# Command Palette

A command palette is a fast, searchable route to actions and destinations. It
supplements visible navigation; it must not become the only way to discover a
critical task.

## Structure

Use a labelled dialog containing a search field and a result list. Group results
by stable concepts such as recent, navigation, and actions. Every result needs a
clear primary label; shortcuts, scope, and destination are supporting metadata.

Use the WAI-ARIA dialog and combobox/listbox guidance as applicable:
https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ and
https://www.w3.org/WAI/ARIA/apg/patterns/combobox/.

## Interaction

- Open from a visible control and an optional platform-appropriate shortcut.
- Put focus in the query field on open.
- Up/Down moves the active result; Enter activates it; Escape closes.
- Keep typed text stable while results update.
- Announce result counts and empty states without stealing focus.
- Return focus to the opener after dismissal.
- Close only after an action is accepted or the user dismisses the palette.

Do not trigger a destructive or irreversible action directly from a search
result. Route to confirmation or the normal guarded flow.

## Search behavior

Rank exact names, aliases, and recent use ahead of fuzzy matches. Highlight
matching text without changing the accessible name. Debounce remote searches,
cancel obsolete requests, and show progress. Keep a useful local subset when a
remote provider is unavailable.

## Verification

- The visible opener, shortcut hint, and actual shortcut agree.
- Focus is contained while the modal palette is open.
- Results remain operable with keyboard, screen reader, zoom, and IME input.
- Loading, no-results, error, and offline states are distinct.
- Hidden or unauthorized commands never appear in results.