An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:CommandPaletteList authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [behavior, accessibility, public-api, theming] verified_by: [ packages/core/src/CommandPalette/CommandPaletteList.test.tsx, packages/core/src/CommandPalette/CommandPalette.test.tsx, packages/core/src/theme/themingTargets.test.ts, apps/storybook/stories/CommandPaletteList.stories.tsx, apps/storybook/rtl-audit/verified-not-applicable.json, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-test-sufficiency, architecture:component-theming-surface, architecture:public-component-api, ] contributing: []
system_specs: []
CommandPaletteList component contract
Contract at a glance
| 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.
Intent
CommandPaletteList is the scrolling results container of the command palette. Inside CommandPalette it is the listbox the query field controls. Standalone, it presents a named results listbox around caller-provided option content.
Compatibility and migration
- 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-labelnever names the list, wherearchitecture:public-component-apiINV5 lets it.
Ownership boundary
Owns
- The listbox root and its accessible name from a caller's
aria-label, elselabel, 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 gaps.
Does not own / non-goals
- List-id generation, query-field focus, active descendant, arrow-key
navigation, hover highlight, Enter selection, search, and the choice between
results and the empty state — owned by
component:CommandPalette. - The aggregate List anatomy entry and its
command-palette-listtarget mapping — owned bycomponent:CommandPalette. - Option semantics, state, and activation; group semantics and headings — owned by CommandPaletteItem and CommandPaletteGroup.
- A standalone composite keyboard model; its direction remains OQ1.
Public concepts
| 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 | 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, id, or target.
Representative states
| 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 and
listboxrole; the accessible name applies unless the caller supplies its ownaria-label(FR2; today it replaces the caller's). - ORD2 — Styling. List target, then base styles with
xstyle, then consumer class, then consumer style.
Performance and resources
- PR1 — No work beyond render. The list adds no state, effect, listener, or observer; it reads translation and CommandPalette context during render only.
Accessibility contract
- AR1 — Name. The listbox takes a caller's explicit
aria-label, elselabel, 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 (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 requires a listbox to own options. A standalone list stays a listbox, and its caller supplies the options.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| List | Presents result options in one scrolling column with spacing-scale padding and gap. | Current source and public docs | Supporting | FR1, FR4 |
Family and system relationships
component:CommandPaletteowns list-id generation, keyboard navigation, hover highlight, the aggregate anatomy, and thecommand-palette-listtarget mapping; this component applies the id and paints the List.architecture:public-component-apiowns native passthrough, styling composition, and refs.architecture:component-theming-surfaceowns target qualification and the aggregate List anatomy map.architecture:component-test-sufficiencyowns the evidence rules behind the verification map below.
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. 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
No component-local decision is recorded.
Open questions
- OQ1 — What standalone keyboard contract should CommandPaletteList expose?
(
human-api) A standalone list exposes a listbox of options but no owning keyboard model. Decide whether a public composite owner supplies that model, the standalone composition takes a different role, or standalone use remains pointer-only presentation.
Content boundary
This file does not duplicate consumer prop tables/examples, implementation steps, or family/system rules. It links to their owners.