@hegemonart/get-design-done 1.16.0 → 1.19.0

package/reference/components/breadcrumbs.md

@@ -0,0 +1,198 @@
+# Breadcrumbs — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Carbon, Polaris, Material 3, Atlassian
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A breadcrumb trail shows a user's location within a hierarchical navigation structure, providing a supplemental path back to any ancestor page. It is not primary navigation — the current page is always the last item and is never a link. Breadcrumbs are most valuable in deep hierarchies (> 2 levels) and information-dense applications. *(WAI-ARIA APG breadcrumb pattern, Carbon, Polaris, Material 3, Atlassian all define breadcrumb as a supplemental location indicator)*
+
+---
+
+## Anatomy
+
+```
+<nav aria-label="Breadcrumb">
+  <ol role="list">
+    <li><a href="/">Home</a></li>
+    <li><span aria-hidden="true">›</span><a href="/products">Products</a></li>
+    <li><span aria-hidden="true">›</span><span aria-current="page">Widget Pro</span></li>
+  </ol>
+</nav>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<nav>` container | Yes | `role="navigation"` + `aria-label="Breadcrumb"` |
+| `<ol>` list | Yes | Ordered list — sequence matters |
+| `<li>` items | Yes | One per level in the path |
+| Ancestor links | Yes | `<a href>` pointing to each ancestor URL |
+| Current page | Yes | Plain text `<span>` (not a link) + `aria-current="page"` |
+| Separator | Yes | `aria-hidden="true"` character or SVG icon; never in link text |
+| Ellipsis (deep paths) | No | Truncate middle items at > 4 levels; always keep first + last 2 |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Inline trail, all items visible | All systems |
+| Collapsed / truncated | Middle items replaced by "…" at > 4 levels | Carbon, Polaris, Atlassian |
+| With icons | Leading icon per item (folder/page icon) | Material 3, Atlassian |
+| Large / heading-inline | Larger type, sits beside or below a page title | Polaris, Atlassian |
+
+**Norm** (≥4 systems agree): separator is `aria-hidden`; current page uses `aria-current="page"`; last item is never a link.
+**Diverge**: Polaris uses `>` as separator; Carbon uses `/`; Material 3 uses `›` (chevron). All are acceptable — choose to match your product's visual language.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Ancestor links + muted separator + current page text | — |
+| link-hover | pointer over ancestor | Underline or color shift | — |
+| link-focus | keyboard focus on ancestor | 2px focus-visible ring | — |
+| current | — | No underline; muted or bold treatment; not clickable | `aria-current="page"` |
+| truncated | path > 4 levels | Middle items hidden; "…" button shown | `aria-label="Show full path"` on ellipsis button |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Item font size | 13–14px (body-sm) | Smaller than page headings; supplemental context |
+| Item height | 24–32px | Allow for comfortable touch targets on mobile |
+| Separator spacing | 4–8px H padding each side | Optical breathing room |
+| Max visible levels | 4 | Truncate middle items beyond 4 levels |
+| Truncation rule | Keep: first + last 2 items | Never truncate the current page or the root |
+
+**Norm**: 13–14px font size (Carbon, Polaris, Atlassian); items on a single line; no wrapping.
+
+---
+
+## Typography
+
+- Ancestor links: body-sm, weight 400, `color: --text-link`; underline on hover
+- Current page: body-sm, weight 500 or 600 (bold for emphasis), `color: --text-primary`; no underline
+- Separator: body-sm, `color: --text-subtle`, `aria-hidden="true"`
+- Do not use uppercase or letter-spacing on breadcrumb items — they should read as natural path segments
+
+Cross-link: `reference/typography.md` — body-sm, link color tokens
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `navigation` (container)
+> **Required attributes**: `aria-label="Breadcrumb"` on `<nav>`; `aria-current="page"` on last item; `aria-hidden="true"` on separators
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to next focusable link in the breadcrumb trail |
+| Shift+Tab | Moves focus to previous link |
+| Enter | Activates the focused link (navigates to ancestor) |
+
+### Accessibility Rules
+
+- `aria-current="page"` MUST be on the last item (current page) — this is the primary AT signal
+- Separators MUST be `aria-hidden="true"` — screen readers should announce "Home, Products, Widget Pro" not "Home › Products › Widget Pro"
+- The current page item MUST NOT be a link — it is the user's current location
+- `<ol>` conveys that order matters; do not use `<ul>` or a `<div>` list
+- `aria-label="Breadcrumb"` distinguishes this nav from primary/secondary navigation landmarks
+
+Cross-link: `reference/accessibility.md` — aria-current, landmark labelling
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Ellipsis expand | 150ms | ease-out | Reveal hidden items inline |
+| Ellipsis collapse | 120ms | ease-in | Hide middle items |
+
+**BAN**: Do not animate the breadcrumb trail on route change — route transitions are the page's responsibility, not the breadcrumb's.
+
+Cross-link: `reference/motion.md` — layout transitions
+
+---
+
+## Do / Don't
+
+### Do
+- Use `<ol>` for the list — order is meaningful in a hierarchical path *(WAI-ARIA APG)*
+- Mark the current page with `aria-current="page"` — not just a CSS class *(WAI-ARIA APG, Atlassian)*
+- Hide separators with `aria-hidden="true"` *(WAI-ARIA APG, Carbon, Polaris)*
+- Truncate middle items (not first/last) when path exceeds 4 levels *(Carbon, Polaris, Atlassian)*
+
+### Don't
+- Don't make the current page item a link — it creates a circular self-referential link *(WAI-ARIA APG)*
+- Don't include separator text inside link labels — `aria-hidden` the separator element, not the link *(WAI-ARIA APG)*
+- Don't use breadcrumbs as the only navigation method — they supplement; primary nav is required *(Material 3, Polaris)*
+- Don't truncate the root or current page items — users need anchoring context at both ends *(Carbon, Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-07 | Missing `aria-current` on active navigation items — `reference/anti-patterns.md#ban-07` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-label="Breadcrumb" on nav container | WAI-ARIA APG breadcrumb pattern |
+| Separator must be aria-hidden | WAI-ARIA APG, Carbon, Polaris, Atlassian |
+| Last item not a link + aria-current="page" | WAI-ARIA APG, Carbon, Polaris, Material 3 |
+| Ordered list (`<ol>`) for hierarchy | WAI-ARIA APG |
+| Truncate middle at > 4 levels | Carbon, Polaris, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Last breadcrumb item is a link (should be plain text with aria-current)
+grep -rn 'breadcrumb\|bread-crumb' src/ | grep -v 'aria-current="page"'
+
+# Separator not aria-hidden
+grep -rn 'breadcrumb' src/ | grep '›\|/\|>\|chevron' | grep -v 'aria-hidden'
+
+# Using <ul> instead of <ol> for breadcrumb
+grep -rn 'breadcrumb' src/ | grep '<ul'
+
+# nav container missing aria-label
+grep -rn 'breadcrumb' src/ | grep '<nav' | grep -v 'aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: all items are links including the current page, separators not hidden -->
+<nav>  <!-- missing aria-label="Breadcrumb" -->
+  <a href="/">Home</a> /
+  <a href="/products">Products</a> /
+  <a href="/products/widget-pro">Widget Pro</a>  <!-- should NOT be a link; no aria-current -->
+</nav>
+```
+
+**Why it fails**: Current page is a link (circular/confusing); separators `/` are announced by screen readers; `<nav>` has no label; no `aria-current="page"` to signal location to AT users; no `<ol>/<li>` structure loses hierarchy semantics.
+**Grep detection**: `grep -rn 'breadcrumb' src/ | grep -v 'aria-current'`
+**Fix**: Replace last `<a>` with `<span aria-current="page">Widget Pro</span>`; wrap separators in `<span aria-hidden="true">/</span>`; add `aria-label="Breadcrumb"` to `<nav>`; wrap items in `<ol><li>`.

package/reference/components/chip.md

@@ -0,0 +1,209 @@
+# Chip / Tag — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Atlassian, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A chip (or tag) is a compact, interactive label that represents an attribute, filter, or selection. It is commonly used for multi-select filter interfaces, tag-input fields (user-generated labels), one-time suggestion prompts, and static display labels. Each variant has distinct interaction semantics — filter chips toggle on/off, input chips are removable, suggestion chips trigger a one-time action, and display chips are static. *(Material 3, Carbon, Atlassian, Mantine agree on the four-variant taxonomy)*
+
+*UUPM app-interface: filter chips in search/filter UIs and tag input patterns (MIT attribution)*
+
+---
+
+## Anatomy
+
+```
+┌───────────────────────────────┐
+│ [icon?]  Label text  [✕ remove?] │
+└───────────────────────────────┘
+↑ role varies by variant
+↑ touch target ≥ 32px height
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label text | Yes | Concise (1–3 words typical) |
+| Container | Yes | Interactive element; role/type depends on variant |
+| Leading icon | No | 16px; left-aligned; 8px gap to label |
+| Remove button | Conditional | Required on input/tag chips; independent focusable element |
+| Selected state indicator | Conditional | Checkmark or filled style on toggled filter chips |
+
+---
+
+## Variants
+
+| Variant | Interaction | Role | Systems |
+|---------|-------------|------|---------|
+| Filter | Toggleable; multi-select | `aria-pressed` or `role="option"` in `role="listbox"` | Material 3, Carbon, Atlassian, Mantine |
+| Input / Tag | User-generated; removable via × button | `role="option"` in combobox; or `role="listbox"` child | Material 3, Atlassian, Mantine |
+| Suggestion | One-time select; fires an action then typically disappears | `role="button"` | Material 3, Mantine |
+| Display | Static label; no interaction | No role needed (or `role="listitem"`) | Atlassian (Lozenge), Carbon (Tag), Mantine |
+
+**Norm** (≥4/18 systems agree): filter chip uses `aria-pressed` for standalone toggles; input chip requires independent remove button with its own `aria-label`; display chip is decorative/static.
+**Diverge**: Material 3 calls static chips "Suggestion chips" when one-time-action and "Assist chips" for shortcut actions; Atlassian separates "Tag" (removable) from "Lozenge" (static status label); Carbon calls them "Tag" uniformly with a `filter` prop.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Rest fill + label | — |
+| hover | pointer over chip | Background tint (+8%) | — |
+| focus | keyboard focus on chip | focus-visible ring (2px) | — |
+| selected (filter) | click / Enter / Space | Filled background; checkmark icon | `aria-pressed="true"` |
+| unselected (filter) | click / Enter / Space | Outline style | `aria-pressed="false"` |
+| disabled | `disabled` / `aria-disabled` | 38% opacity; cursor not-allowed | `aria-disabled="true"` |
+| remove focus | Tab to × button | Focus ring on × | — |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Height | 32px (min touch target) | Do not reduce below 32px |
+| Padding-x | 12px | Each side; 8px when leading icon present |
+| Gap (icon → label) | 8px | |
+| Gap (label → remove ×) | 4px | |
+| Remove button size | 20×20px (visual); 32×32px (touch) | Extend touch area with padding |
+| Border radius | 16–20px (full pill) | *(Material 3: full-radius pill; Carbon: 4px; Atlassian: 2px)* |
+| Font size | 13–14px / 400 | |
+
+**Norm**: pill shape (full-radius) for filter and input chips *(Material 3, Mantine)*; Touch target ≥ 32px height *(WCAG 2.5.5, Material 3)*.
+
+---
+
+## Typography
+
+- Label: body-sm (13–14px/400) — same scale as form labels
+- No bold weight — chip label is a tag, not a heading or CTA
+- Truncate with ellipsis only when chip is in a fixed-width container; prefer wrapping chip set to natural width
+
+Cross-link: `reference/typography.md` — body-sm definition
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` (filter standalone, suggestion); `option` inside `listbox` (filter group, input chips)
+> **Required attributes**: `aria-pressed` on standalone filter chip; `aria-label` on remove button; `aria-selected` if `role="option"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to the chip or to the remove (×) button |
+| Enter / Space | Toggles filter chip (pressed/unpressed); activates suggestion chip |
+| Delete / Backspace | Removes an input/tag chip (when chip or its remove button has focus) |
+| Arrow Left / Right | Navigates between chips when inside a `role="listbox"` group |
+| Escape | Collapses chip group if it was expanded (e.g. overflow +N pattern) |
+
+### Accessibility Rules
+
+- Filter chip used as standalone toggle MUST have `aria-pressed="true|false"` — absence means screen readers cannot report toggle state *(WAI-ARIA APG)*
+- Filter chips inside a multi-select group SHOULD use `role="option"` inside `role="listbox"` with `aria-multiselectable="true"` *(WAI-ARIA APG)*
+- Remove button MUST have an independent `aria-label` describing what it removes: `aria-label="Remove Python tag"` — the × glyph alone is not an accessible name *(WAI-ARIA APG, Material 3)*
+- Remove button MUST be a separate focusable element, NOT a click handler on the chip label *(Carbon, Atlassian)*
+- Touch target for remove button MUST be ≥ 32×32px via padding even if the visual × is 16–20px *(WCAG 2.5.5)*
+- Display chips have no role — they are presentational; if they carry meaningful status, use `role="status"` or integrate into an Alert *(Atlassian Lozenge guidance)*
+
+Cross-link: `reference/accessibility.md` — `aria-pressed`, `listbox`, touch targets
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Toggle selected (background fill) | 100ms | ease-out | Background + checkmark appear |
+| Chip remove (collapse width) | 150ms | ease-in | Width collapses to 0, siblings shift |
+| Chip add (expand width) | 150ms | ease-out | Width expands from 0 |
+| Hover background | 80ms | ease-out | Subtle tint only |
+
+**BAN**: Full-page reflow animation when removing a chip — collapse width inline; do not shift unrelated page sections. Do not use `transition: all` (catches unintended border/shadow changes).
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip width animation, instant add/remove
+
+---
+
+## Do / Don't
+
+### Do
+- Add `aria-pressed` to standalone filter chips *(WAI-ARIA APG)*
+- Give remove buttons an independent `aria-label`: "Remove [label] tag" *(WAI-ARIA APG, Material 3)*
+- Use `role="listbox"` + `role="option"` for multi-select filter chip groups *(WAI-ARIA APG)*
+- Ensure touch target ≥ 32px height; extend remove button via padding *(WCAG 2.5.5)*
+
+### Don't
+- Don't put filter chips without `aria-pressed` — screen readers cannot report selected state *(WAI-ARIA APG)*
+- Don't use the same click handler for chip label and remove — remove must be independently focusable *(Carbon, Atlassian)*
+- Don't truncate chip label in narrow containers without a tooltip — truncated tags lose meaning *(Polaris, Mantine)*
+- Don't use display chips for dynamic statuses that change — use Alert or Badge instead *(Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Filter chip without aria-pressed | `reference/anti-patterns.md#ban-aria-pressed` |
+| Remove button without aria-label | `reference/anti-patterns.md#ban-aria-label` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-pressed on standalone filter chip | WAI-ARIA APG, Material 3, Carbon |
+| Remove button independent aria-label | WAI-ARIA APG, Material 3, Atlassian |
+| role="option" inside role="listbox" for group | WAI-ARIA APG |
+| Touch target ≥ 32px height | WCAG 2.5.5, Material 3 |
+| Delete/Backspace removes input chip | Material 3, Atlassian, Mantine |
+| UUPM filter/tag-input patterns | UUPM app-interface (MIT) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Filter chip missing aria-pressed
+grep -rn 'chip\|Chip\|filter-tag\|filterChip' src/ | grep -i 'filter\|toggle' | grep -v 'aria-pressed'
+
+# Remove button on chip missing aria-label
+grep -rn 'chip.*remove\|tag.*remove\|remove.*chip\|remove.*tag' src/ | grep -v 'aria-label'
+
+# Chip remove button without independent tab stop (not a separate button element)
+grep -rn 'chip\|tag' src/ | grep '×\|&times;\|✕\|close' | grep -v '<button\|role="button"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: filter chip with no aria-pressed — screen readers cannot report toggle state -->
+<div class="chip chip--filter" onclick="toggleFilter(this)">
+  Python
+</div>
+```
+
+**Why it fails**: `<div>` is not keyboard reachable. No `aria-pressed` means screen readers cannot determine if the filter is active or inactive. No `role="button"` or `tabindex` so keyboard users skip it entirely. No focus-visible ring.
+**Grep detection**: `grep -rn 'chip--filter\|filterChip\|chip.*filter' src/ | grep -v 'aria-pressed'`
+**Fix**:
+```html
+<button class="chip chip--filter"
+        aria-pressed="false"
+        onclick="toggleFilter(this)">
+  Python
+</button>
+```
+Update `aria-pressed` to `"true"` when selected.

package/reference/components/command-palette.md

@@ -0,0 +1,228 @@
+# Command Palette — Benchmark Spec
+
+**Harvested from**: Linear, Raycast, Radix CMDK, GitHub Primer, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation & Data
+
+---
+
+## Purpose
+
+A command palette is a keyboard-first global launcher that lets users search across commands, pages, and actions from anywhere in the application without navigating menus. Triggered by Cmd+K (macOS) / Ctrl+K (Windows/Linux), it provides fast access to frequently used actions and deep navigation. It is distinct from a local search input (scoped to one page) and from a Menu (contextual, anchored). *(Linear command palette, Raycast, Radix CMDK, GitHub Primer all converge on Cmd/Ctrl+K trigger + dialog + combobox + listbox pattern)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────┐
+│ role="dialog" aria-modal="true"                 │
+│ aria-label="Command palette"                    │
+│ ┌─────────────────────────────────────────────┐ │
+│ │ 🔍 [Search commands…              ]         │ │  role="combobox"
+│ └─────────────────────────────────────────────┘ │  aria-autocomplete="list"
+│ ┌─────────────────────────────────────────────┐ │
+│ │ role="listbox" id="cmd-results"             │ │
+│ │ ── Recent ──────────  role="group"          │ │
+│ │   Dashboard            role="option"        │ │
+│ │ ── Commands ──────────  role="group"        │ │
+│ │ ▶ New Project          role="option" ●      │ │  aria-selected="true"
+│ │   Invite member        role="option"        │ │
+│ └─────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Dialog overlay | Yes | `role="dialog"` + `aria-modal="true"` + `aria-label="Command palette"` |
+| Focus trap | Yes | Tab/Shift+Tab cycle within dialog only |
+| Search input | Yes | `role="combobox"` + `aria-expanded` + `aria-autocomplete="list"` + `aria-controls` |
+| Results list | Yes | `role="listbox"` + `id` (target of `aria-controls`) |
+| Result items | Yes | `role="option"` + `aria-selected` |
+| Section groups | No | `role="group"` + `aria-label` per section (Recent, Commands, Pages) |
+| Empty state | Yes | "No results for X" text; `aria-live="polite"` on result region |
+| Keyboard shortcut hints | No | `aria-hidden="true"`; display-only |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Cmd/Ctrl+K global trigger; full-width results | Linear, Raycast, Radix CMDK |
+| Inline search | Embedded within a page; narrower context | Primer, Atlassian |
+| Global search | Cross-section nav + recent pages + action shortcuts | UUPM app-interface (MIT) |
+| With categories | Grouped results by type (Recent / Commands / Pages) | Linear, Raycast, UUPM |
+| With icons | Category and action icons beside results | Linear, Raycast |
+| Nested commands | Select a command to reveal sub-commands | Raycast, Radix CMDK |
+
+**Norm** (≥4 systems agree): `role="dialog"` + focus trap + `role="combobox"` input + `role="listbox"` results.
+**Diverge**: Raycast supports nested command flows (select command → enter parameters); Linear/CMDK keep it flat for speed.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| closed | — | Dialog hidden | — |
+| open | Cmd/Ctrl+K | Dialog visible; input focused | `aria-expanded="true"` on combobox |
+| empty | no query | Placeholder or recent items | `aria-expanded="true"` |
+| searching | typing | Results update in real-time | `aria-live="polite"` on results region |
+| result-focus | ArrowDown/Up | Item highlighted | `aria-selected="true"` on option |
+| no-results | no matches | "No results for X" message | `aria-live="polite"` announces update |
+| loading | async search | Spinner in input or results | `aria-busy="true"` on listbox |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Dialog width | 560–640px | Centered horizontally |
+| Dialog max-height | 480px | Results region scrolls beyond this |
+| Input height | 48–56px | Generous; primary interaction surface |
+| Result item height | 40px | Icon + label + shortcut hint |
+| Section label height | 28px | Muted heading; non-interactive |
+| Backdrop | 40–60% opacity black | `rgba(0,0,0,0.5)`; click to dismiss |
+
+**Norm**: 560–640px width (Linear, Raycast, CMDK all converge). Input height 48px+ for legibility.
+
+---
+
+## Typography
+
+- Input placeholder: body-md (15–16px), `color: --text-placeholder`
+- Input value: body-md (15–16px), weight 400
+- Result item label: body-sm (13–14px), weight 400; matched substring bold/highlighted
+- Section heading: label-xs (11px), uppercase, weight 600, `color: --text-subtle`, `aria-hidden="true"` if role="group" handles it
+- Keyboard shortcut hints: label-xs (11px), `color: --text-subtle`, right-aligned, `aria-hidden="true"`
+
+Cross-link: `reference/typography.md` — body-md, label scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `dialog` (overlay), `combobox` (input), `listbox` (results), `option` (items), `group` (sections)
+> **Required attributes**: `aria-modal="true"` on dialog; `aria-label="Command palette"` on dialog; `aria-expanded` + `aria-autocomplete="list"` + `aria-controls` on combobox; `aria-selected` on options; `aria-label` on each `role="group"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ and https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Cmd+K / Ctrl+K | Opens the command palette (global shortcut) |
+| ArrowDown | Moves focus to first result (from input) or next result |
+| ArrowUp | Moves focus to previous result; loops to input |
+| Home | Moves focus to first result in list |
+| End | Moves focus to last result in list |
+| Enter | Executes the selected result |
+| Escape | Closes the palette; returns focus to trigger element |
+| Tab / Shift+Tab | Cycles focus within dialog (focus trap) |
+
+### Accessibility Rules
+
+- Dialog MUST have `aria-modal="true"` — prevents AT from reading content outside the palette
+- `role="combobox"` input MUST have `aria-controls` pointing to the `role="listbox"` `id`
+- `aria-live="polite"` on the results region ensures AT announces result count changes and empty state
+- Focus MUST be trapped within the dialog while it is open (Tab/Shift+Tab cycle inside)
+- On close, focus MUST return to the element that triggered the palette (not body)
+- Keyboard shortcut hints (`⌘K`, `↵`) MUST be `aria-hidden="true"` — the shortcut must be registered separately
+
+Cross-link: `reference/accessibility.md` — dialog focus trap, combobox pattern, live regions
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Dialog open | 150ms | ease-out | Scale 0.96→1 + opacity 0→1 |
+| Dialog close | 100ms | ease-in | Opacity 1→0 |
+| Results update | 80ms | ease-out | Fade new results; avoid reflow |
+| Backdrop fade in | 150ms | ease-out | Opacity 0→0.5 |
+| Item selection flash | 80ms | ease-out | Brief fill before execute |
+
+**BAN**: Do not animate result item reordering as the user types — causes visual instability and is disorienting for AT users with animations enabled.
+
+Cross-link: `reference/motion.md` — dialog entry, BAN-04
+
+---
+
+## Do / Don't
+
+### Do
+- Trap focus inside the dialog while open *(WAI-ARIA APG dialog pattern, WCAG 2.1.2)*
+- Set `aria-live="polite"` on the results region *(WCAG 4.1.3, Radix CMDK)*
+- Return focus to the trigger element on close *(WAI-ARIA APG)*
+- Use `role="group"` + `aria-label` for result sections *(WAI-ARIA APG, Linear, Raycast)*
+
+### Don't
+- Don't build a custom overlay without `role="dialog"` + `aria-modal` — screen readers will read background content *(WCAG 1.3.1)*
+- Don't omit `aria-controls` on the combobox — AT cannot associate input with results *(WAI-ARIA APG combobox)*
+- Don't open on hover or auto-focus — Cmd/Ctrl+K is the expected trigger *(Linear, Raycast convention)*
+- Don't dismiss on every Escape keypress inside nested command flows — first Escape should exit sub-level, second closes palette *(Raycast, Linear)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on results list — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="dialog" + aria-modal="true" + focus trap | WAI-ARIA APG dialog pattern |
+| role="combobox" + aria-controls for input | WAI-ARIA APG combobox pattern |
+| Cmd/Ctrl+K universal trigger | Linear, Raycast, GitHub, VS Code (industry convention) |
+| aria-live="polite" on results region | WAI-ARIA APG, WCAG 4.1.3 |
+| role="group" + aria-label for result sections | WAI-ARIA APG, Radix CMDK |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Dialog overlay missing aria-modal
+grep -rn 'command.*palette\|cmdk\|command-menu' src/ | grep 'role="dialog"' | grep -v 'aria-modal'
+
+# Combobox missing aria-controls pointing to listbox
+grep -rn 'role="combobox"' src/ | grep -v 'aria-controls'
+
+# Results listbox missing id (needed for aria-controls target)
+grep -rn 'role="listbox"' src/ | grep -v 'id='
+
+# Missing aria-live on results region
+grep -rn 'command.*palette\|cmd.*results\|cmdk' src/ | grep 'results\|listbox' | grep -v 'aria-live'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: custom overlay with keyboard handling but no ARIA roles -->
+<div class="command-palette" style="display:block">  <!-- no role="dialog", no aria-modal -->
+  <input type="text" placeholder="Search commands…">  <!-- no role="combobox", no aria-controls -->
+  <div class="results">  <!-- no role="listbox" -->
+    <div class="result-item active" onclick="execute('new-project')">
+      New Project
+    </div>
+    <div class="result-item" onclick="execute('invite')">
+      Invite member
+    </div>
+  </div>
+</div>
+```
+
+**Why it fails**: No `role="dialog"` — AT does not treat this as a modal, and screen readers continue reading background content; no focus trap; input lacks `role="combobox"` and `aria-controls`; results have no `role="listbox"`; items have no `role="option"` or `aria-selected`; no `aria-live` region for result updates.
+**Grep detection**: `grep -rn 'command.*palette\|cmdk\|command-menu' src/ | grep '<div' | grep -v 'role='`
+**Fix**: Use `role="dialog"` + `aria-modal="true"` on the overlay; implement focus trap; add `role="combobox"` + `aria-controls` to input; add `role="listbox"` to results container; add `role="option"` + `aria-selected` to each item; add `aria-live="polite"` to results region.