Command palette
A compact square modal command prompt with local results and category labels.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
<j3w1-command-palette id="example-command-palette-default"><div class="command-palette"><button class="command-palette-control" type="button" data-open="" data-demo-focus-target="">Search commands <kbd>Ctrl K</kbd></button><dialog class="command-palette-dialog" aria-labelledby="example-command-palette-default-command-title"><h2 id="example-command-palette-default-command-title">Command prompt</h2><label for="example-command-palette-default-command-query">Search commands</label><input class="command-palette-control" id="example-command-palette-default-command-query" type="search" role="combobox" aria-autocomplete="list" aria-expanded="true" aria-controls="example-command-palette-default-command-results" autocomplete="off"><ul id="example-command-palette-default-command-results" role="listbox" aria-label="Commands"><li role="option" id="example-command-palette-default-command-foundations" data-action="foundations"><span>SPEC</span> Explore foundations</li><li role="option" id="example-command-palette-default-command-components" data-action="components"><span>BUILD</span> Browse components</li><li role="option" id="example-command-palette-default-command-copy" data-action="copy"><span>AGENT</span> Prepare a copy kit</li></ul><p role="status" data-command-status="">3 commands</p><button class="command-palette-control" type="button" data-close="">Close</button></dialog></div></j3w1-command-palette>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/command-palette.css';
import '@j3w1/ui/register/command-palette';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy command-palette --out ./vendor/j3w1/command-paletteThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
shortcut | CustomEvent | Opt in to Ctrl+K / Cmd+K; absence leaves global shortcuts to the host. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
open | boolean | Native modal state. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
show | (): void | Open and focus the command prompt. |
close | (): void | Close and restore the opener. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-command | CustomEvent | Invoke the chosen command; prevent default to handle a result link yourself. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Command palette command-palette
A compact square modal command prompt with local results and category labels.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
root.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.border | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
heading.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
secondary.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
control.bg | color.surface.inputapproveduse | #000000 | Form-control fill. |
control.focus | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
button.bg | color.action.secondary.bgobserveduse | rgb(0 0 0 / 0%) | Secondary button has no fill. |
button.text | color.action.secondary.textapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
button.border | color.action.secondary.borderapproveduse | #986f72 | D-041 action.secondary.border: color.primitive.modern.control. |
button.bg-hover | color.action.secondary.hover-bgobserveduse | #630f0d | Secondary button hover. |
button.bg-active | color.action.secondary.pressed-bgobserveduse | #420f0c | Secondary button pressed. |
button.border-active | color.border.activeobserveduse | #e53935 | Active or focused control border. |
button.focus | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
dependency.role-border-width-default | border.width.defaultobserveduse | 1px | Every border is 1px. |
dependency.role-border-width-emphasis | border.width.emphasisobserveduse | 2px | Selected indicator, sticky header rule, invalid border. |
dependency.role-color-border-overlay | color.border.overlayapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
dependency.role-color-border-selected-indicator | color.border.selected-indicatorobserveduse | #e53935 | 2px indicator bar on the selected tab or nav item. |
dependency.role-color-interaction-selection-bg | color.interaction.selection.bgapproveduse | #531310 | Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection. |
dependency.role-color-interaction-selection-text | color.interaction.selection.textobserveduse | #f4eeee | Text on the selection. |
dependency.role-color-surface-backdrop | color.surface.backdropproposeduse-and-reportD-008 | rgb(0 0 0 / 65%) | Behind modal dialogs. |
dependency.role-color-surface-overlay | color.surface.overlayapproveduse | #1c1010 | D-041 surface.overlay: color.primitive.modern.overlay. |
dependency.role-density-comfortable-control-height | density.comfortable.control-heightobserveduse | 32px | |
dependency.role-density-compact-control-height | density.compact.control-heightobserveduse | 24px | |
dependency.role-focus-offset | focus.offsetobserveduse | -2px | outline-offset for controls. |
dependency.role-radius-none | radius.noneobserveduse | 0px | The only radius. Nothing is rounded. |
dependency.role-space-12 | space.12observeduse | 12px | |
dependency.role-space-16 | space.16observeduse | 16px | |
dependency.role-space-8 | space.8observeduse | 8px |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Default |
|---|---|
default | |
open | |
closed | |
focus-visible | |
no-results |
Purpose
Finds and invokes local commands; navigation the site requires stays available outside the palette, without JavaScript.
Anatomy
Parts as listed in the anatomy.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | One prompt, dense command rows. Button controls are the secondary button (button.md); inputs keep the input look. | Visible names and categories. |
| open | Square overlay surface and border. | Native modal dialog; active-descendant relationship. |
| closed | Panel absent. | Opener stays focusable. |
| focus-visible | Dashed input ring. | Input keeps DOM focus while results change. |
| no-results | Muted zero-results status. | Explicit result count; no active descendant. |
Keyboard
As in the key table. Shortcuts are never intercepted globally unless the host opts in, and one Escape closes the palette.
Accessibility
Each result’s name includes its category and command text. Selection uses the approved selected roles.
Portability
Follows the shared component defaults in spec/portability.md (section
“Shared component defaults”).
Non-examples
Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.
Contrast report
7 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| command-palette default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| command-palette default border | default | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Primary content | — | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| Supporting content | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| Control boundary | — | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Button label | — | text | color.action.secondary.text #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| Button label on hover | — | text | color.action.secondary.text #ffa2a7 | color.action.secondary.hover-bg #630f0d | 6.84 | 4.5 | pass |
Keys
| Key | Action |
|---|---|
| Ctrl+K / Cmd+K | Open when the host explicitly enables the shortcut. |
| Up / Down | Move the active result while retaining input focus. |
| Enter | Invoke the active enabled result and close. |
| Escape | Close and restore the opener. |
| Tab / Shift+Tab | Cycle through native modal controls. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Stress fixtures: FX-320 FX-360 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-TOUCH FX-DENSITY FX-STATE-MATRIX