An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:CommandPaletteEmpty authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [public-api, behavior, theming, accessibility, testing] verified_by: [ packages/core/src/CommandPalette/CommandPaletteEmpty.test.tsx, packages/core/src/CommandPalette/CommandPalette.test.tsx, packages/core/src/CommandPalette/CommandPaletteList.test.tsx, packages/core/src/CommandPalette/tests/CommandPaletteEmptyAudit.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, apps/storybook/stories/CommandPaletteEmpty.stories.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:component-test-sufficiency, ] contributing: []
system_specs: [spec:AST-029, spec:AST-056]
CommandPaletteEmpty component contract
Contract at a glance
| Area | Contract |
|---|---|
| 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. |
| 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. |
This table is a review projection; the body below is authoritative.
Intent
CommandPaletteEmpty presents the message shown in a CommandPalette result area
when there is nothing to choose. It owns the empty-message surface: its layout,
supporting typography, secondary text color, root input composition, and the
command-palette-empty theme target. CommandPalette decides when the message
appears, what it says by default, and whether it is announced.
Consumer syntax and examples belong in CommandPaletteEmpty.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
- One root container and its public ref, DOM/data/ARIA, class, style, event, and
xstylecomposition. - Centered layout, block and inline padding, supporting type size and leading, body font family, and secondary text color for caller content.
- Wrapping caller text inside the host's inline size.
- The
command-palette-emptytarget on the same painted root.
Does not own / non-goals
- When the empty branch appears, the built-in catalog messages, and the
empty-search announcement — owned by
component:CommandPalette. - Result-surface semantics while empty, including dropping listbox semantics —
owned by
component:CommandPaletteandcomponent:CommandPaletteList. - The meaning, links, or controls inside caller content — owned by the product callsite.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Empty message | caller ReactNode: text or elements |
The supporting message people read when there is nothing to choose. | No-query and no-results palette branches; standalone composition | required | component | stable | Rendered as given; React decides non-renderable values. |
| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the message root. | Every render | omitted | public component API | stable | Accepted inputs compose; the component adds no role. |
Behavioral and layout contract
| 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
- AV1 — Theme paint. The target may restyle the message surface and text without changing semantics or layout ownership.
- AV2 — Caller content. Text length, translation, inline elements, and links may vary while the root stays one ordinary container.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Palette no-query empty | The bootstrap message renders in the result area; no listbox is exposed. | Built-in catalog text or caller content. |
| Palette no-result | The search message renders; CommandPalette announces the rendered text. | Built-in catalog text or caller rich content. |
| Standalone | The same root renders outside a palette with caller content. | Host layout and caller roles. |
| Long or translated | Text wraps inside the host; no inline overflow. | Line count grows. |
| RTL | Centered layout and text remain direction-neutral; inline text order mirrors. | Caller content direction. |
| Narrow viewport | The message wraps within a 320 CSS px host. | Line count grows. |
Transformation and precedence order
- ORD1 — Root composition. Apply the target class, component styles, then
caller
xstyle; append callerclassName; apply callerstyle; spread remaining host props onto the root.
Performance and resources
- PR1 — No lifecycle. CommandPaletteEmpty uses no hook, listener, observer, timer, request, state, or Effect.
Accessibility contract
- AR1 — Ordinary content. The root exposes caller content in reading order with no added role; a caller link keeps its own role and focus behavior.
- AR2 — Readable message. Message text meets the WCAG 2.2 SC 1.4.3 contrast minimum against its rendered surface in every supported theme and mode.
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 | supporting | FR1, FR4, FR5 |
No component-local design decision is recorded. The aggregate CommandPalette
anatomy map, owned by component:CommandPalette, maps the Empty part.
Family and system relationships
architecture:public-component-apiowns exports and root input composition.architecture:component-theming-surfaceowns target placement.architecture:component-test-sufficiencyowns proportionate, observable evidence.spec:AST-056/FR3andAR1require CommandPalette to announce the empty-search message it rendered; this component supplies the rendered node.component:CommandPaletteandcomponent:CommandPaletteListown the parent branches and the empty result surface.spec:AST-029owns 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 |
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
No component-local decision is recorded.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, implementation steps, or system rules. It links to their owners.