An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:CommandPalette authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [behavior, theming, accessibility] verified_by: [ packages/core/src/CommandPalette/CommandPalette.test.tsx, packages/core/src/CommandPalette/CommandPaletteInput.test.tsx, packages/core/src/CommandPalette/CommandPaletteList.test.tsx, packages/core/src/CommandPalette/CommandPaletteItem.test.tsx, packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx, packages/core/src/CommandPalette/CommandPaletteFooter.test.tsx, packages/core/src/CommandPalette/tests/CommandPalette.a11y.chromium.spec.ts, packages/core/src/CommandPalette/tests/CommandPaletteFooter.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, ] modules: [] families: [family:overlay-dismissal] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:interaction-modality, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-056, spec:AST-092/FR9]
CommandPalette component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | CommandPalette with its documented props and slots, composed from CommandPaletteInput, CommandPaletteList, CommandPaletteItem, CommandPaletteGroup, CommandPaletteEmpty, and CommandPaletteFooter, inside a Dialog. |
| Behavior | Searchable commands in a Dialog: a combobox query field, a listbox of results only while selectable results exist, an empty message otherwise, and a keyboard-guidance footer. Modal Escape belongs to Dialog's shared dismissal. |
| End-user impact | Keyboard and screen-reader users search and run commands with native text editing kept intact, hear the empty message that is shown, and close nested layers one Escape at a time. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no public change. AR1's caller aria-label rule is an implementation gap in component:CommandPaletteList, listed in its Current-state impact; two owner questions stay open (OQ2 asks whether INV5 should state this composite-semantics reading family-wide). |
| Review checks | Reject local modal Escape handling, IME routing, Home/End result navigation, empty listboxes, stale active descendants, placeholder-only names, mismatched Empty announcements, or gaps. |
| Governing rules | family:overlay-dismissal/FR1, FR2, FR4, FR5; spec:AST-056/FR3, AR1, AR2; spec:AST-092/FR9 (its outcome only; FR10); existing public component and delegated-owner contracts. |
This table is a review projection; the body below is authoritative.
Intent
CommandPalette presents searchable commands inside a Dialog. It owns search and selection orchestration plus the aggregate consumer anatomy while delegating its surface and modal dismissal ordering to Dialog.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: as documented in
CommandPalette.doc.mjs - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- The List replaces a caller's name (AR1). A builder's explicit
aria-labeldoes not name the List today;component:CommandPaletteListrecords the gap.
Ownership boundary
Owns
- Search orchestration and composition of the current Input, List, Item, Group, Group heading, Empty, and Footer parts and targets.
- Composition of the native Query field rendered inside the default Input; the field's semantics and native passthrough are owned by
component:CommandPaletteInput.
Does not own / non-goals
- Dialog's surface, Icon's glyph, Spinner's loading indicator, or Kbd's shortcut badges — owned by their respective components.
- Caller-provided replacement Input, Footer, item content, or trailing input content — owned by the product callsite.
- The Item option's passthrough, pointer, disabled, selected, highlighted, and
standalone-scroll semantics — owned by
component:CommandPaletteItem. - A
command-paletteroot target — no such target exists. - Shared layer hosting, positioning, or lifecycle rules beyond the current records linked below.
- The List root's accessible name, list-id application, native passthrough, and
overflow scrolling — owned by
component:CommandPaletteList. - The Group's role, name, and heading — owned by
component:CommandPaletteGroup; the Footer's guidance — owned bycomponent:CommandPaletteFooter; the Empty surface — owned bycomponent:CommandPaletteEmpty.
Public concepts
No new public concept is introduced. Consumer props, slots, and usage remain
documented in CommandPalette.doc.mjs and its subcomponent docs.
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The default render places Input and Footer around a result surface inside a delegated Dialog. That surface is a List listbox while Items exist and an ordinary Empty container otherwise. Before the first query's result is committed, while that query is pending, the result surface keeps the Empty container's size and shows no message; once an answer is committed, a later pending query keeps the current results or the search-empty message until its own result commits (the "Pending search" state row; component:CommandPaletteEmpty FR2). The default Footer renders only when footer is omitted, null, or undefined; any other footer replaces it, so footer={false} shows no Footer guidance while the Footer area keeps its divider (architecture:react-component-runtime INV16). |
Current source, docs, tests, and ARIA required-child rule |
| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current command-palette-* targets documented below; no command-palette root target exists. |
Current source and target docs |
| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog. | Current source and component docs |
| FR4 | Query field is a distinct native text field inside Input and has no separate public target. The command-palette-input target is on the surrounding search region, not the native field. |
Current source and target docs |
| FR5 | A modal palette leaves Escape unclaimed for Dialog's shared dismissal stack so a nested member handles the first press; inline previews close locally because they do not register as layers. | family:overlay-dismissal/FR1, FR2, FR4, FR5 |
| FR6 | The editable query field keeps Home and End for native caret movement, uses PageUp and PageDown for first/last result navigation, and does not route active IME composition keys to commands. | WAI-ARIA editable combobox convention; objective IME integrity |
| FR7 | A committed result set resets highlight before exposure; the query input emits active-descendant only for an index that exists in the current selectable set. | WAI-ARIA active-descendant integrity |
| FR8 | Empty search announcements mirror rendered emptySearchText, including rich caller content; the query input's default accessible name is independent of its placeholder. |
spec:AST-056/FR3, AR1, AR2 |
| FR10 | A rejected search() settles as an empty answer and shows the empty-result state, as a typeahead's failed answer with nothing shown does; a rejected bootstrap() settles as no initial items and shows the initial empty state. Neither throws to an error boundary. |
Consistency with the outcome spec:AST-092/FR9 requires of typeaheads. |
Allowed variation
- AV1 — Results. Item count, grouping, selected content, and empty state may vary without changing the aggregate anatomy.
- AV2 — Slots. Caller-provided Input and Footer content may replace the defaults without becoming CommandPalette-owned subparts.
- AV3 — Delegated rendering. Dialog, Icon, Spinner, and Kbd may change their internal element shape while preserving their own public contracts.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Ungrouped results | List contains Item instances. | Item count and caller-rendered content. |
| Grouped results | List contains Group, Group heading, and Item instances. | Group names, count, ordering, and item content. |
| Empty bootstrap/search | Empty replaces listbox semantics; search-empty text is announced as rendered. | Caller-provided rich content, including ordinary controls. |
| Pending search | Default Input may contain Loading spinner. | Spinner is absent when no search is pending. |
| Default slots | Input and Footer render their documented defaults. | Footer shortcut text and translated labels. |
| Caller-replaced slots | The slot content replaces the corresponding default. | Replacement structure remains caller-owned. |
Transformation and precedence order
- No search, selection, layout, or styling precedence rule beyond FR1–FR10.
Performance and resources
- No resource rule.
Accessibility contract
- AR1 — Named composite. The containing Dialog, combobox, populated listbox,
groups, options, busy status, empty state, and keyboard guidance preserve their
owned accessible names and roles. A caller's explicit
aria-labelnames a List or Group (architecture:public-component-apiINV5); thelistboxandoptionroles and option state stay component-owned, ascomponent:CommandPaletteInputAR3 records.component:CommandPaletteListrecords where today's List replaces a caller's name. When no selectable results exist, the result surface and combobox omit listbox, expanded, controls, and active-descendant semantics so rich Empty content stays ordinary non-nested content. - AR2 — Topmost Escape. A modal palette delegates unclaimed Escape presses to Dialog's shared dismissal stack. A nested registered surface handles the first press; the host palette remains open until it becomes topmost.
- AR3 — Inline preview. Documentation-only inline rendering remains outside the shared layer stack and preserves its local Escape close behavior.
- AR4 — Editable query keys. Home and End preserve native caret movement; PageUp and PageDown navigate to the first and last results; active IME composition keys remain owned by the input method.
- AR5 — Rendered empty message. A search dead end announces the text rendered
by
emptySearchText, including text produced by caller components and links. - AR6 — Query-field name. The default query field name is a localized
"Search commands" label independent of its placeholder; caller
labeland nativearia-labeloverrides remain supported. - AR7 — Existing active option. Result changes reset highlight, and
aria-activedescendantis present only when the indexed option exists in the current selectable set.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Dialog | Presents the containing modal surface. | component:Dialog |
Supporting | FR1, FR3 |
| Input | Paints the search region around the query field and supporting visuals. | Current source and public docs | Prominent | FR1, FR2, FR4 |
| Search glyph | Presents the search symbol in the default Input. | component:Icon |
Supporting | FR3 |
| Query field | Accepts the native text query inside Input. | Current source and public docs | Prominent | FR1, FR4 |
| Loading spinner | Indicates a pending search in the default Input. | component:Spinner |
Supporting | FR3 |
| List | Presents the current result collection or Empty state. | Current source and public docs | Supporting | FR1, FR2 |
| Item | Presents one selectable command result. | Current source and public docs | Prominent | FR1, FR2 |
| Group | Arranges related Items together. | Current source and public docs | Supporting | FR1, FR2 |
| Group heading | Labels one Group visually. | Current source and public docs | Supporting | FR1, FR2 |
| Empty | Presents the no-results or no-query message. | Current source and public docs | Prominent | FR1, FR2 |
| Footer | Presents default guidance or caller-provided footer content. | Current source and public docs | Supporting | FR1, FR2 |
| Keyboard shortcut | Presents one shortcut as painted key badges in the default Footer. | component:Kbd |
Supporting | FR3 |
The native Query field is separate from the Input region that carries
command-palette-input. It has no direct target; whether it should is OQ1.
Theming anatomy
{
"Dialog": {
"delegatesTo": {"owner": "component:Dialog", "target": "dialog"}
},
"Input": {"target": "command-palette-input"},
"Search glyph": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Query field": {
"none": {
"reason": "unsettled: No current public target is applied directly to the native query field; future exposure still needs an owner decision"
}
},
"Loading spinner": {
"delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
},
"List": {"target": "command-palette-list"},
"Item": {"target": "command-palette-item"},
"Group": {"target": "command-palette-group"},
"Group heading": {"target": "command-palette-group-heading"},
"Empty": {"target": "command-palette-empty"},
"Footer": {"target": "command-palette-footer"},
"Keyboard shortcut": {
"delegatesTo": {"owner": "component:Kbd", "target": "kbd"}
}
}
The seven local targets are current public seams. The delegated parts retain
their existing component owners. The Query field none disposition is
unsettled (OQ1) and does not authorize a new target.
Family and system relationships
architecture:component-theming-surfaceowns anatomy qualification, target mapping, delegation, and factualnonedispositions.architecture:public-component-apiowns the stable props and composition surface.architecture:interaction-modality/INV4owns supported-modality path reachability; the exact query-key details follow objective editable-combobox and IME composition standards.spec:AST-056/FR3,AR1, andAR2own rendered empty-search announcement parity and an accessible query-field name independent of placeholder text.family:overlay-dismissalowns topmost Escape and close-request ordering; CommandPalette adopts it through Dialog while preserving local inline-preview closing because inline mode does not register as a layer.architecture:layer-runtimerecords that the modal path delegates Escape to Dialog's shared dismissal registration while the unregistered inline preview preserves local closing.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | CommandPalette root and subcomponent suites; CommandPalette.test.tsx pending-state cases; CommandPalettePending.a11y.chromium.spec.ts (pending keeps the empty surface's height) |
Default, grouped, empty, pending, rich Empty, and replaced slots | Exposing an empty listbox, leaving empty Input popup attributes, or nesting rich Empty controls under option semantics fails focused role assertions. Evidence gap: FR1's footer rule (the default footer only when footer is omitted, null, or undefined; footer={false} leaves an empty footer bar) is source-inspected; no test passes footer={false}. |
audit:CommandPalette/anatomy |
| FR2 | Focused subcomponent suites and themingTargets.test.ts |
Seven local targets at their owned elements | Removing or moving a current target fails a focused placement assertion or the global inventory. | audit:CommandPalette/theming |
| FR3 | CommandPaletteInput.test.tsx and CommandPaletteFooter.test.tsx |
Default Search glyph, pending spinner, and Footer Kbd | Replacing or removing the delegated Icon, Spinner, or Kbd instance fails a composed-owner assertion. | audit:CommandPalette/theming |
| FR4 | CommandPaletteInput.test.tsx |
Native query field with idle and pending Input | Removing the field fails combobox tests; adding a field target requires an explicit map update. | audit:CommandPalette/anatomy |
| FR5, AR2, AR3 | CommandPalette.test.tsx |
Modal host with nested layer; inline preview | Restoring local modal Escape handling closes the host instead of the nested surface; removing the inline branch loses preview closing. | audit:CommandPalette/interaction |
| FR6, AR4 | CommandPalette.test.tsx and CommandPaletteInput.test.tsx |
Home, End, PageDown, Enter, and active IME composition | Routing Home/End to results or forwarding a composing command key fails user-event and native composition assertions. | audit:CommandPalette/interaction |
| FR7, AR7 | CommandPalette.test.tsx and CommandPaletteInput.test.tsx |
Populated, empty, and repopulated result sets | Preserving an out-of-range highlight or emitting its nonexistent active descendant fails transition and direct bounds assertions. | audit:CommandPalette/a11y |
| FR8, AR5, AR6 | CommandPalette.test.tsx, CommandPaletteInput.test.tsx, and i18n checks |
Rich caller Empty content; default and caller query names | Announcing catalog copy over rendered caller content or naming the query only through placeholder text fails live-region, name, and catalog assertions. | audit:CommandPalette/a11y |
| FR10 | CommandPalette.test.tsx "a rejected search source" suite |
Bootstrap rejects; a search rejects or throws; a superseded query rejects | A rejection that reaches an error boundary, leaves the busy state on, keeps stale rows, or lets a superseded query clear the current results fails. | audit:CommandPalette/interaction |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and seven current local targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. Gap: no check fails if a mapped part stops painting. | audit:CommandPalette/theming |
Focused target-placement assertions cover all seven local targets. The composed Input and Footer tests also pin the delegated Search Icon, pending Spinner, and four default Kbd shortcuts.
Decision log
No component-local decision is recorded.
Open questions
- OQ1 — Should Query field gain a stable public theming target? (
human-api) It has no direct target today, and no owner has decided whether it should. - OQ2 — Should
architecture:public-component-apiINV5 state the composite-semantics reading family-wide? (human-api) Inside a composite such as CommandPalette, roles likecombobox,listbox, andoptionand option state are component-owned and replace a caller's, ascomponent:CommandPaletteInputAR3 records, while a caller's explicit name still wins. Stating it in INV5 would make every composite follow it; leaving it here keeps it a CommandPalette reading that other composites may not share.
Content boundary
This file does not duplicate consumer prop tables/examples, shared layer or modality rules, or implementation steps. It links to their owners.