Components / v1.0.0

Keyboard command surface

A fast command surface with predictable focus, useful grouping, and enough context to choose an action without opening another view.

Audience

Frequent product users who already know what they want to reach or execute.

Job to be done

Find a destination or command quickly while preserving the user context behind the overlay.

Design direction

Use a single filled dialog, restrained selected rows, and a stable layout. Search, results, and command context should read as one surface.

Hierarchy

01Search input
02Active result
03Result label and context
04Grouped alternatives
05Keyboard help

Required proof

01Result count for filtered states
02Visible destination or action context
03Recent items stored only on the current device

Required states

01Closed
02Browse
03Searching
04No results
05Active result
06Command running
07Command failed

Responsive behavior

01Use a full-height sheet on narrow phones
02Hide secondary descriptions before truncating labels
03Keep the search input and close action fixed while results scroll

Constraints

01Never use a white hover fill in dark mode
02Do not nest cards inside the dialog
03Keep the active row visible during keyboard navigation

Accessibility

01Trap focus while open and restore it on close
02Support ArrowUp, ArrowDown, Home, End, Enter, and Escape
03Use combobox and active-descendant semantics where appropriate

Verification

01Complete the full flow without a pointer
02Confirm focus restoration after action and dismissal
03Test empty results and long labels at 320px

Tradeoffs

01A stable grouped layout is easier to learn but shows fewer results at once
02Recent items improve speed but require clear local-only storage behavior

Stack

ReactTailwind CSSLucide React

Connected UI Grids assets

CommandMenu ProductShell

Build handoff

Provider

You are an expert design engineer.

Build a reusable React component: Keyboard command surface.

**Purpose:** A fast command surface with predictable focus, useful grouping, and enough context to choose an action without opening another view.

**Audience:** Frequent product users who already know what they want to reach or execute.

**Job to be done:** Find a destination or command quickly while preserving the user context behind the overlay.

**Design style:** Use a single filled dialog, restrained selected rows, and a stable layout. Search, results, and command context should read as one surface.

**Visual hierarchy:** Search input -> Active result -> Result label and context -> Grouped alternatives -> Keyboard help

**Responsiveness:** Use a full-height sheet on narrow phones Hide secondary descriptions before truncating labels Keep the search input and close action fixed while results scroll

**Accessibility:** Trap focus while open and restore it on close Support ArrowUp, ArrowDown, Home, End, Enter, and Escape Use combobox and active-descendant semantics where appropriate

**Required proof:**
- Result count for filtered states
- Visible destination or action context
- Recent items stored only on the current device

**Required states:**
- Closed
- Browse
- Searching
- No results
- Active result
- Command running
- Command failed

**Expected technologies:**
- React
- Tailwind CSS
- Lucide React

**Constraints:**
- Never use a white hover fill in dark mode
- Do not nest cards inside the dialog
- Keep the active row visible during keyboard navigation

**Verification:**
- Complete the full flow without a pointer
- Confirm focus restoration after action and dismissal
- Test empty results and long labels at 320px

**Tradeoffs:**
- A stable grouped layout is easier to learn but shows fewer results at once
- Recent items improve speed but require clear local-only storage behavior

**Brand inputs:**
- Product name
- Search placeholder
- Command groups
- Default actions
- Recent-item policy

**Deliver:** A production-ready component implementation plus verification notes.

Use React + Tailwind. Keep it accessible and respect prefers-reduced-motion. Return only the component code.