Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): CommandPalette records its shipped contract as current (#9306)

Cindy Zhang27ccfe043b3a
diff --git a/docs/specs/components/CommandPalette/CommandPalette.spec.md b/docs/specs/components/CommandPalette/CommandPalette.spec.md
index 4dff2ab531..cf2b3ee252 100644
--- a/docs/specs/components/CommandPalette/CommandPalette.spec.md
+++ b/docs/specs/components/CommandPalette/CommandPalette.spec.md
@@ -3,11 +3,11 @@ schema_version: 3
template_version: 7
kind: component
id: component:CommandPalette
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-11-01
owners: [cixzhang]
review_triggers: [behavior, theming, accessibility]
verified_by:
@@ -40,15 +40,15 @@ system_specs: [spec:AST-056]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | Prop and visual APIs are unchanged. The result surface exposes listbox semantics only with selectable results; the query input has a real default name; rich Empty content remains ordinary. |
-| Behavior | Modal Escape delegates to Dialog; query-field Home/End and IME remain native; result changes reset stale highlight; Empty announcements mirror rendered content. |
-| End-user impact | Nested dismissal and native text entry are preserved; assistive technology receives the visible empty message, an independent query-field name, and only existing active options. |
-| Builder impact | None; no migration or new caller choice. |
-| Compatibility/readiness | Visual output is preserved. Empty-result ARIA, query-field accessible naming, empty-state announcement, and highlight reset behavior are corrected and verified. |
-| 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`; existing public component and delegated-owner contracts. |
+| 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`; existing public component and delegated-owner contracts. |
This table is a review projection; the body below is authoritative.
@@ -60,19 +60,19 @@ surface and modal dismissal ordering to Dialog.
## Compatibility and migration
-- Released default preserved: `yes` for props and visual output
-- Compatibility class: behavioral and accessibility correction; empty states
- conditionally omit listbox, expanded, controls, and active-descendant ARIA
- attributes until selectable results exist; the default query accessible name
- is independent of its placeholder; empty-search announcements mirror the
- rendered content; public props, styling, targets, and visible defaults remain
- unchanged
-- Controlled/uncontrolled behavior: unchanged
-- Migration decision: adopts `family:overlay-dismissal/FR1`, `FR2`, `FR4`, and
- `FR5` through Dialog; no caller 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-label` does not name the List today; `component:CommandPaletteList`
+ records the gap.
+
## Ownership boundary
**Owns**
@@ -89,12 +89,14 @@ Consumer migration instructions belong in consumer docs and release notes.
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-palette` root target — no such current target exists, and this
- factual backfill does not invent one.
+- A `command-palette` root 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 by `component:CommandPaletteFooter`; the Empty
+ surface — owned by `component:CommandPaletteEmpty`.
## Public concepts
@@ -103,16 +105,16 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| FR1 | The current 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. | Current source, docs, tests, and ARIA required-child rule | Verified current anatomy and valid rich Empty semantics |
-| 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 | Verified current inventory and focused placement coverage |
-| 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 | Verified current composition; no ownership change |
-| FR4 | Query field is a distinct native text field inside Input and currently 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 | Verified current reachability; long-term theming intent remains unsettled |
-| 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` | Verified by nested and inline integration tests |
-| 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 | Verified by user-event navigation and composition-key tests |
-| 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 | Verified across populated, empty, and repopulated results |
-| 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` | Verified by live-region and accessible-name tests |
+| 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. | 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` |
### Allowed variation
@@ -136,17 +138,21 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.
### Transformation and precedence order
-- No new search, selection, layout, or styling precedence rule is introduced.
+- No search, selection, layout, or styling precedence rule beyond FR1–FR8.
### Performance and resources
-- No new performance or resource rule is introduced.
+- 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. When no selectable results exist, the result
+ owned accessible names and roles. A caller's explicit `aria-label` names a List or
+ Group (`architecture:public-component-api` INV5); the `listbox` and `option`
+ roles and option state stay component-owned, as
+ `component:CommandPaletteInput` AR3 records. `component:CommandPaletteList`
+ records 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
@@ -184,8 +190,7 @@ documented in `CommandPalette.doc.mjs` and its subcomponent docs.
| 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`. Its current lack of a direct target is observed
-reachability, not a decision that it must remain unthemeable.
+`command-palette-input`. It has no direct target; whether it should is OQ1.
### Theming anatomy
@@ -221,15 +226,15 @@ reachability, not a decision that it must remain unthemeable.
```
The seven local targets are current public seams. The delegated parts retain
-their existing component owners. The Query field `none` disposition records a
-current audit gap and does not authorize a new target.
+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-surface` owns anatomy qualification, target
mapping, delegation, and factual `none` dispositions.
- `architecture:public-component-api` owns the stable props and composition
- surface; this documentation adds no API.
+ surface.
- `architecture:interaction-modality/INV4` owns supported-modality path
reachability; the exact query-key details follow objective editable-combobox
and IME composition standards.
@@ -244,35 +249,41 @@ current audit gap and does not authorize a new target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1, AR1 | CommandPalette root and subcomponent suites plus exact-head Chromium evidence | 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 and hosted axe assertions. | `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`, `CommandPaletteFooter.test.tsx`, and browser evidence | Default Search glyph, pending spinner, and Footer Kbd | Replacing or removing the delegated Icon, Spinner, or Kbd instance fails a composed-owner assertion and changes the exact-head evidence inventory. | `audit:CommandPalette/theming` |
-| FR4 | `CommandPaletteInput.test.tsx` and source inspection | 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` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` and exact-head Chromium evidence | Canonical anatomy and seven current local targets | Missing, extra, prefixed, stale, alias-backed, or visually absent mappings fail repository validation or browser sensor counts. | `audit:CommandPalette/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1, AR1 | CommandPalette root and subcomponent suites | 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. | `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` |
+| 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; exact-head browser evidence verifies the same owned
-anatomy across light, dark, LTR, RTL, and narrow rendering.
+four default Kbd shortcuts.
## Decision log
-None. This draft records current facts and introduces no component-local design,
-layer, API, or theming decision.
+No component-local decision is recorded.
## Open questions
- **OQ1 — Should Query field gain a stable public theming target?** (`human-api`)
- Its current lack of direct reachability is an audit gap, not settled intent.
+ It has no direct target today, and no owner has decided whether it should.
+- **OQ2 — Should `architecture:public-component-api` INV5 state the
+ composite-semantics reading family-wide?** (`human-api`) Inside a composite
+ such as CommandPalette, roles like `combobox`, `listbox`, and `option` and
+ option state are component-owned and replace a caller's, as
+ `component:CommandPaletteInput` AR3 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, current audit results, or implementation steps. It links to
+modality rules, or implementation steps. It links to
their owners.
diff --git a/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md b/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md
index cd324b8612..1ec47de01b 100644
--- a/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md
+++ b/docs/specs/components/CommandPalette/CommandPaletteEmpty.spec.md
@@ -3,11 +3,11 @@ schema_version: 3
template_version: 7
kind: component
id: component:CommandPaletteEmpty
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-11-01
owners: [cixzhang]
review_triggers: [public-api, behavior, theming, accessibility, testing]
verified_by:
@@ -42,8 +42,8 @@ system_specs: [spec:AST-029, spec:AST-056]
| Public contract | `CommandPaletteEmpty` / `CommandPaletteEmptyProps`: required `children`, `BaseProps<HTMLDivElement>`, and a root `ref`. |
| Behavior | One ordinary container centers caller content as supporting text. CommandPalette renders it for the no-query and no-results branches; it owns no role, state, announcement, or interaction. |
| End-user impact | People who reach a palette dead end read the message, and any caller link stays ordinary reachable content rather than an option. |
-| Builder impact | None. Caller content, host attributes, and styling inputs compose on the root. |
-| Compatibility/readiness | Observational patch contract. Runtime behavior, exports, and the target name are unchanged; authority stays `draft` until exact-head owner approval. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Evidence still pending for the claims listed as read from source. |
| Review checks | Reject a component-owned role or live region, option semantics around caller content, dropped root inputs, a target moved off the painted root, or content that overflows its host inline axis. |
| Governing rules | `architecture:public-component-api/INV1,INV5–INV8`; `architecture:component-theming-surface/INV2–INV6`; `spec:AST-056/FR3`, `AR1` for the parent's announcement; WCAG 2.2 SC 1.4.3 and 1.4.10. |
@@ -61,8 +61,8 @@ Consumer syntax and examples belong in `CommandPaletteEmpty.doc.mjs`.
## Compatibility and migration
-- Released default preserved: yes — one centered, ordinary message container.
-- Compatibility class: observational patch; no public surface changes.
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: not applicable.
- Migration decision: none.
@@ -97,17 +97,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------ |
-| FR1 | The component MUST render its children inside one container element that centers them on both axes with centered text, supporting type, body font family, and secondary text color. | Current source, consumer docs, and focused tests | verify |
-| FR2 | CommandPalette MUST render this component with `emptyBootstrapText` when there is no query and no result, and with `emptySearchText` when a query has no result. | Current CommandPalette source and tests | verify |
-| FR3 | The root MUST carry no component-owned role, live region, or focus stop, so caller links and controls remain ordinary content. | WAI-ARIA 1.2 listbox owned-children rule; current source and Chromium evidence | verify |
-| FR4 | Caller text MUST wrap inside the host's inline size, including a single unbroken token, so no message forces inline scrolling or clipping at 320 CSS px. | WCAG 2.2 SC 1.4.10; Chromium evidence | verify |
-| FR5 | The painted root MUST carry the `command-palette-empty` target; component styles apply before caller `xstyle`. | `architecture:component-theming-surface/INV2–INV6`; source and focused tests | verify |
-| FR6 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the root. | `architecture:public-component-api/INV5–INV8`; focused tests | verify |
+| ID | Invariant | Basis |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| FR1 | The component MUST render its children inside one container element that centers them on both axes with centered text, supporting type, body font family, and secondary text color. | Current source, consumer docs, and focused tests |
+| FR2 | CommandPalette MUST render this component with `emptyBootstrapText` when there is no query and no result, and with `emptySearchText` when a query has no result. | Current source and tests |
+| FR3 | The root MUST carry no component-owned role, live region, or focus stop, so caller links and controls remain ordinary content. | WAI-ARIA 1.2 listbox owned-children rule; current source and tests |
+| FR4 | Caller text MUST wrap inside the host's inline size, including a single unbroken token, so no message forces inline scrolling or clipping at 320 CSS px. | WCAG 2.2 SC 1.4.10; current source |
+| FR5 | The painted root MUST carry the `command-palette-empty` target; component styles apply before caller `xstyle`. | `architecture:component-theming-surface/INV2–INV6`; source and focused tests |
+| FR6 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the root. | `architecture:public-component-api/INV5–INV8`; focused tests |
### Allowed variation
@@ -147,11 +144,12 @@ intentional decision.
## Design relationships
-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------- | ------------------ |
-| Empty message | Presents the dead-end message as supporting text centered in the results. | Current source tokens; no component-local visual decision settled | supporting | FR1, FR4, FR5 |
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Empty message | Presents the dead-end message as supporting text centered in the results. | Current source tokens | supporting | FR1, FR4, FR5 |
-No component-local visual decision is settled by this draft.
+No component-local design decision is recorded. The aggregate CommandPalette
+anatomy map, owned by `component:CommandPalette`, maps the Empty part.
## Family and system relationships
@@ -161,23 +159,29 @@ No component-local visual decision is settled by this draft.
evidence.
- `spec:AST-056/FR3` and `AR1` require CommandPalette to announce the
empty-search message it rendered; this component supplies the rendered node.
-- CommandPalette and CommandPaletteList draft records describe the parent
- branches and empty result surface; they are observational context, not
- authority for this contract.
-- `spec:AST-029` keeps this observational draft separate from the audit receipt.
+- `component:CommandPalette` and `component:CommandPaletteList` own the parent
+ branches and the empty result surface.
+- `spec:AST-029` owns the audit evidence inventory this record's verification
+ map follows.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| FR1, FR5–FR6 | `CommandPaletteEmpty.test.tsx`; `themingTargets.test.ts` | text and element children; root inputs | A dropped input, a moved target, or lost children fails the focused assertions. | `audit:CommandPaletteEmpty/§2,§3,§4` |
-| FR2, FR3, AR1 | `CommandPalette.test.tsx`; `CommandPaletteList.test.tsx`; exact-head Chromium receipts | bootstrap, search, rich content, modal and inline | Exposing a listbox, adding a role, or announcing other text than the rendered message fails assertions. | `audit:CommandPaletteEmpty/§1,§4` |
-| FR4, AR2 | Exact-head Chromium receipts and contrast pairs | long and translated text; 320 px; themes and modes | Inline overflow or clipping fails the reflow sensor; ratios are recorded per frame. | `audit:CommandPaletteEmpty/§5,§10` |
-| PR1 | Source review and the presentational lint rule | every state | A hook or lifecycle mechanism fails the lint rule. | `audit:CommandPaletteEmpty/§7` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1, FR5–FR6 | `CommandPaletteEmpty.test.tsx`; `themingTargets.test.ts` | text and element children; root inputs | A dropped input, a moved target, or lost children fails the focused assertions. | `audit:CommandPaletteEmpty/§2,§3,§4` |
+| FR2, FR3, AR1 | `CommandPalette.test.tsx`; `CommandPaletteList.test.tsx` | bootstrap, search, rich content, modal and inline | Exposing a listbox, adding a role, or announcing other text than the rendered message fails assertions. | `audit:CommandPaletteEmpty/§1,§4` |
+| FR4, AR2 | `CommandPaletteEmptyAudit.a11y.chromium.spec.ts` | Narrow and wide viewports; light and dark; forced colors; rich content | A case with horizontal overflow at 320 CSS px fails the audit manifest test. Gap: the audit records message contrast without gating on it, so contrast below 4.5:1 does not fail. | `audit:CommandPaletteEmpty/accessibility` |
+| PR1 | Source review | Every state | Gap: no automated check fails if CommandPaletteEmpty adds a hook, listener, or Effect. | `audit:CommandPaletteEmpty/behavior` |
+
+Read from source, with no focused test yet:
+
+- FR1: centering, supporting type, body font, and secondary text color.
+- AR2: message contrast in each theme and mode.
+- PR1: no hook, listener, or lifecycle of the component's own.
## Decision log
-None. This draft records current facts and introduces no product decision.
+No component-local decision is recorded.
## Open questions
@@ -185,6 +189,5 @@ None.
## Content boundary
-This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or system rules. The audit pull request
-owns the closed run evidence required by `spec:AST-029/FR5`.
+This file does not duplicate consumer prop tables/examples, implementation
+steps, or system rules. It links to their owners.
diff --git a/docs/specs/components/CommandPalette/CommandPaletteFooter.spec.md b/docs/specs/components/CommandPalette/CommandPaletteFooter.spec.md
new file mode 100644
index 0000000000..8273ed6bb1
--- /dev/null
+++ b/docs/specs/components/CommandPalette/CommandPaletteFooter.spec.md
@@ -0,0 +1,150 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:CommandPaletteFooter
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-11-01
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming]
+verified_by:
+ [
+ packages/core/src/CommandPalette/CommandPaletteFooter.test.tsx,
+ packages/core/src/CommandPalette/__tests__/CommandPaletteFooter.a11y.chromium.spec.ts,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# CommandPaletteFooter component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `CommandPaletteFooter` with optional `children`, `ref`, `xstyle`, `className`, `style`, and root DOM props. |
+| Behavior | A footer row of keyboard guidance: by default, the navigate, select, and close shortcuts with translated labels; `children` replace them. |
+| End-user impact | People see which keys move through, run, and close the palette. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. |
+| Review checks | Reject a footer that takes a role or name of its own, a lost default shortcut, or guidance that cannot wrap. |
+| Governing rules | `component:Kbd`; `architecture:public-component-api`; `architecture:component-theming-surface`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+CommandPaletteFooter is the guidance row at the bottom of a CommandPalette.
+Consumer usage lives in `CommandPaletteFooter.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The footer root, its layout, supporting text style, and the
+ `command-palette-footer` target (FR1, FR3).
+- The default guidance and its replacement by `children` (FR2).
+- Root ref, DOM props, and styling (FR4).
+
+**Does not own / non-goals**
+
+- Painting each shortcut — owned by `component:Kbd`.
+- The keyboard behavior the guidance describes — owned by
+ `component:CommandPalette`.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is a wrapping row of supporting text in the secondary color, with no role or name of its own. | Current source and tests |
+| FR2 | Without `children`, the root shows three hints in order: Up and Down with the translated navigate label, Enter with select, and Escape with close, each shortcut a `Kbd`. `children` replace all three. | Current source and tests |
+| FR3 | The root carries the `command-palette-footer` target. | Current source and tests |
+| FR4 | `ref`, DOM props, `className`, `style`, and `xstyle` reach the root, with the caller's class after the generated ones. | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Guidance.** Callers may replace the default hints.
+- **AV2 — Translation.** Label text follows the active locale.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| -------------- | ------------------------------------------- | ----------------- |
+| Default | Navigate, select, and close hints in order. | Locale. |
+| Custom | `children` replace the defaults. | Content. |
+| Narrow surface | Hints wrap onto more lines. | Line count. |
+
+### Transformation and precedence order
+
+- **ORD1 — Content.** `children` when given, otherwise the default hints.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — No owned semantics.** The footer adds no role, name, or focus
+ target; each shortcut's semantics are Kbd's.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ----------------- | -------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Footer | A wrapping row of supporting guidance. | Current source | Supporting | FR1, FR3 |
+| Keyboard shortcut | Shows one shortcut. | `component:Kbd` | Supporting | FR2 |
+
+The aggregate CommandPalette anatomy map, owned by `component:CommandPalette`,
+maps the Footer and Keyboard shortcut parts.
+
+## Family and system relationships
+
+- `component:Kbd` owns shortcut painting and semantics.
+- `component:CommandPalette` owns the keyboard behavior the guidance names.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | --------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------- | --------------------------------------- |
+| FR1, AR1 | `CommandPaletteFooter.test.tsx` wrap test; `CommandPaletteFooter.a11y.chromium.spec.ts` | narrow; LTR and RTL | A role or name on the root, or no wrapping, fails. | `audit:CommandPaletteFooter/layout` |
+| FR2 | `CommandPaletteFooter.test.tsx` default-labels and custom-children tests | default; custom | A lost hint or ignored children fails. | `audit:CommandPaletteFooter/behavior` |
+| FR3 | `CommandPaletteFooter.test.tsx` "carries the stable theme target on its single root" | any | A missing target fails. | `audit:CommandPaletteFooter/theming` |
+| FR4 | `CommandPaletteFooter.test.tsx` className, xstyle, style, ref, and DOM-prop tests | root inputs | A dropped input fails. | `audit:CommandPaletteFooter/public-api` |
+
+Read from source, with no focused test yet:
+
+- FR1: the supporting type and secondary color.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, or
+CommandPalette's search and keyboard behavior. It links to their owners.
diff --git a/docs/specs/components/CommandPalette/CommandPaletteGroup.spec.md b/docs/specs/components/CommandPalette/CommandPaletteGroup.spec.md
new file mode 100644
index 0000000000..5957d2bf67
--- /dev/null
+++ b/docs/specs/components/CommandPalette/CommandPaletteGroup.spec.md
@@ -0,0 +1,155 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:CommandPaletteGroup
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-11-01
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming]
+verified_by:
+ [
+ packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# CommandPaletteGroup component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract | `CommandPaletteGroup` with a required string `heading`, `children`, `ref`, `xstyle`, `className`, `style`, and root DOM props. |
+| Behavior | A `group` of command results named by `heading`, with the heading shown as a visual label above them. |
+| End-user impact | Related commands appear under a visible heading, and screen-reader users hear the group's name when they move into it. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. |
+| Review checks | Reject an unnamed group, a heading read twice, or a heading target that merges with the group target. |
+| Governing rules | `component:CommandPalette`; `architecture:public-component-api` INV5; `architecture:component-theming-surface`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+CommandPaletteGroup gathers related command results under a heading inside a
+CommandPalette list. Consumer usage lives in `CommandPaletteGroup.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+None.
+
+## Ownership boundary
+
+**Owns**
+
+- The group root, its role and name, and the `command-palette-group` target
+ (FR1, FR3).
+- The visual heading and its `command-palette-group-heading` target (FR2, FR3).
+- Root ref, DOM props, and styling (FR4).
+
+**Does not own / non-goals**
+
+- Option semantics and activation — owned by `component:CommandPaletteItem`.
+- The list, search, and keyboard navigation — owned by
+ `component:CommandPalette` and `component:CommandPaletteList`.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root has `role="group"` and is named by `heading` through `aria-label`, unless the caller supplies its own `role` or `aria-label` (FR4), and lays its heading and children out in one column. | Current source and tests |
+| FR2 | The heading renders `heading` as supporting text before the children and is hidden from assistive technology, so the name is read once. | Current source and tests |
+| FR3 | The root carries `command-palette-group` and the heading carries the separate `command-palette-group-heading` target. | Current source and tests |
+| FR4 | `ref`, DOM props, `className`, `style`, and `xstyle` reach the root, and a caller's explicit `role` or `aria-label` reaches it (`architecture:public-component-api` INV5). | Current source |
+
+### Allowed variation
+
+- **AV1 — Content.** The heading text and the grouped items vary.
+- **AV2 — Theme.** Themes restyle the group and the heading separately.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| --------------- | ------------------------------------------- | ----------------- |
+| Grouped results | A named group with a hidden visual heading. | Items. |
+
+### Transformation and precedence order
+
+- No precedence rule.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Named group.** The group is named by `heading` (FR1), unless the
+ caller supplies its own `aria-label` (FR4).
+- **AR2 — One reading.** The visual heading is hidden from assistive
+ technology, so the name is not repeated (FR2).
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Group | Gathers related results in one column. | Current source | Supporting | FR1, FR3 |
+| Group heading | Labels the group with supporting text. | Current source | Supporting | FR2, FR3 |
+
+The aggregate CommandPalette anatomy map, owned by `component:CommandPalette`,
+maps the Group and Group heading parts to these targets.
+
+## Family and system relationships
+
+- `component:CommandPalette` owns the aggregate anatomy and the composite
+ keyboard model; `component:CommandPaletteItem` owns the options inside.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | ----------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1, AR1 | `CommandPaletteGroup.test.tsx` "has group role with aria-label" | grouped results | A missing role or name fails. | `audit:CommandPaletteGroup/accessibility` |
+| FR2, AR2 | `CommandPaletteGroup.test.tsx` heading, `aria-hidden`, and decorative-heading tests | grouped results | A heading exposed to assistive technology fails. | `audit:CommandPaletteGroup/accessibility` |
+| FR3 | `CommandPaletteGroup.test.tsx` heading-target tests; `themingTargets.test.ts` | grouped results | A missing or merged target fails. | `audit:CommandPaletteGroup/theming` |
+| FR4 | Source review | Caller inputs | Gap: no test covers `ref`, DOM props, `className`, `style`, `xstyle`, or a caller `role` or `aria-label`. | `audit:CommandPaletteGroup/api` |
+
+Read from source, with no focused test yet:
+
+- FR1: the one-column layout.
+- FR4: `ref`, DOM props, `className`, `style`, and `xstyle` on the root.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, or
+CommandPalette's search and keyboard behavior. It links to their owners.
diff --git a/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md b/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md
index 45e435538b..d90a5a937f 100644
--- a/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md
+++ b/docs/specs/components/CommandPalette/CommandPaletteItem.spec.md
@@ -3,11 +3,11 @@ schema_version: 3
template_version: 7
kind: component
id: component:CommandPaletteItem
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-11-01
owners: [cixzhang]
review_triggers: [behavior, accessibility, public-api, compatibility, theming]
verified_by:
@@ -42,8 +42,8 @@ system_specs: [spec:AST-017, spec:AST-020]
| Public contract | One result option with context-backed identity, highlight, selection, and close behavior; explicit standalone visual state and pointer activation remain available. |
| Behavior | Consumer click runs first; cancellation stops selection; successful activation reports locally, updates context, and closes; disabled items run no click callbacks. |
| End-user impact | Disabled commands cannot activate, and keyboard focus, selected value, and option identity remain distinct and consistently exposed. |
-| Builder impact | Values stay unique; children stay non-interactive; CommandPalette owns composite keyboard navigation and reports keyboard selection through root `onValueChange`. |
-| Compatibility/readiness | Victim-free `[fix]` restores promised disabled and native-passthrough behavior; the standalone keyboard contract remains unsettled. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact; two owner questions stay open. |
| Review checks | Reject disabled activation, dropped standalone DOM identity, highlight-as-selection ARIA, nested interactive children, or a second context scroll owner. |
| Governing rules | `architecture:public-component-api/INV5,INV7`; `architecture:interaction-modality`; `spec:AST-017/FR1,FR3,FR5`; `spec:AST-020/FR1,FR2`; WAI-ARIA 1.2 `option`. |
@@ -59,21 +59,25 @@ standalone scroll behavior.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: victim-free contract restoration under
- `spec:AST-017/FR1,FR3,FR5`; `isDisabled` already promises a non-interactive
- item and the native `BaseProps` seam already promises standalone DOM props
+- Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: explicit item state still precedes context
state, then the existing false default
-- Migration decision: none for these corrections; OQ1 holds any change to the
- standalone keyboard contract
-- Documentation compatibility: item `onSelect` reports pointer activation only.
- No public runtime path delivers Enter to it — CommandPalette mints rows without
- item callbacks and standalone items have no keyboard owner — so describing
- keyboard selection through root `onValueChange` leaves no released consumer
- behind (`spec:AST-017/FR1,FR5`). OQ1 owns any standalone keyboard path.
+- Migration decision: none; OQ1 holds any change to the standalone keyboard
+ contract. Item `onSelect` reports pointer activation only; keyboard selection
+ is reported through the root's `onValueChange`.
Consumer migration instructions belong in consumer docs and release notes.
+## Current-state impact
+
+- **A standalone option has no keyboard model.** Outside CommandPalette the
+ item exposes `role=option` and pointer activation but no owning listbox
+ keyboard model, so a keyboard user cannot reach or activate it; WAI-ARIA 1.2
+ options belong to a composite that owns their keyboard interaction (AR5, OQ1).
+- **Selected paint hides keyboard highlight.** When an item is both highlighted
+ and selected, the selected background masks the highlighted one, so the
+ keyboard position is not visible on that item (AV2, OQ2).
+
## Ownership boundary
**Owns**
@@ -106,13 +110,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------- |
-| FR1 | Native props and `ref` reach the option root. CommandPalette context owns registered-item id, role, selected state, disabled state, and value marker; standalone caller id persists. | Released source and `architecture:public-component-api/INV5` | Verified by focused DOM tests |
-| FR2 | Pointer activation runs consumer `onClick`, then stops when prevented; otherwise it calls item `onSelect`, then context selection and close. Disabled items run none of those paths. | Released callbacks and disabled promise | Verified; mutation-resistant |
-| FR3 | Explicit `isHighlighted` and `isSelected` precede context-derived values, then false. Highlight paints active state only; selection alone drives `aria-selected`. | Released source, docs, and listbox semantics | State semantics tested; precedence tested; combined paint gap remains OQ2 |
-| FR4 | Context owns highlighted-item scrolling. Outside context, a highlighted item scrolls nearest, except an initially highlighted item inside an inline Dialog does not scroll. | Released source and regression history | Verified by focused Effect tests |
-| FR5 | Children provide the option's label and supporting presentation, without nested interactive descendants. | Option semantics and `spec:AST-020/FR1,FR2` | Documented; exact-head a11y remains a gate |
+| ID | Invariant | Basis |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| FR1 | Native props and `ref` reach the option root. The `option` role, selected state, and disabled state replace a caller's: inside CommandPalette because composite semantics are component-owned and replace passthrough, as `component:CommandPaletteInput` AR3 records, and standalone by this record's own rule. CommandPalette context owns the registered-item id and value marker; a standalone caller id persists. | Current source and tests; `architecture:public-component-api` |
+| FR2 | Pointer activation runs consumer `onClick`, then stops when prevented; otherwise it calls item `onSelect`, then context selection and close. Disabled items run none of those paths. | Current source and tests |
+| FR3 | Explicit `isHighlighted` and `isSelected` precede context-derived values, then false. Highlight paints active state only; selection alone drives `aria-selected`. | Current source, tests, and docs |
+| FR4 | Context owns highlighted-item scrolling. Outside context, a highlighted item scrolls nearest, except an initially highlighted item inside an inline Dialog does not scroll. | Current source and tests |
+| FR5 | Children provide the option's label and supporting presentation, without nested interactive descendants. | Option semantics and `spec:AST-020/FR1,FR2` |
### Allowed variation
@@ -151,29 +155,28 @@ Consumer migration instructions belong in consumer docs and release notes.
## Accessibility contract
-- **AR1 — Option semantics.** The root exposes `role=option`; its content or
+- **AR1 — Option semantics.** The root exposes `role=option` (FR1); its content or
caller label provides the accessible name, and `aria-selected` reports chosen
value rather than visual highlight.
- **AR2 — Composite ownership.** Inside CommandPalette, the query field retains
focus and points to the context-generated item id; CommandPalette owns arrow
navigation and Enter selection under its adopted listbox/combobox model.
- **AR3 — Disabled state.** Disabled items expose `aria-disabled=true` and
- suppress every pointer activation callback. Source inspection confirms the
- interaction overlay is omitted; exact-head browser evidence remains the paint
- gate.
+ suppress every pointer activation callback, and the interaction overlay is
+ omitted.
- **AR4 — Content.** Item children contain no nested button, link, or other
interactive descendant whose semantics would be lost when the `option`
role makes its descendants presentational, following WAI-ARIA 1.2 and
`spec:AST-020/FR1,FR2`.
- **AR5 — Standalone gap.** A standalone option has no owning composite keyboard
- model. OQ1 must settle that public contract before runtime semantics change.
+ model (Current-state impact; OQ1).
## Design relationships
-| Anatomy | Design requirement | Representation authority | Hierarchy role | Component contract |
-| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Item | Paints enabled, highlighted, selected, disabled, and press states on one root. Selected currently masks highlight when both apply (OQ2). | Current source and public docs | Prominent | FR1–FR4, AR1–AR3 |
-| Content | Supplies the option name and non-interactive supporting presentation. | Product callsite | Supporting | FR5, AR1, AR4 |
+| Anatomy | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |
+| Item | Paints enabled, highlighted, selected, disabled, and press states on one root. Selected masks highlight when both apply (OQ2). | Current source and public docs | Prominent | FR1–FR4, AR1–AR3 |
+| Content | Supplies the option name and non-interactive supporting presentation. | Product callsite | Supporting | FR5, AR1, AR4 |
## Family and system relationships
@@ -184,26 +187,31 @@ Consumer migration instructions belong in consumer docs and release notes.
compatibility.
- `architecture:component-theming-surface` owns the aggregate Item anatomy map
and stable `command-palette-item` target.
-- `spec:AST-017` classifies the victim-free corrections and holds OQ1 against
- silent released-contract changes.
+- `spec:AST-017` holds OQ1 against silent released-contract changes.
- `spec:AST-020` supplies accessibility evidence and adopted-pattern boundaries.
- WAI-ARIA 1.2 option semantics make descendants presentational, so interactive
controls do not belong inside this option root.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| FR1, FR3, AR1–AR2 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; context highlighted/selected | Dropped id/ref/native prop, clobberable role/state, or highlight-as-selection fails focused DOM assertions. | `audit:CommandPaletteItem/a11y` |
-| FR2, AR3 | `CommandPaletteItem.test.tsx` | enabled; disabled; consumer-cancelled; contextual | Disabled consumer activation, ignored cancellation, missing local report, selection, or close fails tests. | `audit:CommandPaletteItem/behavior` |
-| FR4 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; inline initial; changed highlight | Lost nearest scrolling, duplicate contextual scrolling, or initial inline scroll fails Effect assertions. | `audit:CommandPaletteItem/behavior` |
-| FR5, AR4 | public docs, dedicated Storybook states, exact-head a11y/browser evidence | label; shortcut; disabled | Interactive descendant guidance regresses or supported composition fails exact-head accessibility evidence. | `audit:CommandPaletteItem/a11y` |
-| Theme/RTL | focused class assertion, `themingTargets.test.ts`, Storybook fixture, RTL verified N/A | all visual states | Target loss fails inventory/DOM tests; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteItem/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| FR1, FR3, AR1–AR2 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; context highlighted/selected | Dropped id/ref/native prop, clobberable role/state, or highlight-as-selection fails focused DOM assertions. | `audit:CommandPaletteItem/a11y` |
+| FR2, AR3 | `CommandPaletteItem.test.tsx` | enabled; disabled; consumer-cancelled; contextual | Disabled consumer activation, ignored cancellation, missing local report, selection, or close fails tests. | `audit:CommandPaletteItem/behavior` |
+| FR4, PR2 | `CommandPaletteItem.test.tsx`, `CommandPalette.test.tsx` | standalone; inline initial; changed highlight | Lost nearest scrolling, duplicate contextual scrolling, or initial inline scroll fails Effect assertions. | `audit:CommandPaletteItem/behavior` |
+| Theme/RTL | focused class assertion, `themingTargets.test.ts`, RTL verified N/A | all visual states | Target loss fails inventory/DOM tests; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteItem/theming` |
+| FR5, AR4 | Source review | Item children | Gap: no check fails if item children contain a nested interactive descendant. | `audit:CommandPaletteItem/accessibility` |
+| AR5 | Source review | Standalone item | Gap: no standalone keyboard model exists to test (OQ1). | `audit:CommandPaletteItem/accessibility` |
+| PR1 | Source review | Inside CommandPalette | Gap: no automated check fails if context matching adds a listener, an observer, or per-item registry work. | `audit:CommandPaletteItem/behavior` |
+
+Read from source, with no focused test yet:
+
+- FR5, AR4: children carrying no interactive descendant.
+- AR3: the omitted interaction overlay on a disabled item.
## Decision log
-No component-local API, keyboard, or visual decision is settled in this draft.
-Objective corrections preserve the current public shape.
+No component-local decision is recorded.
## Open questions
@@ -214,10 +222,9 @@ Objective corrections preserve the current public shape.
interaction contract, or standalone activation should enter a migration path.
- **OQ2 — How should keyboard highlight remain visible when the item is also
selected?** (`human-design`) Current selected background paint follows and
- masks the highlighted background. Real-browser pixels must confirm the gap;
- any appearance remedy requires owner direction and a separate visual change.
+ masks the highlighted background; any appearance remedy needs owner
+ direction.
## Content boundary
-This file does not duplicate consumer examples, audit scores, implementation
-steps, aggregate CommandPalette search/list behavior, or shared system rules.
+This file does not duplicate consumer examples, implementation steps, aggregate CommandPalette search/list behavior, or shared system rules.
diff --git a/docs/specs/components/CommandPalette/CommandPaletteList.spec.md b/docs/specs/components/CommandPalette/CommandPaletteList.spec.md
index 1e6920770a..c082624349 100644
--- a/docs/specs/components/CommandPalette/CommandPaletteList.spec.md
+++ b/docs/specs/components/CommandPalette/CommandPaletteList.spec.md
@@ -3,11 +3,11 @@ schema_version: 3
template_version: 7
kind: component
id: component:CommandPaletteList
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-11-01
owners: [cixzhang]
review_triggers: [behavior, accessibility, public-api, theming]
verified_by:
@@ -36,15 +36,15 @@ system_specs: []
## Contract at a glance
-| Area | Contract |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | None changes. One named listbox container for result options, rendered by CommandPalette or directly for a standalone results list. |
-| Behavior | The root is a `listbox` named by `label` or the translated default; inside CommandPalette it is one only while selectable results exist, and carries the context list id the query field controls. |
-| End-user impact | Screen-reader users reach a named results list from the query field; overflowing results scroll inside the list instead of growing the palette. |
-| Builder impact | None. CommandPalette renders its own list; standalone compositions render items and groups directly inside this one. |
-| Compatibility/readiness | Draft. Inside CommandPalette an empty or pending result surface drops the listbox role and name (AR4, an accessibility fix); a standalone caller `id` is kept (FR1); the standalone keyboard model remains OQ1. |
-| Review checks | Reject a second list-id owner, a role or name that consumer props can replace, dropped native or styling inputs, or a list target moved off the scrolling root. |
-| Governing rules | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface`; WAI-ARIA 1.2 `listbox`. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `CommandPaletteList` with `label`, `children`, `ref`, `xstyle`, `className`, `style`, and root DOM props: the named listbox of results that CommandPalette renders, or a standalone results list. |
+| Behavior | The root is a `listbox` named by a caller's `aria-label`, else `label`, else the translated default (the caller's `aria-label` is an FR2 gap today); inside CommandPalette it is one only while selectable results exist, and carries the context list id the query field controls. |
+| End-user impact | Screen-reader users reach a named results list from the query field; overflowing results scroll inside the list instead of growing the palette. |
+| Builder impact | A builder's explicit `aria-label` is meant to name the list; today the component's name replaces it (FR2 gap). |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact; one owner question stays open. |
+| Review checks | Reject a second list-id owner, a `listbox` role a caller can replace, a caller `aria-label` that does not reach the root, dropped native or styling inputs, or a list target moved off the scrolling root. |
+| Governing rules | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface`; WAI-ARIA 1.2 `listbox`. |
This table is a review projection; the body below is authoritative.
@@ -56,22 +56,30 @@ presents a named results listbox around caller-provided option content.
## Compatibility and migration
-- Released default preserved: `yes`, except inside CommandPalette while no
- selectable result exists, where the root no longer exposes an empty listbox
-- Compatibility class: accessibility behavior fix (`spec:AST-017/FR53`); styling,
- target, and public API are unchanged
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: not applicable; the list holds no state
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
+## Current-state impact
+
+- **A standalone list has no keyboard model.** A standalone list exposes a
+ listbox of options with no owning keyboard model, so a keyboard user cannot
+ move through its options; WAI-ARIA 1.2 gives a listbox's keyboard interaction
+ to its owner (AR3, OQ1).
+- **The list replaces a caller's name (FR2).** Consumer props spread before
+ the component's accessible name, so a builder's explicit `aria-label` never
+ names the list, where `architecture:public-component-api` INV5 lets it.
+
## Ownership boundary
**Owns**
-- The listbox root and its accessible name from `label`, falling back to the
- translated default, and dropping both inside CommandPalette while no selectable
- result exists.
+- The listbox root and its accessible name from a caller's `aria-label`, else
+ `label`, else the translated default (FR2), and dropping both inside
+ CommandPalette while no selectable result exists.
- Applying the CommandPalette context list id to the root.
- Native passthrough, `ref`, and styling-input composition on the root.
- Block-axis scrolling of overflowing children, with spacing-scale padding and
@@ -90,40 +98,41 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| --------------- | ---------------------------------- | ------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------ | --------- | ------------------------------------------------------------------------ |
-| Accessible name | caller `label`; translated default | Name announced for the results listbox. | All uses | `@astryx.commandPalette.list.label` ("Commands" in English) | `component:CommandPaletteList` | Stable | An empty `label` leaves the listbox unnamed; callers supply a real name. |
-| List identity | context list id; caller `id` | DOM id the CommandPalette query field references. | Inside CommandPalette; standalone | Context id inside CommandPalette; caller `id` standalone | `component:CommandPalette` | Stable | Inside CommandPalette a caller `id` is replaced by the context id. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------ | --------- | ------------------------------------------------------------------------ |
+| Accessible name | caller `aria-label`; caller `label`; translated default | Name announced for the results listbox. | All uses | `@astryx.commandPalette.list.label` ("Commands" in English) | `component:CommandPaletteList` | Stable | An empty `label` leaves the listbox unnamed; callers supply a real name. |
+| List identity | context list id; caller `id` | DOM id the CommandPalette query field references. | Inside CommandPalette; standalone | Context id inside CommandPalette; caller `id` standalone | `component:CommandPalette` | Stable | Inside CommandPalette a caller `id` is replaced by the context id. |
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Native props and `ref` reach the listbox root, and consumer `className` and `style` combine with the list target and base styles. Inside CommandPalette the root id is the context list id; standalone, a caller `id` is kept. | Released source; `architecture:public-component-api/INV5,INV6,INV8` | Ref, styling, and the standalone `id` verified by focused tests |
-| FR2 | Standalone, and inside CommandPalette while at least one selectable result exists, the root exposes `role=listbox` with an accessible name from `label`, falling back to the translated default; consumer `role` and `aria-label` props do not replace them. Otherwise AR4 applies. | Released source and docs; WAI-ARIA 1.2 `listbox` | Role and name verified by focused tests, with and without palette results; consumer-prop precedence is source-verified |
-| FR3 | Inside CommandPalette, the query field's `aria-controls` names the listbox id. | Released source and component docs | Verified by a focused composition test |
-| FR4 | The root lays out children in one column with spacing-scale padding and gaps, grows within a flex parent, caps its height at the parent's height, and scrolls overflowing children inside itself. | Released source and component docs | Source-verified; the scrolling fixture renders it in a browser, but scroll geometry is not yet measured |
+| ID | Invariant | Basis |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Native props and `ref` reach the listbox root, and consumer `className` and `style` combine with the list target and base styles. Inside CommandPalette the root id is the context list id; standalone, a caller `id` is kept. | Current source and tests |
+| FR2 | Standalone, and inside CommandPalette while at least one selectable result exists, the root exposes `role=listbox`, which a caller's `role` does not replace: inside CommandPalette because composite semantics are component-owned and replace passthrough, as `component:CommandPaletteInput` AR3 records, and standalone by this record's own rule, named by a caller's explicit `aria-label`, else `label`, else the translated default (`architecture:public-component-api` INV5). Implementation gap: the component's name replaces a caller's `aria-label` (Current-state impact). Otherwise AR4 applies. | Current source and tests |
+| FR3 | Inside CommandPalette, the query field's `aria-controls` names the listbox id. | Current source and tests |
+| FR4 | The root lays out children in one column with spacing-scale padding and gaps, grows within a flex parent, caps its height at the parent's height, and scrolls overflowing children inside itself. | Current source |
### Allowed variation
- **AV1 — Children.** Items, groups, and empty states may vary in count, order,
and content without changing the root, except as AR4 states.
- **AV2 — Layout.** Consumer `xstyle`, class, and style may adjust the root
- without replacing its role, name, id, or target.
+ without replacing its role, id, or target.
### Representative states
-| State | Required invariant | Allowed variation |
-| --------------------- | ------------------------------------------------------------------------------ | -------------------------- |
-| Standalone results | The listbox is named by `label` or the translated default. | Item count and grouping. |
-| Inside CommandPalette | The root id equals the query field's `aria-controls` value. | Results count and groups. |
-| Overflowing results | Results scroll inside the list instead of growing past the container. | Container and item height. |
-| Empty palette results | Inside CommandPalette with no selectable result, the root has no role or name. | Empty or pending message. |
+| State | Required invariant | Allowed variation |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| Standalone results | The listbox is named by a caller's `aria-label`, else `label`, else the translated default (FR2 gap for `aria-label`). | Item count and grouping. |
+| Inside CommandPalette | The root id equals the query field's `aria-controls` value. | Results count and groups. |
+| Overflowing results | Results scroll inside the list instead of growing past the container. | Container and item height. |
+| Empty palette results | Inside CommandPalette with no selectable result, the root has no role or name. | Empty or pending message. |
### Transformation and precedence order
- **ORD1 — Root attributes.** Consumer native props, then the component-owned
- id, `listbox` role, and accessible name.
+ id and `listbox` role; the accessible name applies unless the caller supplies
+ its own `aria-label` (FR2; today it replaces the caller's).
- **ORD2 — Styling.** List target, then base styles with `xstyle`, then
consumer class, then consumer style.
@@ -134,14 +143,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Accessibility contract
-- **AR1 — Name.** The listbox takes `label` as its accessible name and falls back
- to the translated default when `label` is omitted.
+- **AR1 — Name.** The listbox takes a caller's explicit `aria-label`, else
+ `label`, else the translated default, as its accessible name (FR2 gap).
- **AR2 — Relationship.** Inside CommandPalette, the query field controls the
listbox through its id; CommandPalette owns focus and keyboard navigation under
its combobox model.
- **AR3 — Standalone gap.** A standalone list exposes a listbox of options with
- no owning keyboard model. OQ1 must settle that contract before runtime
- semantics change.
+ no owning keyboard model (Current-state impact; OQ1).
- **AR4 — Empty content.** Inside CommandPalette, while no selectable result
exists, the root has no role and no accessible name, so screen readers meet the
empty or pending message as plain content and no empty popup; WAI-ARIA 1.2
@@ -168,17 +176,23 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1 | `CommandPaletteList.test.tsx` | standalone root with ref, class, and style | Disconnecting `ref`, or dropping the consumer class or the list target, fails focused DOM assertions. | `audit:CommandPaletteList/api` |
-| FR2, AR1, AR4 | `CommandPaletteList.test.tsx` | default and caller label; palette with and without results | Removing the role or name, or keeping them on an empty palette surface, fails the role and name assertions. | `audit:CommandPaletteList/a11y` |
-| FR3, AR2 | `CommandPaletteList.test.tsx`, `CommandPalette.test.tsx` | inline CommandPalette | Dropping the context id breaks the query-field relationship assertion. | `audit:CommandPaletteList/a11y` |
-| FR4 | Storybook fixtures, `themingTargets.test.ts`, exact-head accessibility and RTL evidence | standalone list; scrolling palette | Losing the target fails the target inventory; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteList/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------- | -------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| FR1 | `CommandPaletteList.test.tsx` | standalone root with ref, class, and style | Disconnecting `ref`, or dropping the consumer class or the list target, fails focused DOM assertions. | `audit:CommandPaletteList/api` |
+| FR2, AR1, AR4 | `CommandPaletteList.test.tsx` | default and caller label; palette with and without results | Removing the role or name, or keeping them on an empty palette surface, fails the role and name assertions. Gap: no test covers a caller `role` or `aria-label`. | `audit:CommandPaletteList/a11y` |
+| FR3, AR2 | `CommandPaletteList.test.tsx`, `CommandPalette.test.tsx` | inline CommandPalette | Dropping the context id breaks the query-field relationship assertion. | `audit:CommandPaletteList/a11y` |
+| FR4 | `themingTargets.test.ts`; RTL verified not applicable | standalone list | Losing the target fails the target inventory. | `audit:CommandPaletteList/theming` |
+| AR3 | Source review | Standalone list | Gap: no standalone keyboard model exists to test (OQ1). | `audit:CommandPaletteList/accessibility` |
+| PR1 | Source review | Every state | Gap: no automated check fails if the list adds state, an effect, a listener, or an observer. | `audit:CommandPaletteList/behavior` |
+
+Read from source, with no focused test yet:
+
+- FR4: the one-column layout, spacing, height cap, and inner scrolling.
+- PR1: no state, Effect, listener, or observer.
## Decision log
-None. This draft records current facts and settles no component-local API,
-keyboard, or visual decision; AR4 applies the WAI-ARIA 1.2 listbox rule.
+No component-local decision is recorded.
## Open questions
@@ -190,5 +204,5 @@ keyboard, or visual decision; AR4 applies the WAI-ARIA 1.2 listbox rule.
## Content boundary
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.
+This file does not duplicate consumer prop tables/examples, implementation
+steps, or family/system rules. It links to their owners.