J3W1 / DESIGN SYSTEM

Command palette

A compact square modal command prompt with local results and category labels.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

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@1.1.0

import '@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.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy command-palette --out ./vendor/j3w1/command-palette

The 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

Purpose

Find and invoke local commands from a compact square floating utility panel. One prompt filters dense rows with category labels. Results are caller-supplied links or bounded actions; no remote search occurs. The host may opt into Ctrl+K or Cmd+K.

Anatomy

trigger: Named native button opens the utility panel.
prompt: Labelled combobox input retains focus while navigating results.
results: Listbox results include category and command text.
dialog: Native modal dialog provides containment and return.

States

State	Presentation	Non-colour channel
default	One prompt and dense command rows.	Visible names and categories.
open	Square overlay surface and border.	Native modal dialog and active-descendant relationship.
closed	Panel absent.	Opener remains focusable.
focus-visible	Dashed input ring.	Input retains DOM focus while results change.
no-results	Muted zero-results status.	Explicit result count and no active descendant.

Keyboard

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.

Accessibility

Combine native modal focus behavior with the editable combobox pattern. Result names include their category and command text; selection uses the approved selected roles. Escape closes once and restores focus. Required site navigation remains available outside the palette without JavaScript. Do not globally intercept shortcuts unless the host opts in.

Portability

Wrap labels and actions without changing source order. Use logical spacing in RTL. Preserve native target sizes at both densities; only bounded data regions may scroll horizontally. Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation. The host owns application data, persistence, permissions and services.

Non-examples

Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.