Command Palette Architecture Playbook

Scope

This guide defines a scalable command system for navigation, search, and product operations.

Command Model

Each command should include:

• id: immutable stable identifier
• name: display label
• description: searchable helper text
• category: search, theme, navigation, custom
• shortcut: optional typed prefix
• execute: side-effect handler
• access: optional permission metadata

Runtime Stages

1. collect commands from providers
2. filter by permissions and context
3. parse query intent
4. rank candidates
5. render list and allow keyboard navigation
6. execute selected command with payload

Query Parsing

Support two modes:

• free text fuzzy search
• prefix mode such as g hello

Keep parser pure and separately tested.

Ranking Heuristics

Weighted score example:

• exact name match: 100
• prefix shortcut exact: 95
• startsWith name: 80
• includes in description: 40
• recent usage bonus: +10

Keyboard Semantics

• Cmd/Ctrl+K and Cmd/Ctrl+Shift+P open
• ArrowUp and ArrowDown cycle list
• Enter executes active item
• Escape clears input first, closes on second press

Focus and Accessibility

• trap focus while modal is open
• announce active command to screen readers
• preserve visible focus ring on list items
• keep pointer and keyboard selection in sync

Execution Safety

• avoid duplicate execution on key repeat
• disable execute while async action in flight
• surface errors in non-blocking toast
• log command failures with stable ids

Observability

Track:

• command_palette_opened
• command_selected
• command_executed
• command_failed
• command_search_latency_ms

Extensibility Pattern

Adopt command providers by feature area:

• theme provider
• navigation provider
• external search provider

Merge providers into one array at runtime with deterministic ordering.

Test Matrix

Unit:

• parser and ranking functions
• keyboard state transitions

Integration:

• open/close behavior
• selection and execute flow

E2E:

• typed shortcut payload execution
• accessibility regression checks

Anti-patterns

• business logic inside component template
• hardcoded command arrays without ownership boundaries
• inconsistent shortcut behavior across platforms