@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/components/file-upload.md

@@ -0,0 +1,219 @@
+# File Upload — Benchmark Spec
+
+**Harvested from**: Polaris (DropZone), Carbon (FileUploader), Atlassian Design System, Material 3
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/file-upload.md`
+
+---
+
+## Purpose
+
+A File Upload component lets users attach one or more files by dragging them onto a drop zone or clicking to open the native file picker. It must work for all users: keyboard-only users activate the hidden-but-accessible `<input type="file">`, while pointer users can drag-drop. A file list tracks upload progress, status, and provides remove actions. *(Polaris, Carbon, Atlassian agree: drop zone + accessible file input + per-file status list is the canonical pattern.)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────┐
+│  Drop zone                      │
+│  [ Cloud icon ]                 │
+│  "Drag files here or"           │
+│  [ Browse files ] ← triggers    │
+│    <input type="file">          │
+└─────────────────────────────────┘
+
+File list (appears after selection):
+┌────────────────────────────────────────────────┐
+│ 📄 report.pdf  245 KB  [========   ] 80%  [✕] │
+│ 📄 photo.jpg   1.2 MB  ✓ Done             [✕] │
+│ 📄 data.csv    88 KB   ✗ Error            [✕] │
+└────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Drop zone container | Yes | Dashed border; drag-over changes fill + border color |
+| `<input type="file">` | Yes | MUST be accessible (not `display:none`) — keyboard fallback |
+| Browse trigger button | Yes | Visually activates the file input; must be a `<button>` or `<label>` |
+| File list | Yes (when files selected) | Per-file name, size, status, progress bar, remove button |
+| Progress bar | Yes (during upload) | `role="progressbar"` + `aria-valuenow` per file or overall |
+| Remove button | Yes | `aria-label="Remove [filename]"` |
+| Error region | Yes (on error) | `aria-live="assertive"` for upload errors |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Drop zone | Large dashed-border target area with drag-and-drop | Polaris, Carbon, Atlassian, Material 3 |
+| Compact / inline | Small "Attach file" button only; no large drop area | Carbon (FileUploaderItem), Atlassian |
+| Avatar/image uploader | Circular or rectangular crop zone for single image | Material 3, Polaris |
+| Multi-file | `multiple` attr; list of uploaded files | All systems |
+| Single-file | No `multiple`; replaces previous selection | Carbon, Polaris |
+
+**Norm** (≥3/4 systems agree): drop zone + browse button + file list is the standard desktop pattern; progress bar per file during upload.
+**Diverge**: Polaris auto-starts upload on drop; Carbon shows "Add files" button after initial selection to allow adding more; Material 3 defers to app logic.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Dashed border, instructional text | — |
+| drag-over | File dragged over zone | Filled background + solid border color change | `aria-dropeffect="copy"` (deprecated but still useful) |
+| drag-invalid | Wrong file type dragged over | Error border color; tooltip/message | — |
+| uploading | File being sent | Per-file progress bar animating | `aria-valuenow` on progressbar |
+| upload-done | Transfer complete | Check icon; status text "Done" | — |
+| upload-error | Transfer failed | Error icon; error message per file | `aria-live="assertive"` error region |
+| disabled | `disabled` prop | 38% opacity; drag events ignored | `aria-disabled="true"` on zone |
+
+---
+
+## Sizing & Spacing
+
+| Size | Drop Zone Min Height | Border Radius | Font |
+|------|---------------------|---------------|------|
+| sm | 80px | 4px | 13px |
+| md (default) | 128px | 8px | 14px |
+| lg | 200px | 12px | 16px |
+
+**Norm**: Drop zone should be large enough that it is comfortably hittable — 128px minimum height for default. File list rows are 48–56px tall for accessible remove-button target size *(Carbon, Polaris)*.
+
+Cross-link: `reference/surfaces.md` — minimum 44×44px touch targets for remove buttons.
+
+---
+
+## Typography
+
+- Drop zone instruction: body-md, centered, secondary color
+- "Browse files" link/button: body-md, primary link or button style
+- File name in list: body-sm, truncated with ellipsis (max-width on container), full name in `title` attribute
+- File size: caption-sm, secondary color
+- Status text (Done / Error): caption-sm, success or error semantic color
+
+Cross-link: `reference/typography.md` — truncation rules.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` (browse trigger); `progressbar` (upload progress); `status` or `log` (file list updates)
+> **Required attributes**: `aria-label="Remove [filename]"` on remove buttons; `aria-valuenow` + `aria-valuemin` + `aria-valuemax` on progressbar; `aria-live="assertive"` on error region
+
+### Keyboard Contract
+
+*Derived from native `<input type="file">` behavior and WAI-ARIA APG button pattern — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to browse button / file input |
+| Enter / Space | Activate browse button — opens native file picker dialog |
+| Tab (in file list) | Move through file items and remove buttons |
+| Enter / Space (on remove button) | Remove file from list |
+
+Drag-and-drop is pointer-only; keyboard users MUST be able to complete the entire task via the file input alone.
+
+### Accessibility Rules
+
+- `<input type="file">` MUST NOT use `display:none` or `visibility:hidden` — use `opacity:0` positioned absolutely with dimensions matching the trigger, OR keep a visible file input alongside the drop zone
+- The browse trigger MUST be a `<button>` or `<label for="file-input">` so it is keyboard-focusable and activates the input
+- Remove buttons MUST have `aria-label="Remove [filename]"` — an icon-only ✕ with no accessible name fails AT users
+- Upload errors MUST be announced via `aria-live="assertive"` — do not rely solely on visual indicators
+- Progress bars MUST keep `aria-valuenow` updated throughout upload
+- `accept` attribute MUST match the visible allowed-types hint text so users are not surprised by rejection
+- File list additions/removals should be announced via `aria-live="polite"` on the list container
+
+Cross-link: `reference/accessibility.md` — aria-live regions, accessible file input patterns.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Drop zone drag-over | 100ms | ease-out | Background fill + border color |
+| File list item enter | 200ms | ease-out | Slide-in from top or fade-in |
+| File list item remove | 150ms | ease-in | Fade + collapse height |
+| Progress bar fill | continuous | linear | Matches upload byte progress |
+| Upload complete tick | 200ms | ease-out | Check icon draw animation |
+
+**BAN**: Do not animate progress bar with CSS only at a fixed pace — progress MUST reflect actual upload percentage via `aria-valuenow`.
+
+Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animations; keep progress bar updates.
+
+---
+
+## Do / Don't
+
+### Do
+- Keep `<input type="file">` accessible at all times (opacity:0 trick or visible) *(WAI-ARIA, Polaris, Carbon)*
+- Provide `aria-label="Remove [filename]"` on every remove button *(Carbon, Atlassian)*
+- Show file name, size, and status in the file list *(Polaris, Carbon, Atlassian)*
+- Announce upload errors via `aria-live="assertive"` *(WCAG 2.1 §4.1.3 Status Messages)*
+
+### Don't
+- Don't use `display:none` on the file input — keyboard and AT users cannot trigger the picker *(WCAG 2.1 §2.1.1)*
+- Don't omit the `accept` hint text — users should know allowed types before selecting *(Polaris, Carbon)*
+- Don't show only drag-drop UI with no browse button — drag is inaccessible to keyboard users *(Carbon, Atlassian)*
+- Don't use a generic `aria-label="Remove"` on remove buttons — AT users cannot identify which file *(Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-08 | File input hidden with display:none — keyboard inaccessible — `reference/anti-patterns.md#ban-08` |
+| BAN-13 | Icon-only action button without aria-label — `reference/anti-patterns.md#ban-13` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| input type="file" must not be display:none | WCAG 2.1 §2.1.1, Carbon, Polaris accessibility guides |
+| Remove button needs aria-label="Remove [filename]" | Carbon FileUploader, Atlassian, Polaris |
+| Upload errors need aria-live="assertive" | WCAG 2.1 §4.1.3, Material 3 |
+| Progress bar needs aria-valuenow updates | WAI-ARIA progressbar role spec |
+| Drag-over state: background fill + border change | Polaris, Carbon, Atlassian drop zone specs |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# File input hidden with display:none (keyboard inaccessible)
+grep -rn 'type="file"' src/ | grep -v 'opacity\|position.*absolute' | grep 'display.*none\|visibility.*hidden'
+
+# Remove button missing aria-label (icon-only, no accessible name)
+grep -rn 'remove.*button\|btn.*remove\|✕\|×' src/ | grep -v 'aria-label'
+
+# Progress bar missing aria-valuenow
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuenow'
+
+# Upload error region without aria-live
+grep -rn 'upload.*error\|file.*error\|error.*upload' src/ | grep -v 'aria-live'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: drop zone with display:none on the actual <input> — keyboard and AT users can't trigger file picker -->
+<div class="drop-zone" ondrop="handleDrop(event)" ondragover="handleDragOver(event)">
+  <p>Drag files here</p>
+  <input type="file" id="file-input" style="display:none" onchange="handleFiles(event)">
+  <button onclick="document.getElementById('file-input').click()">Browse</button>
+</div>
+```
+
+**Why it fails**: `display:none` removes the input from accessibility tree and tab order. The JavaScript `.click()` workaround does not work reliably with all AT. Keyboard users pressing Enter/Space on "Browse" may get inconsistent behavior across browsers. Screen reader users cannot discover or activate the file input directly.
+**Grep detection**: `grep -rn 'type="file".*display.*none\|display.*none.*type="file"' src/`
+**Fix**: Use `opacity:0; position:absolute; width:100%; height:100%` on the input (matching the browse button dimensions), or place a visible `<input type="file">` and style the button as a `<label for="file-input">` so clicking the label activates the input natively without JavaScript.

package/reference/components/list.md

@@ -0,0 +1,217 @@
+# List (Interactive & Display) — Benchmark Spec
+
+**Harvested from**: Carbon, Polaris, Material 3, Mantine, WAI-ARIA APG, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation & Data
+
+---
+
+## Purpose
+
+A list component handles two distinct patterns: (1) a display list renders a series of items using semantic `<ul>/<ol>/<li>` HTML — no ARIA needed; (2) an interactive list (listbox) presents selectable options with keyboard navigation and selection state. Use a display list for content; use an interactive listbox when users choose one or more items from a set. *(Carbon, Polaris, Material 3 all define separate display and interactive list patterns)*
+
+---
+
+## Anatomy
+
+```
+Display list:              Interactive listbox:
+<ul>                       <div role="listbox"
+  <li>Item one</li>              aria-multiselectable="false"
+  <li>Item two</li>              aria-label="Assignees">
+  <li>Item three</li>       <div role="option"
+</ul>                              aria-selected="true">Alice</div>
+                             <div role="option"
+                                   aria-selected="false">Bob</div>
+                           </div>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| List container | Yes | `<ul>` / `<ol>` (display) or `role="listbox"` (interactive) |
+| List item | Yes | `<li>` (display) or `role="option"` (interactive) |
+| `aria-selected` | Interactive only | `true`/`false` on each `role="option"` |
+| `aria-multiselectable` | Interactive only | `true` if multi-select; default `false` |
+| `aria-label` / `aria-labelledby` | Interactive only | Describes the listbox purpose |
+| Empty state | No | Min 200px height; illustration + message + optional CTA |
+| Virtual scroll | Conditional | At > 100 items; TanStack Virtual or react-virtual |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Unordered display | `<ul>` bullet list; purely semantic | All systems |
+| Ordered display | `<ol>` numbered list; sequential content | All systems |
+| Single-select listbox | One item selectable at a time | Carbon, Polaris, Material 3 |
+| Multi-select listbox | Multiple items selectable (Shift+Click, Ctrl+Click) | Carbon, Material 3, Mantine |
+| List / detail panel | Left-panel list + right detail pane | UUPM app-interface (MIT) |
+| Recent-items list | Time-ordered recent items with timestamps | UUPM app-interface (MIT) |
+| Virtualized | Windowed rendering for large datasets (> 100 items) | Carbon, Mantine |
+
+**Norm** (≥4 systems agree): `role="listbox"` + `role="option"` for interactive; native `<ul>/<li>` for display.
+**Diverge**: Material 3 calls the interactive variant "ListItem with selectable state"; Carbon uses "ContentSwitcher" for small sets and "MultiSelect" for large. Pattern semantics are identical.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Items visible; none selected | `aria-selected="false"` on all options |
+| option-hover | pointer over | 8% overlay | — |
+| option-focus | keyboard focus | 2px focus-visible ring | managed via `tabindex` |
+| option-selected | click or Enter/Space | Filled highlight; checkmark for multi-select | `aria-selected="true"` |
+| option-disabled | disabled prop | 38% opacity; cursor: default | `aria-disabled="true"` |
+| empty | no items | Empty state (illustration + text + CTA) | `aria-label` on empty container |
+| loading | data fetch | Skeleton items | `aria-busy="true"` on listbox container |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Item height | 40px (default) | 32px compact; 48px comfortable |
+| Item padding H | 12–16px | Icon + 8px gap if icon present |
+| Empty state min-height | 200px | Prevents visually collapsed empty container |
+| Virtual viewport | ~400–600px | Clip height for virtualised scroll |
+| List max-height | 400px default | Scroll within list container |
+
+**Norm**: 40px item height (Carbon, Polaris, Mantine). Max-height + internal scroll for contained lists.
+
+---
+
+## Typography
+
+- Display list: inherits parent body text; `<li>` marker via `list-style-type`
+- Interactive option label: body-sm (13–14px), weight 400; selected weight 500
+- Secondary text / metadata: label-xs (11–12px), `color: --text-subtle`
+- Empty state heading: heading-sm, center-aligned
+- Empty state body: body-sm, `color: --text-subtle`
+
+Cross-link: `reference/typography.md` — body-sm, heading scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `listbox` (interactive container), `option` (each item)
+> **Required attributes**: `aria-selected` on each `role="option"`; `aria-label` or `aria-labelledby` on `role="listbox"`; `aria-multiselectable="true"` for multi-select
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| ArrowDown | Moves focus to next option (wraps to first) |
+| ArrowUp | Moves focus to previous option (wraps to last) |
+| Home | Moves focus to first option |
+| End | Moves focus to last option |
+| Enter / Space | Selects the focused option (single-select) |
+| Shift+ArrowDown | Extends selection downward (multi-select) |
+| Shift+ArrowUp | Extends selection upward (multi-select) |
+| Ctrl+A | Selects all options (multi-select) |
+| A–Z | Moves focus to next option starting with typed character |
+
+### Accessibility Rules
+
+- Display lists use native `<ul>/<li>` — no ARIA roles needed; they are already accessible
+- Interactive lists MUST use `role="listbox"` + `role="option"` — not `<ul>/<li>` with click handlers
+- `aria-selected` MUST be present on every `role="option"` (either `true` or `false`)
+- Multi-select listbox MUST declare `aria-multiselectable="true"` on the container
+- Virtual scroll: all options in the virtualised window must have correct `aria-posinset` and `aria-setsize` attributes
+- Empty state container MUST have `aria-label` or `aria-live` so AT announces the empty state
+
+Cross-link: `reference/accessibility.md` — listbox pattern, virtual list accessibility
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Option selection highlight | 100ms | ease-out | Background color only |
+| Skeleton item shimmer | 1500ms | linear loop | Loading placeholder |
+| Empty state entry | 150ms | ease-out | Fade in |
+
+**BAN**: Do not animate item reordering unless using a deliberate drag-and-drop library — unsolicited reordering causes disorientation.
+
+Cross-link: `reference/motion.md` — skeleton shimmer, list animations
+
+---
+
+## Do / Don't
+
+### Do
+- Use native `<ul>/<ol>/<li>` for display-only lists — no ARIA needed *(WAI-ARIA APG)*
+- Use `role="listbox"` + `role="option"` for selectable lists *(WAI-ARIA APG, Carbon, Polaris)*
+- Virtualise at > 100 items to prevent DOM bloat *(Carbon, Mantine)*
+- Provide a meaningful empty state with a CTA when the list can be populated *(Polaris, Material 3)*
+
+### Don't
+- Don't use `<div onClick>` list items without `role="option"` — keyboard-inaccessible *(WCAG 2.1.1)*
+- Don't omit `aria-selected` on options — AT cannot determine what is selected *(WAI-ARIA APG)*
+- Don't use `<ul>/<li>` with `role="option"` — mixing native list semantics and listbox ARIA creates conflicts *(WAI-ARIA)*
+- Don't load all items at once when count > 100 — renders slowly and wastes memory *(Carbon, Mantine)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="listbox" + role="option" for interactive lists | WAI-ARIA APG listbox pattern |
+| aria-selected required on every option | WAI-ARIA APG, Carbon, Polaris |
+| aria-multiselectable="true" for multi-select | WAI-ARIA APG |
+| Virtualise at > 100 items | Carbon, Mantine (TanStack Virtual) |
+| 200px min empty state height | Carbon, Polaris HIG |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Interactive list items using <div> without role="option"
+grep -rn '<div' src/ | grep -i 'list.*item\|list-item\|listitem' | grep 'onClick\|on:click' | grep -v 'role='
+
+# Missing aria-selected on option elements
+grep -rn 'role="option"' src/ | grep -v 'aria-selected'
+
+# Listbox missing aria-label
+grep -rn 'role="listbox"' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# <ul>/<li> used with role="option" (semantics conflict)
+grep -rn 'role="option"' src/ | grep '<li'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: interactive list items using <div onClick> with no keyboard support -->
+<div class="user-list">  <!-- no role="listbox" -->
+  <div class="list-item selected" onclick="selectUser('alice')">
+    Alice Chen
+  </div>
+  <div class="list-item" onclick="selectUser('bob')">
+    Bob Tanaka
+  </div>
+</div>
+```
+
+**Why it fails**: No `role="listbox"` on container; no `role="option"` on items; no `aria-selected`; items not keyboard-focusable (no `tabindex`); arrow-key navigation does nothing; screen readers see two unlabelled `<div>` elements.
+**Grep detection**: `grep -rn '<div.*onClick\|<div.*on:click' src/ | grep -i 'list.*item\|listitem'`
+**Fix**: Use `<div role="listbox" aria-label="Users">` with `<div role="option" tabindex="-1" aria-selected="false">` items; implement roving `tabindex` and arrow-key handlers.

package/reference/components/menu.md

@@ -0,0 +1,212 @@
+# Menu (Dropdown / Context Menu) — Benchmark Spec
+
+**Harvested from**: Radix UI, WAI-ARIA APG, Carbon, Atlassian, Material 3, Polaris
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A menu presents a list of actions or options in a temporary overlay anchored to a trigger element. It differs from a Select/Combobox (which chooses a value) — a menu executes commands or navigates. Use a Dropdown Menu for trigger-button scenarios; use a Context Menu for right-click/long-press on an element. *(Radix DropdownMenu, Carbon OverflowMenu, Atlassian DropdownMenu, WAI-ARIA APG Menu agree: menus are action lists, not value selectors)*
+
+---
+
+## Anatomy
+
+```
+[ Trigger Button ▾ ]
+┌─────────────────────┐
+│  ✓ Menu Item        │  role="menuitemcheckbox"
+│  ── Separator ──    │  role="separator"
+│  › Sub-menu Item    │  role="menuitem" aria-haspopup="menu"
+│    Edit             │  role="menuitem"
+│    Delete           │  role="menuitem"
+└─────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Trigger | Yes | `<button>` with `aria-haspopup="menu"` + `aria-expanded` |
+| Menu container | Yes | `role="menu"` + `aria-labelledby` pointing to trigger |
+| Menu item | Yes | `role="menuitem"` on each action |
+| Separator | No | `role="separator"` — groups related items |
+| Checkbox item | No | `role="menuitemcheckbox"` + `aria-checked` |
+| Radio item | No | `role="menuitemradio"` + `aria-checked`; group in `role="group"` |
+| Sub-menu trigger | No | `role="menuitem"` + `aria-haspopup="menu"` + `aria-expanded` |
+| Focus indicator | Yes | 2px focus-visible ring on keyboard-active item |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Dropdown menu | Opens from a button trigger; anchored below/above | Radix, Carbon, Atlassian, Polaris |
+| Context menu | Opens at pointer position on right-click or long-press | Radix, Material 3, Carbon |
+| Overflow menu | Icon-only trigger (⋯ or ⋮); common in dense UIs | Carbon OverflowMenu, Atlassian |
+| Sub-menu | Cascading child menu opening on ArrowRight | Radix, Atlassian, Carbon |
+| Checkbox/radio menu | Items with persistent checked state | Radix, Carbon, Material 3 |
+
+**Norm** (≥4 systems agree): flat action list with separator groups; avoid > 2 nesting levels.
+**Diverge**: Polaris uses ActionList as a shared primitive for both menus and select options; Carbon splits OverflowMenu from ContextMenu as separate components.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| closed | — | Trigger visible; overlay hidden | `aria-expanded="false"` on trigger |
+| open | Click trigger | Overlay visible; first item focused | `aria-expanded="true"` on trigger |
+| item-hover / focus | Arrow keys or pointer | Item highlight (8% overlay) | `tabindex="-1"` managed via roving tabindex |
+| item-disabled | `disabled` prop | 38% opacity, cursor: default | `aria-disabled="true"` on item |
+| checked | Toggle menuitemcheckbox | Checkmark icon visible | `aria-checked="true"` |
+| submenu-open | ArrowRight on parent | Child menu visible | `aria-expanded="true"` on parent item |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Min menu width | 160px | Prevents awkward narrow menus |
+| Max menu width | 320px | Truncate labels with ellipsis beyond |
+| Item height | 36px (md) | 32px compact, 40px comfortable |
+| Item padding H | 12px | Icon if present: 16px left + 8px gap |
+| Separator height | 1px + 4px V margin | Divider line |
+| Icon size | 16px | Left-aligned, consistent with label baseline |
+
+**Norm**: 36px item height (Radix default, Carbon, Atlassian). Min-width 160px prevents single-word menus.
+
+---
+
+## Typography
+
+- Item label: body-sm (13–14px), weight 400 — not bold; action labels read as text, not controls
+- Destructive items: same weight, color token `--color-text-danger`
+- Keyboard shortcut hints: body-xs (11–12px), muted color, right-aligned, `aria-hidden="true"`
+- Truncate item labels with `text-overflow: ellipsis`; never wrap item text
+
+Cross-link: `reference/typography.md` — body-sm scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `menu` (container), `menuitem` / `menuitemcheckbox` / `menuitemradio` (items)
+> **Required attributes**: `aria-haspopup="menu"` + `aria-expanded` on trigger; `aria-labelledby` on `role="menu"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter / Space | Opens menu from trigger; activates focused item |
+| ArrowDown | Moves focus to next item (wraps to first) |
+| ArrowUp | Moves focus to previous item (wraps to last) |
+| Escape | Closes menu; returns focus to trigger |
+| Tab | Closes menu; moves focus to next focusable element (does not cycle through items) |
+| Home | Moves focus to first item |
+| End | Moves focus to last item |
+| A–Z / a–z | Moves focus to next item starting with that character |
+| ArrowRight | Opens sub-menu; moves focus to first item of sub-menu |
+| ArrowLeft | Closes sub-menu; returns focus to parent item |
+
+### Accessibility Rules
+
+- Menu MUST open on click only — never on hover for primary open (hover may preview sub-menus)
+- All items MUST be reachable by keyboard; no mouse-only items
+- Focus returns to the trigger element when the menu closes
+- Keyboard shortcut labels (e.g. "⌘K") are `aria-hidden="true"` — the shortcut must be registered separately
+- `role="separator"` dividers are not focusable
+- Disabled items use `aria-disabled="true"` (keep focusable so AT users know the option exists)
+
+Cross-link: `reference/accessibility.md` — focus management, roving tabindex
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Menu enter | 120ms | ease-out | Scale 0.95→1 + opacity 0→1 from anchor point |
+| Menu exit | 80ms | ease-in | Opacity 1→0; skip scale-down for speed |
+| Item highlight | 80ms | ease-out | Background color transition only |
+| Sub-menu enter | 120ms | ease-out | Same as menu enter |
+
+**BAN**: `transition: all` on menu items — triggers layout thrash on width changes.
+
+Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="menu"` + `role="menuitem"` for all action menus *(WAI-ARIA APG)*
+- Group related items with `role="separator"` — keep groups ≤ 7 items *(Carbon, Atlassian)*
+- Return focus to the trigger on close *(WAI-ARIA APG)*
+- Use `role="menuitemcheckbox"` for persistent toggle states *(Radix, Material 3)*
+
+### Don't
+- Don't open the menu on hover as the primary interaction — keyboard users can't discover hover *(WCAG 1.3.3)*
+- Don't exceed 2 levels of sub-menus — deeply nested menus are cognitively expensive *(Atlassian, Carbon)*
+- Don't put form controls (inputs, sliders) inside a menu — use a Popover instead *(WAI-ARIA APG)*
+- Don't use `<div>` items without `role="menuitem"` — invisible to screen readers *(WAI-ARIA)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="menu" + role="menuitem" contract | WAI-ARIA APG Menu Button pattern |
+| Click-only open (not hover) | WAI-ARIA APG, WCAG 1.3.3, Carbon |
+| ArrowRight/Left for sub-menu navigation | WAI-ARIA APG, Radix DropdownMenu |
+| Focus returns to trigger on close | WAI-ARIA APG, Radix |
+| 36px item height | Radix default, Carbon OverflowMenu, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Menu container missing role="menu"
+grep -rn 'dropdown\|context-menu\|overflow-menu' src/ | grep -v 'role="menu"'
+
+# Items using <div> without role="menuitem"
+grep -rn '<div' src/ | grep -i 'menu-item\|menuitem\|menu__item' | grep -v 'role='
+
+# Trigger missing aria-haspopup
+grep -rn 'aria-expanded' src/ | grep -i 'menu\|dropdown' | grep -v 'aria-haspopup'
+
+# Missing aria-labelledby on menu container
+grep -rn 'role="menu"' src/ | grep -v 'aria-labelledby\|aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: div list with click handlers but no ARIA roles -->
+<div class="dropdown-menu">
+  <div class="dropdown-item" onclick="handleEdit()">Edit</div>
+  <div class="dropdown-item" onclick="handleDelete()">Delete</div>
+</div>
+```
+
+**Why it fails**: No `role="menu"` or `role="menuitem"` — screen readers cannot announce this as a menu; items are not keyboard-navigable; no arrow-key navigation; trigger lacks `aria-haspopup` and `aria-expanded`.
+**Grep detection**: `grep -rn '<div.*onclick\|<div.*onClick' src/ | grep -i 'menu\|dropdown'`
+**Fix**: Use `<ul role="menu">` with `<li role="menuitem" tabindex="-1">` items, or a headless menu primitive (Radix DropdownMenu, Downshift).