@design-ai/cli 4.55.0

package/examples/component-color-picker.md

@@ -0,0 +1,110 @@
+# `ColorPicker` — spec
+
+> Citing Ant Design `ColorPicker`, MUI (no built-in), shadcn-ui (composition with libraries)
+
+## Purpose
+
+Lets users pick a color value. Used in: design tools, theme customizers, content authoring (highlight color, brand color), CRM tag creation.
+
+## Anatomy
+
+```
+Trigger (small swatch):           Open (full picker panel):
+┌─────────────┐                   ┌─────────────────────────────────┐
+│ ▣ #7C3AED  ▾│                   │  ┌─────────────────────────┐   │
+└─────────────┘                   │  │                         │   │  ← saturation/value square
+                                  │  │     [picker dot]        │   │
+                                  │  │                         │   │
+                                  │  └─────────────────────────┘   │
+                                  │  ──[ hue slider ]────────       │
+                                  │  ──[ alpha slider ]──────       │
+                                  │                                  │
+                                  │  HEX:    [#7C3AED         ]      │
+                                  │  RGB:    [124] [58] [237]        │
+                                  │  HSL/OKLCH:  [...]              │
+                                  │                                  │
+                                  │  Presets: ● ● ● ● ● ● ● ●       │
+                                  └─────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<ColorPicker
+  value={color}
+  onValueChange={setColor}
+  format="hex"
+  showAlpha
+  presets={brandColors}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` (hex/rgba/oklch) | — | Color value |
+| `onValueChange` | `(value: string) => void` | — | |
+| `format` | `"hex" \| "rgb" \| "hsl" \| "oklch"` | `"hex"` | Output format |
+| `showAlpha` | `boolean` | `false` | Alpha slider |
+| `showInputs` | `boolean` | `true` | Numeric inputs (hex/rgb/hsl) |
+| `presets` | `string[]` | — | Preset swatches at the bottom |
+| `disabled` | `boolean` | `false` | |
+| `triggerStyle` | `"swatch" \| "button"` | `"swatch"` | Compact swatch vs labeled button |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+
+## Behavior
+
+- Click trigger → opens popover with picker.
+- Saturation/value square: drag picker dot to choose; updates live.
+- Hue slider: vertical or horizontal; rotates hue.
+- Alpha slider (if shown): adjusts transparency.
+- Numeric inputs: typing updates picker.
+- Preset swatch click: instant apply.
+
+## States
+
+Standard popover-trigger states. The picker square + sliders use canvas/SVG; track mouse + keyboard.
+
+## Accessibility
+
+- Trigger: `role="button"`, `aria-label="Choose color"`, `aria-haspopup="dialog"`.
+- Popover: `role="dialog"`, `aria-label="Color picker"`.
+- Saturation/value square: `role="slider"`, `aria-valuetext` describing current color (e.g., "Hue 285, Saturation 70%, Value 90%").
+- Hue/alpha sliders: standard slider role.
+- Numeric inputs: standard input fields with labels.
+
+### Keyboard
+
+The square is hard to navigate by keyboard. Provide:
+- `Tab` to reach square; arrow keys move dot by small steps.
+- Numeric inputs: type to set exact value.
+- Preset swatches: tab through, Enter to apply.
+
+For users who prefer, the hex input is the primary path on keyboard.
+
+## Format conversion
+
+Internally, store as a single canonical format (often HSV or RGB), convert to display format on output. Use a library:
+
+- `tinycolor2` — robust conversions
+- `chroma.js` — color manipulation
+- `culori` — modern, OKLCH-aware
+
+Don't roll your own — color math is hard and there are subtle edge cases.
+
+## Don't
+
+- Don't use ColorPicker for picking from a fixed brand palette. Use a Tag/swatch picker.
+- Don't auto-apply on hover (only on commit).
+- Don't omit accessible name. Color values aren't enough.
+- Don't show only the picker without numeric inputs — accessibility requires keyboard alternative.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/color-picker/`](../refs/ant-design/components/color-picker/) — comprehensive. Has presets, alpha, multiple format inputs.
+- MUI: no built-in. Use `react-colorful` or similar.
+- shadcn-ui: no built-in. Compose with `Popover` + `react-colorful`.
+
+## Cross-reference
+
+- [`knowledge/colors/color-theory.md`](../knowledge/colors/color-theory.md) — color spaces (OKLCH, HSL)
+- [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md) — when picking text colors, verify contrast

package/examples/component-combobox.md

@@ -0,0 +1,267 @@
+# `Combobox` — spec
+
+> Synthesized from shadcn-ui `combobox` (cmdk + Popover) and the WAI-ARIA Combobox pattern. A typeable search field combined with a list of options. Distinct from `Select` (no typing) and `Autocomplete` (more freeform).
+
+## Combobox vs Select vs Autocomplete
+
+| | Combobox | Select | Autocomplete |
+| --- | --- | --- | --- |
+| Typing | **Yes** (filters list) | No | Yes |
+| Free input | No (must pick from list) | n/a | Yes (often) |
+| Use | Pick from a long list (50+ options) | Pick from a short list (< 20) | Suggest while typing free text |
+| Examples | Country picker, user mention | Sort by, status filter | Address auto-suggest, search bar |
+
+The combobox is "Select with search" — typing narrows the list.
+
+## Anatomy
+
+```
+┌─────────────────────────────────┐
+│ ▼ Search framework...           │   ← trigger field (looks like input)
+└─────────────────────────────────┘
+       ↓ click / focus
+┌─────────────────────────────────┐
+│ ⌕ Type to search...             │   ← search input
+│ ───────────────────             │
+│ ▶  React                        │
+│    Vue                          │   ← filtered list
+│    Svelte                       │
+│    Solid                        │
+│ ───────────────────             │
+│ No results found                │   ← empty state
+└─────────────────────────────────┘
+```
+
+## API
+
+```tsx
+const [value, setValue] = useState("");
+const [open, setOpen] = useState(false);
+
+<Combobox open={open} onOpenChange={setOpen}>
+  <Combobox.Trigger asChild>
+    <Button variant="outline" role="combobox" aria-expanded={open}>
+      {value ? frameworks.find(f => f.value === value)?.label : "Select framework..."}
+      <ChevronIcon />
+    </Button>
+  </Combobox.Trigger>
+  <Combobox.Content>
+    <Combobox.Input placeholder="Search framework..." />
+    <Combobox.List>
+      <Combobox.Empty>No framework found.</Combobox.Empty>
+      <Combobox.Group>
+        {frameworks.map(f => (
+          <Combobox.Item
+            key={f.value}
+            value={f.value}
+            onSelect={(v) => { setValue(v); setOpen(false); }}
+          >
+            <CheckIcon className={value === f.value ? "" : "invisible"} />
+            {f.label}
+          </Combobox.Item>
+        ))}
+      </Combobox.Group>
+    </Combobox.List>
+  </Combobox.Content>
+</Combobox>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Combobox` | Wrapper / state holder |
+| `Trigger` | Element that opens (typically a button styled as input) |
+| `Content` | Floating panel with input + list |
+| `Input` | Search/filter input (auto-focused when open) |
+| `List` | Container for options (virtualizable) |
+| `Empty` | Shown when no items match query |
+| `Item` | Selectable option |
+| `Group` | Grouped section with optional heading |
+| `Separator` | Visual divider |
+
+## Variants
+
+### Single-select (default)
+
+One value at a time. Selecting closes the combobox.
+
+### Multi-select
+
+```tsx
+const [selected, setSelected] = useState<string[]>([]);
+
+<Combobox multiple value={selected} onValueChange={setSelected}>
+  <Combobox.Trigger asChild>
+    <Button>
+      {selected.length > 0
+        ? `${selected.length} 개 선택됨`
+        : "선택"}
+    </Button>
+  </Combobox.Trigger>
+  ...
+</Combobox>
+```
+
+Items show check on selected; combobox stays open while user picks multiple.
+
+### With creation (creatable)
+
+```tsx
+<Combobox.Item createable onSelect={() => createNew(query)}>
+  + Create "{query}"
+</Combobox.Item>
+```
+
+When user types and no exact match exists, show a "Create" item at the top.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Trigger only |
+| Open | Panel visible; input focused; first item highlighted |
+| Typing | List filters; first match highlighted |
+| Empty results | `Empty` component shown |
+| Selected (single) | Trigger shows selected label |
+| Selected (multi) | Trigger shows count or chips; checks visible in list |
+| Loading (async) | Skeleton or "Searching..." in list |
+| Disabled | Trigger grayed; no events |
+
+## Keyboard contract (WAI-ARIA Combobox pattern)
+
+| Key | Action |
+| --- | --- |
+| `Enter` / `Space` (on trigger) | Open |
+| Type in input | Filter list |
+| `↓` / `↑` | Navigate items |
+| `Home` / `End` | Jump to first / last |
+| `Enter` (on item) | Select; close (single) or stay open (multi) |
+| `Esc` | Close; return focus to trigger |
+| `Tab` | Close; move to next focusable in document |
+| Click outside | Close |
+
+## Tokens consumed
+
+```
+--color-bg-default                 (trigger field bg)
+--color-bg-overlay                 (panel bg)
+--color-fg-default
+--color-fg-muted                   (placeholder, group headings)
+--color-bg-overlay-hover           (item hover)
+--color-bg-overlay-selected        (current focused/highlighted item)
+--color-brand-default              (selected check icon)
+--color-border-default
+--shadow-overlay
+--radius-md
+--space-xs, --space-sm
+--font-size-base                   (input)
+--font-size-sm                     (group headings)
+--motion-fast                      (item hover)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- Trigger: `<button role="combobox" aria-expanded aria-haspopup="listbox" aria-controls="combo-list">`.
+- Input: separate from trigger when popup open; `role="combobox"` on input itself.
+- List: `role="listbox"` + `aria-label`.
+- Item: `role="option"` + `aria-selected`.
+- Use `aria-activedescendant` to indicate which item is highlighted (don't move focus to options; keep focus on input so typing works).
+- `aria-live="polite"` on List for screen reader to announce filter changes.
+- Touch target ≥ 36px per item.
+
+## Korean IME considerations
+
+Korean input uses IME (Input Method Editor) for Hangul composition. Three rules:
+
+1. **Don't trigger filter on every `keydown`** during composition — wait for `compositionend`.
+2. **Filter logic should match initial / 초성** — typing "ㄱ" might match "강원도", "기타" (initial-letter search common in Korean).
+3. **Cancel on Esc during composition** — Esc cancels IME composition first, then closes combobox on second press.
+
+```tsx
+const [query, setQuery] = useState("");
+const [composing, setComposing] = useState(false);
+
+<Combobox.Input
+  value={query}
+  onChange={(e) => !composing && setQuery(e.target.value)}
+  onCompositionStart={() => setComposing(true)}
+  onCompositionEnd={(e) => {
+    setComposing(false);
+    setQuery(e.currentTarget.value);
+  }}
+/>
+```
+
+## Code example — country picker
+
+```tsx
+function CountryPicker({ value, onChange }: Props) {
+  const [open, setOpen] = useState(false);
+  const country = COUNTRIES.find(c => c.code === value);
+
+  return (
+    <Combobox open={open} onOpenChange={setOpen}>
+      <Combobox.Trigger asChild>
+        <Button variant="outline" role="combobox">
+          {country ? `${country.flag} ${country.name}` : "국가 선택"}
+          <ChevronDownIcon />
+        </Button>
+      </Combobox.Trigger>
+      <Combobox.Content className="w-[280px] p-0">
+        <Combobox.Input placeholder="국가 검색..." />
+        <Combobox.List>
+          <Combobox.Empty>일치하는 국가가 없어요.</Combobox.Empty>
+          {COUNTRIES.map(c => (
+            <Combobox.Item
+              key={c.code}
+              value={c.name + " " + c.code}  // search token
+              onSelect={() => { onChange(c.code); setOpen(false); }}
+            >
+              <span className="mr-2">{c.flag}</span>
+              {c.name}
+              <CheckIcon
+                className={cn("ml-auto", value === c.code ? "" : "invisible")}
+              />
+            </Combobox.Item>
+          ))}
+        </Combobox.List>
+      </Combobox.Content>
+    </Combobox>
+  );
+}
+```
+
+## Edge cases
+
+- **Very long list (10,000+ items)**: virtualize. Use `react-virtual` inside Combobox.List.
+- **Async fetch as user types**: debounce input; show loading state in list.
+- **No exact match + creatable**: show "Create new" as last item.
+- **Selected value not in list** (stale data): Trigger shows ID or last-known label; refresh on next open.
+- **Disabled items**: render but skip on `Enter`.
+- **Mobile**: open as a Sheet (full-height) instead of a Popover for better thumb reach.
+- **Korean 초성 search** ("ㄱㅇㄷ" → matches "강원도"): requires custom search function with hangul-jaso library.
+
+## Don't
+
+- Don't use Combobox when a simple Select would do (< 20 items).
+- Don't trigger network search on every keystroke. Debounce 200-300ms.
+- Don't move focus to the option list — keep focus on input (use `aria-activedescendant`).
+- Don't hide the search input when there are < 5 items. Confusing — degrade gracefully to non-search list.
+- Don't show "0 results" without offering a creatable fallback OR a clear-filter shortcut.
+- Don't ignore Korean IME — Hangul composition events matter.
+
+## References
+
+- shadcn-ui: [`combobox`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/combobox.tsx)
+- WAI-ARIA: [Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- cmdk library
+
+## Cross-reference
+
+- [`examples/component-select.md`](component-select.md) — non-search variant
+- [`examples/component-auto-complete.md`](component-auto-complete.md) — freeform variant
+- [`examples/component-command.md`](component-command.md) — command palette (similar primitive)
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — IME handling

package/examples/component-command.md

@@ -0,0 +1,299 @@
+# `CommandPalette` — spec
+
+> Synthesized from shadcn-ui `command` (cmdk under the hood). Searchable command/action palette — the canonical "press Cmd+K" pattern popularized by VS Code, Linear, GitHub.
+
+## When to use
+
+- **Power-user shortcuts** for any action in the app.
+- **Search across multiple entity types** (users, files, settings, actions).
+- **Replace a sprawling main menu** for keyboard-driven UIs.
+- **AI command surface** — "ask AI", "generate X" entry points.
+
+When NOT to use:
+- Simple apps with < 20 actions — overkill.
+- Mobile-primary apps — keyboard shortcuts don't translate (long-press + on-screen invocation needed).
+
+## Anatomy
+
+```
+        [Cmd+K]
+            ↓
+┌──────────────────────────────────────┐
+│  ⌕  Type a command or search...      │
+│ ───────────────────────────────────── │
+│                                      │
+│  Suggestions                          │
+│  ─────────                            │
+│   ▶  Open file...           ⌘P       │
+│      Run command...         ⌘⇧P      │
+│      Toggle theme           ⌘L       │
+│                                      │
+│  Recent                              │
+│  ─────                                │
+│      design-system.md                │
+│      Profile settings                │
+│                                      │
+│  Search results — "compo"             │
+│  ────────────────────                 │
+│      Component spec                  │
+│      Compose new doc                 │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<CommandPalette open={open} onOpenChange={setOpen}>
+  <CommandPalette.Input placeholder="Type a command or search..." />
+  <CommandPalette.List>
+    <CommandPalette.Empty>No results found.</CommandPalette.Empty>
+
+    <CommandPalette.Group heading="Suggestions">
+      <CommandPalette.Item onSelect={openFile}>
+        <FileIcon /> Open file...
+        <CommandPalette.Shortcut>⌘P</CommandPalette.Shortcut>
+      </CommandPalette.Item>
+      <CommandPalette.Item onSelect={runCommand}>
+        <TerminalIcon /> Run command...
+        <CommandPalette.Shortcut>⌘⇧P</CommandPalette.Shortcut>
+      </CommandPalette.Item>
+    </CommandPalette.Group>
+
+    <CommandPalette.Separator />
+
+    <CommandPalette.Group heading="Recent">
+      {recentItems.map(item => (
+        <CommandPalette.Item key={item.id} onSelect={() => open(item)}>
+          {item.name}
+        </CommandPalette.Item>
+      ))}
+    </CommandPalette.Group>
+  </CommandPalette.List>
+</CommandPalette>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `CommandPalette` | Wrapper; manages state + keyboard |
+| `Input` | Search field (auto-focuses on open) |
+| `List` | Results container (virtualized for long lists) |
+| `Empty` | Shown when no items match query |
+| `Group` | Section with heading |
+| `Item` | Single command / result |
+| `Shortcut` | Keyboard hint (visual; doesn't bind keys) |
+| `Separator` | Visual divider |
+| `Loading` | Shown while async results load |
+
+## Keyboard contract
+
+| Key | Action |
+| --- | --- |
+| `Cmd+K` / `Ctrl+K` | Open globally |
+| Type | Filter items (substring + fuzzy) |
+| `↓` / `↑` | Navigate items |
+| `Enter` | Activate selected item |
+| `Esc` | Close (or clear input first if non-empty) |
+| `Tab` | Close (no internal tabbing) |
+| `Cmd+Enter` | Open in new tab / new window (if applicable) |
+
+Global hotkey activation requires app-level keyboard listener (separate from CommandPalette internals). Standard pattern:
+
+```tsx
+useEffect(() => {
+  const handler = (e: KeyboardEvent) => {
+    if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+      e.preventDefault();
+      setOpen(o => !o);
+    }
+  };
+  document.addEventListener("keydown", handler);
+  return () => document.removeEventListener("keydown", handler);
+}, []);
+```
+
+## Search modes
+
+### Fuzzy / substring (default)
+
+Type "comp" → matches "Component spec", "Compose new doc", "Compress files".
+
+cmdk uses substring + fuzzy by default with per-item scoring.
+
+### Pages / sub-commands
+
+Multi-step flows (think VS Code "Go to..." then "File / Symbol / Line"):
+
+```tsx
+{!page && (
+  <CommandPalette.Group heading="Navigate">
+    <CommandPalette.Item onSelect={() => setPage("files")}>Files</CommandPalette.Item>
+    <CommandPalette.Item onSelect={() => setPage("symbols")}>Symbols</CommandPalette.Item>
+  </CommandPalette.Group>
+)}
+
+{page === "files" && (
+  <CommandPalette.Group heading="Files">
+    {files.map(f => <CommandPalette.Item key={f.path}>{f.name}</CommandPalette.Item>)}
+  </CommandPalette.Group>
+)}
+```
+
+`Backspace` on empty input pops back to root page.
+
+### Async / remote search
+
+For server-fetched results (e.g., GitHub user search):
+
+```tsx
+const [query, setQuery] = useState("");
+const { data, isLoading } = useDebouncedQuery(query, 200);
+
+<CommandPalette.Input value={query} onValueChange={setQuery} />
+<CommandPalette.List>
+  {isLoading && <CommandPalette.Loading>Searching...</CommandPalette.Loading>}
+  {!isLoading && data?.length === 0 && <CommandPalette.Empty>No matches.</CommandPalette.Empty>}
+  {data?.map(item => <CommandPalette.Item key={item.id}>{item.name}</CommandPalette.Item>)}
+</CommandPalette.List>
+```
+
+Debounce input; show loading state; render empty state on no results.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Hidden |
+| Opening | Modal fade + scale (200ms) |
+| Open, no input | Show suggestions / recent |
+| Typing | Filter / fuzzy match in real-time |
+| Loading (async) | Shimmer or "Searching..." in List |
+| No results | `Empty` rendered |
+| Closing | Reverse |
+
+## Visual
+
+CommandPalette is a centered Modal (top-positioned more common):
+
+```
+[centered horizontally]
+[at ~20% from top of viewport (not center; users scan top-down)]
+```
+
+Width: 600-720px on desktop; near-full-width on mobile.
+
+Backdrop: scrim (semi-opaque dark). Click outside closes.
+
+## Tokens consumed
+
+```
+--color-bg-overlay-scrim       (backdrop)
+--color-bg-default             (palette bg)
+--color-fg-default
+--color-fg-muted               (groups, shortcut hints)
+--color-bg-secondary           (item hover bg)
+--color-brand-default          (selected item indicator)
+--color-border-default
+--shadow-overlay
+--radius-lg                    (palette container)
+--radius-md                    (items)
+--space-xs, --space-sm, --space-md
+--font-size-base               (input)
+--font-size-sm                 (group headings, shortcuts)
+--motion-fast                  (item hover)
+--motion-medium                (open/close)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- Wrapper: `role="dialog" aria-modal="true" aria-label="Command palette"`.
+- Input: `role="combobox" aria-expanded="true" aria-controls="cmdk-list" aria-activedescendant="<item-id>"`.
+- List: `role="listbox"`.
+- Item: `role="option" aria-selected="true|false"`.
+- Group: `role="group" aria-label="<heading>"`.
+- Empty: `role="status"` for "No results" announcement.
+- Focus trapped in palette; first item auto-selected after typing.
+- Touch target ≥ 36px per item.
+- Korean: Pretendard / NanumSquare body, Pretendard for input. Group headings 합쇼체 ("최근 항목") or English mixed.
+
+## Code example
+
+```tsx
+function GlobalCommandPalette() {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const navigate = useNavigate();
+
+  useGlobalHotkey("cmd+k", () => setOpen(true));
+
+  return (
+    <CommandPalette open={open} onOpenChange={setOpen}>
+      <CommandPalette.Input
+        value={query}
+        onValueChange={setQuery}
+        placeholder="명령어 또는 파일을 검색하세요..."
+      />
+      <CommandPalette.List>
+        <CommandPalette.Empty>일치하는 결과가 없어요.</CommandPalette.Empty>
+
+        <CommandPalette.Group heading="명령어">
+          <CommandPalette.Item onSelect={() => navigate("/new")}>
+            <PlusIcon /> 새 문서 만들기
+            <CommandPalette.Shortcut>⌘N</CommandPalette.Shortcut>
+          </CommandPalette.Item>
+          <CommandPalette.Item onSelect={() => toggleTheme()}>
+            <SunIcon /> 테마 전환
+            <CommandPalette.Shortcut>⌘⇧L</CommandPalette.Shortcut>
+          </CommandPalette.Item>
+        </CommandPalette.Group>
+
+        <CommandPalette.Group heading="최근 항목">
+          {recents.map(item => (
+            <CommandPalette.Item key={item.id} onSelect={() => navigate(item.path)}>
+              {item.name}
+            </CommandPalette.Item>
+          ))}
+        </CommandPalette.Group>
+      </CommandPalette.List>
+    </CommandPalette>
+  );
+}
+```
+
+## Edge cases
+
+- **Long lists (10,000+ items)**: virtualize the List (react-virtual / cmdk built-in).
+- **Disabled items**: render but skip on Enter; visually muted.
+- **Item with multiple actions** (open / open in new tab): show as separate items OR add an "actions" submenu (`Cmd+Enter` for secondary).
+- **Closing while async query in flight**: cancel request OR ignore late response.
+- **Korean IME composition**: don't treat composing characters as final input — debounce / wait for `compositionend`.
+- **Reduced motion**: skip the open/close animation; instant.
+- **Mobile**: full-width palette; on-screen keyboard handling — palette shrinks above keyboard.
+
+## Don't
+
+- Don't put critical actions ONLY in the palette. They need visible buttons too.
+- Don't forget Esc to close — accessibility foundation.
+- Don't over-pack one palette with 50+ groups; users get lost.
+- Don't put the search input below results — input always at top.
+- Don't lock keyboard shortcuts to one OS (`Cmd` only); use `Cmd` on Mac, `Ctrl` on Win/Linux.
+- Don't use CommandPalette as your only input method — must have alternatives.
+- Don't fail to debounce async queries — server load.
+
+## References
+
+- shadcn-ui: [`command`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/command.tsx) (cmdk-based)
+- cmdk library by pacocoursey
+- Patterns: VS Code Command Palette, Linear, GitHub global search, Slack `Cmd+K`
+- WAI-ARIA: combobox + listbox pattern
+
+## Cross-reference
+
+- [`examples/component-dropdown.md`](component-dropdown.md) — for non-search menus
+- [`examples/component-modal.md`](component-modal.md) — focus trap pattern
+- [`examples/component-auto-complete.md`](component-auto-complete.md) — single-field search
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)