@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/link.md

@@ -0,0 +1,193 @@
+# Link — Benchmark Spec
+
+**Harvested from**: Carbon, Polaris, Primer (GitHub), Fluent 2, WAI-ARIA APG, Material 3, Mantine, Atlassian
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## Purpose
+
+A link navigates the user to a new resource — another page, section, or external URL. It is the semantic counterpart to Button: if clicking takes the user somewhere, it is a `<a href>` link; if it triggers an action in the current context, it is a button. Never reverse these roles. *(Carbon, Primer, WAI-ARIA APG all enforce this boundary)*
+
+---
+
+## Anatomy
+
+```
+Inline: Read the [full documentation] for details.
+         └── <a href="..."> — inline, within body text
+
+Standalone: [→ View report]
+             └── <a href="..."> — block-level, not inline in prose
+
+External: [Open dashboard ↗]
+           └── <a href="..." target="_blank" rel="noopener noreferrer">
+               + aria-label="Open dashboard (opens in new tab)"
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<a href>` | Yes | Native element; href MUST be a real URL or `#anchor` |
+| Visible label | Yes | Descriptive of destination — not "click here" or "read more" |
+| Underline | Conditional | Required for inline links in body text; optional for standalone/nav |
+| Visited state | No | Encouraged for inline links in long-form content |
+| External icon | Conditional | Required when `target="_blank"`; 12–14px, inline-aligned |
+| `rel="noopener noreferrer"` | Yes (external) | Security — prevents opener access |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Inline | Within prose; always underlined | All |
+| Standalone | Block-level CTA; underline optional | Carbon, Polaris, Primer |
+| Nav / breadcrumb | In navigation contexts; no underline | All |
+| External | `target="_blank"` with external icon | All |
+| Destructive | Rare; red colour for delete-via-link patterns | Polaris (critical link) |
+| Disabled | `aria-disabled="true"` + `tabindex="-1"` | Carbon, Primer |
+
+**Norm** (≥6/18): inline links in body text MUST be underlined — colour alone fails WCAG 1.4.1.
+**Diverge**: visited state — Primer and Carbon use it for documentation; most SaaS systems omit it.
+
+---
+
+## States
+
+| State | Visual | ARIA / HTML |
+|-------|--------|-------------|
+| default | Underline + colour | `href` present |
+| hover | Colour shift (10% darker/lighter) | — |
+| focus | 2px focus-visible ring | — |
+| active / pressed | Colour darkens + subtle scale 0.98 | — |
+| visited | Distinct colour (purple conventional) | `:visited` pseudo-class |
+| disabled | 38% opacity; pointer-events: none | `aria-disabled="true"` + `tabindex="-1"` |
+
+---
+
+## Sizing & Spacing
+
+- Links inherit parent font-size and line-height — do not override
+- Standalone link min-height: 44px via padding for touch targets
+- Icon size (external/leading): 12–14px; `vertical-align: middle`; 4px gap from text
+
+Cross-link: `reference/surfaces.md` — hit-area pattern for standalone links
+
+---
+
+## Typography
+
+- Inline links: same weight as surrounding text (400); underline distinguishes them
+- Standalone links: 400–500 weight; may have leading icon or trailing arrow
+- Never use ALL CAPS for links — reduces readability and implies different semantics
+- Truncate with ellipsis + `title` attribute only when space is genuinely constrained
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `link` (implicit on `<a href>`)
+> **Required attributes**: `href` — without it, the element is not a link and has no keyboard access
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/link/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter | Activates the link and navigates to its destination |
+| Tab | Moves focus to the next focusable element |
+| Shift+Tab | Moves focus to the previous focusable element |
+
+### Accessibility Rules
+
+- Link text MUST describe the destination — "click here" and "read more" fail 2.4.6 (descriptive labels)
+- External links opening in new tab MUST disclose this: append "(opens in new tab)" to `aria-label`, or use a visually-hidden span
+- `target="_blank"` MUST always be paired with `rel="noopener noreferrer"` (security + performance)
+- Disabled links: `aria-disabled="true"` + `tabindex="-1"` — never `href=""` or `href="#"`
+- Inline links in body text MUST be underlined — colour alone is insufficient for WCAG 1.4.1 (non-text contrast)
+- Icon-only links (e.g., social icons) MUST have `aria-label` describing the destination
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Colour on hover | 100ms | ease | Subtle; avoid opacity changes (readability) |
+| Underline decoration | 80ms | ease | Underline grow or fade for standalone variants |
+
+---
+
+## Do / Don't
+
+### Do
+- Use descriptive link text: "View account settings" not "click here" *(Polaris, Carbon, WAI-ARIA APG)*
+- Underline inline links in body text *(Carbon, Polaris, WAI-ARIA APG — WCAG 1.4.1)*
+- Add `rel="noopener noreferrer"` to all `target="_blank"` links *(Primer, Carbon, Fluent 2)*
+- Disclose new-tab behavior in `aria-label` or visually-hidden text *(WAI-ARIA APG, Primer)*
+
+### Don't
+- Don't use `<a>` without `href` — it's not a link, not keyboard-accessible, and will confuse screen readers *(WAI-ARIA APG)*
+- Don't use `<button>` when the action is navigation *(Carbon, Primer)*
+- Don't rely on colour alone to distinguish links from surrounding text *(WCAG 1.4.1)*
+- Don't open links in new tabs unexpectedly without disclosure *(Polaris, Primer, WCAG 3.2.5)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Anchor without href | `reference/anti-patterns.md` |
+| Non-descriptive link text | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Enter activates link | WAI-ARIA APG §3.3 |
+| Underline required for inline links | Carbon, Polaris, WCAG 1.4.1 |
+| rel="noopener noreferrer" for _blank | Primer, Carbon, Fluent 2 |
+| "click here" is anti-pattern | Polaris, Carbon, WAI-ARIA APG |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# <a> without href (not a link — no keyboard access)
+grep -rn '<a ' src/ | grep -v 'href='
+
+# target="_blank" without rel="noopener noreferrer"
+grep -rn 'target="_blank"' src/ | grep -v 'rel=.*noopener'
+
+# Non-descriptive link text
+grep -rn '>click here\|>read more\|>learn more\|>here<' src/ | grep -i '<a'
+
+# Colour-only link distinction (no text-decoration)
+grep -rn 'text-decoration:\s*none' src/ | grep -i 'link\|<a'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: non-descriptive link text + missing rel on external link -->
+<a href="https://docs.example.com" target="_blank">Click here</a>
+```
+
+**Why it fails**: "Click here" gives no destination context (fails WCAG 2.4.6). Missing `rel="noopener noreferrer"` is a security vulnerability. No disclosure of new-tab behavior.
+**Grep detection**: `grep -rn '>click here\|>here<\|>read more' src/`
+**Fix**:
+```html
+<a href="https://docs.example.com" target="_blank" rel="noopener noreferrer"
+   aria-label="View documentation (opens in new tab)">
+  View documentation <span aria-hidden="true">↗</span>
+</a>
+```

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).