# CommandMenu

> Finds and runs anything from the keyboard (⌘K).

- **Level**: organism · **Status**: stable · **Role**: navigation
- **Import**: `import { CommandMenu, CommandMenuGroup, CommandMenuItem, CommandMenuSeparator } from "@rrios-forge/ui/organisms/command-menu";`
- **Source**: `packages/ui/src/organisms/command-menu`

⌘K command palette. Composes Dialog (modal overlay + focus trap) + cmdk Command (filtered listbox + keyboard navigation + active descendant). Item rendering is consumer-owned via children — typically a tree of CommandMenu.Group + CommandMenu.Item + CommandMenu.Separator. cmdk handles filtering automatically based on the search input; the organism never owns search state.

## Use it for

- App frame / navigation → **The rail that peeks (ADR-044) — the default and the recommendation.** `PageShell` (defaults: `sidebarMode="rail"`, `sidebarPresentation="inset"`, `mobileNav="tabs"`) + `SidebarSection aria-label` + ONE untitled `NavGroup`: home, search, the rooms, settings — same size, same gap. Wrap every `NavItem` in `PageShell.RailPeek` and compose its panel with `PageShell.PeekHeader` / `PeekFacts` / `PeekLinks`. Search is a button row opening `CommandMenu` (⌘K); settings' peek holds the quick controls; phones get `PageShell.MobileTabBar` (≤ 5). No `TopBar` in an app frame. Opt-ins only when a product needs them: the labelled panel (`sidebarMode="auto"`, ⌘\\ collapse, ADR-040), `island`/`column` (ADR-025), the bubble (`mobileNav="bubble"`)
- Command palette → `CommandMenu`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `tone` | — | `neutral` `muted` | `neutral` | Which semantic colour family the element speaks in. |
| `intent` | — | `neutral` `danger` | `neutral` | What an action does. |

## Stories

- [Playground](/?path=/story/components-organisms-commandmenu--playground) · frame: `/iframe.html?id=components-organisms-commandmenu--playground&viewMode=story`
- [Open (inline)](/?path=/story/components-organisms-commandmenu--open) · frame: `/iframe.html?id=components-organisms-commandmenu--open&viewMode=story`
- [With trigger](/?path=/story/components-organisms-commandmenu--with-trigger) · frame: `/iframe.html?id=components-organisms-commandmenu--with-trigger&viewMode=story`
- [Empty (no matches)](/?path=/story/components-organisms-commandmenu--empty) · frame: `/iframe.html?id=components-organisms-commandmenu--empty&viewMode=story`
- [Custom empty](/?path=/story/components-organisms-commandmenu--custom-empty) · frame: `/iframe.html?id=components-organisms-commandmenu--custom-empty&viewMode=story`
- [No footer](/?path=/story/components-organisms-commandmenu--no-footer) · frame: `/iframe.html?id=components-organisms-commandmenu--no-footer&viewMode=story`
- [Single group](/?path=/story/components-organisms-commandmenu--single-group) · frame: `/iframe.html?id=components-organisms-commandmenu--single-group&viewMode=story`
- [In PageShell (⌘K trigger)](/?path=/story/components-organisms-commandmenu--in-page-shell) · frame: `/iframe.html?id=components-organisms-commandmenu--in-page-shell&viewMode=story`
- [Accessibility](/?path=/story/components-organisms-commandmenu--accessibility) · frame: `/iframe.html?id=components-organisms-commandmenu--accessibility&viewMode=story`

## Decisions that name it

- ADR-003 — Storybook editorial convention and pattern↔component bidirectionality
- ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule
- ADR-010 — PageShell v4: bottom dock + mobile floating bubble
- ADR-030 — Axis vocabulary: one name, one meaning
- ADR-034 — Accessible names come from a labels provider
- ADR-035 — Motion grammar: the gate before motion, slop by repetition, and what reduced motion keeps
- ADR-044 — Navigation is a rail that peeks

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).