@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/components/input.md

@@ -1,4 +1,4 @@
-# Input — Benchmark Spec
+# Input - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Ant Design, Mantine, Polaris, Fluent 2, Atlassian, shadcn/ui
 **Wave**: 1 · **Category**: Inputs
@@ -47,7 +47,7 @@ Label *                     ← <label for="id"> — always visible
 | Number | `type="number"` or `inputmode="numeric"` | Material 3, Ant, Mantine |
 
 **Norm** (≥6/18): outlined with floating or static label is the most-cited default.
-**Diverge**: floating vs. static label — Material 3 uses floating; Carbon, Polaris, Atlassian use static (above). Static label is safer for a11y (floating requires JavaScript + ARIA management).
+**Diverge**: floating vs. static label - Material 3 uses floating; Carbon, Polaris, Atlassian use static (above). Static label is safer for a11y (floating requires JavaScript + ARIA management).
 
 ---
 
@@ -55,14 +55,14 @@ Label *                     ← <label for="id"> — always visible
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Resting border | — |
-| hover | pointer over | Border lightens 20% | — |
-| focus | keyboard / click | 2px focus-visible ring or thickened border | — |
-| filled | has value | Label lifts (floating) or stays static | — |
+| default | - | Resting border | - |
+| hover | pointer over | Border lightens 20% | - |
+| focus | keyboard / click | 2px focus-visible ring or thickened border | - |
+| filled | has value | Label lifts (floating) or stays static | - |
 | disabled | `disabled` attr | 38% opacity; cursor: not-allowed | `disabled` attr |
 | read-only | `readonly` attr | No border change; cursor: default | `readonly` attr |
 | error | invalid | Red/error border + icon + error message | `aria-invalid="true"` + `aria-describedby` |
-| success | valid (opt.) | Green border + check icon | — |
+| success | valid (opt.) | Green border + check icon | - |
 
 ---
 
@@ -75,20 +75,20 @@ Label *                     ← <label for="id"> — always visible
 | lg | 48px | 16px | 16px | 16px |
 
 **Norm**: 40px default height (Carbon, Polaris, Fluent, Atlassian confirm).
-Minimum width: 200px — narrower inputs invite input truncation and frustrate users.
+Minimum width: 200px - narrower inputs invite input truncation and frustrate users.
 
-Cross-link: `reference/surfaces.md` — hit area ≥44px via padding; `reference/typography.md` — label sizing.
+Cross-link: `reference/surfaces.md` - hit area ≥44px via padding; `reference/typography.md` - label sizing.
 
 ---
 
 ## Typography
 
 - Label: 14px/500 above input; 12px when floating in focus/filled state
-- Placeholder: 14px/400; color at 40% contrast minimum — never the only label
+- Placeholder: 14px/400; color at 40% contrast minimum - never the only label
 - Helper/error: 12px/400; full contrast for error messages
 - **Placeholder is not a label**: it disappears on type, fails contrast, and cannot be announced by screen readers as a persistent label
 
-Cross-link: `reference/typography.md` — text-wrap, font-smoothing rules
+Cross-link: `reference/typography.md` - text-wrap, font-smoothing rules
 
 ---
 
@@ -99,7 +99,7 @@ Cross-link: `reference/typography.md` — text-wrap, font-smoothing rules
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/textbox/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/textbox/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -115,7 +115,7 @@ Password toggle and clear button must be keyboard accessible (Enter/Space activa
 
 ### Accessibility Rules
 
-- Label MUST be associated via `<label for="id">` or `aria-label` — `placeholder` alone is not sufficient
+- Label MUST be associated via `<label for="id">` or `aria-label` - `placeholder` alone is not sufficient
 - Error message MUST be linked via `aria-describedby` and triggered before or alongside visual indicator
 - `aria-invalid="true"` MUST be set on the input when in error state
 - `aria-required="true"` for required fields (supplement with visual `*` + legend)
@@ -133,7 +133,7 @@ Cross-link: `reference/accessibility.md`
 | border colour | 100ms | ease | Focus/error state border change |
 | error message in | 150ms | ease-out | Slide-down + fade; respect prefers-reduced-motion |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion` guard required on label float
+Cross-link: `reference/motion.md` - `prefers-reduced-motion` guard required on label float
 
 ---
 
@@ -146,10 +146,10 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion` guard required on
 - Use `autocomplete` attributes for common fields (name, email, address) *(Polaris, Fluent)*
 
 ### Don't
-- Don't use `placeholder` as the only label — it disappears and fails contrast *(Carbon, Polaris, Atlassian)*
+- Don't use `placeholder` as the only label - it disappears and fails contrast *(Carbon, Polaris, Atlassian)*
 - Don't show error state before the user has had a chance to input (premature validation) *(Polaris)*
-- Don't remove the label on focus to create space — floating labels break screen readers *(Atlassian)*
-- Don't use `type="number"` for things that aren't math operands (phone, ZIP) — use `inputmode` instead *(Mantine, Carbon)*
+- Don't remove the label on focus to create space - floating labels break screen readers *(Atlassian)*
+- Don't use `type="number"` for things that aren't math operands (phone, ZIP) - use `inputmode` instead *(Mantine, Carbon)*
 
 ---
 
@@ -157,7 +157,7 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion` guard required on
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| Placeholder-as-label | `reference/anti-patterns.md` — no dedicated BAN yet; cross-ref accessibility.md |
+| Placeholder-as-label | `reference/anti-patterns.md` - no dedicated BAN yet; cross-ref accessibility.md |
 
 ---
 

package/reference/components/label.md

@@ -1,4 +1,4 @@
-# Label — Benchmark Spec
+# Label - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Carbon, Material 3, Mantine, Polaris, Atlassian, Fluent 2, shadcn/ui
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A label is the visible text that identifies a form control to the user and to assistive technology. It is the most critical accessibility primitive in forms — every input, select, checkbox, radio, and switch MUST have an associated label. Labels are distinct from placeholders (which disappear) and from hints (which supplement but do not replace). *(WAI-ARIA APG, Carbon, Polaris, Atlassian all agree)*
+A label is the visible text that identifies a form control to the user and to assistive technology. It is the most critical accessibility primitive in forms - every input, select, checkbox, radio, and switch MUST have an associated label. Labels are distinct from placeholders (which disappear) and from hints (which supplement but do not replace). *(WAI-ARIA APG, Carbon, Polaris, Atlassian all agree)*
 
 ---
 
@@ -42,26 +42,26 @@ Alternative (legend for group):
 
 | Variant | Description | Systems |
 |---------|-------------|---------|
-| Static label (above) | Fixed position above control — most accessible | Carbon, Polaris, Atlassian, Fluent |
+| Static label (above) | Fixed position above control - most accessible | Carbon, Polaris, Atlassian, Fluent |
 | Floating label | Starts inside control, floats up on focus/fill | Material 3, Mantine, shadcn |
 | Inline label | Label beside control (radio/checkbox) | All |
 | Legend | Group label inside `<fieldset>` | WAI-ARIA APG, all (for groups) |
 | Visually hidden | Accessible but not visible (e.g., search icon button) | WAI-ARIA APG, Carbon |
 
-**Norm** (≥5/18): static label above the control is the most accessible and implementation-simple approach — recommended as the default.
-**Diverge**: floating label — Material 3 and Mantine use it; Carbon, Polaris, Atlassian explicitly recommend static labels for a11y predictability. Floating labels require JavaScript, break if JS fails, and require careful `aria-*` management.
+**Norm** (≥5/18): static label above the control is the most accessible and implementation-simple approach - recommended as the default.
+**Diverge**: floating label - Material 3 and Mantine use it; Carbon, Polaris, Atlassian explicitly recommend static labels for a11y predictability. Floating labels require JavaScript, break if JS fails, and require careful `aria-*` management.
 
 ---
 
 ## States
 
-Labels are not interactive — they have no hover/focus states of their own. However:
+Labels are not interactive - they have no hover/focus states of their own. However:
 
 | Control State | Label Behaviour |
 |---------------|-----------------|
 | error | Label colour may shift to error colour (optional); error text replaces/appends helper |
 | disabled | Label at 38% opacity alongside disabled control |
-| required | Required indicator (`*`) added — never remove from DOM |
+| required | Required indicator (`*`) added - never remove from DOM |
 | focus (on control) | Label may shift colour to primary (Material 3 floating) |
 
 ---
@@ -70,19 +70,19 @@ Labels are not interactive — they have no hover/focus states of their own. How
 
 | Property | Value | Notes |
 |----------|-------|-------|
-| Font size | 14px (static); 12px (floating — small state) | |
+| Font size | 14px (static); 12px (floating - small state) | |
 | Weight | 500 | Slightly heavier than body to distinguish |
 | Gap: label → control | 4–8px | *(Carbon: 4px, Material 3: 8px)* |
 | Required asterisk gap | 2px left of asterisk | |
 | Width | Match control width | Labels should not exceed their control |
 
-Cross-link: `reference/typography.md` — label sizing rules
+Cross-link: `reference/typography.md` - label sizing rules
 
 ---
 
 ## Typography
 
-- Label text: 14px/500 — slightly heavier than body 400; distinguishes from surrounding content
+- Label text: 14px/500 - slightly heavier than body 400; distinguishes from surrounding content
 - Required `*`: same size, colour matches error or primary brand colour
 - Visually-hidden labels: use CSS `.sr-only` pattern (clip + overflow: hidden + absolute), never `display:none` or `visibility:hidden`
 
@@ -108,20 +108,20 @@ Cross-link: `reference/typography.md` — label sizing rules
 
 ### Association Methods (in order of preference)
 
-*Per WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+*Per WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/ - W3C - 2024*
 
-1. **`<label for="id">`** — native HTML; best browser + AT support; clicking label focuses control
-2. **`aria-labelledby="label-id"`** — when label cannot use `for` (complex composites)
-3. **`aria-label="string"`** — when no visible label is possible (icon-only controls); last resort
-4. **`<legend>` inside `<fieldset>`** — for groups of related controls; not replaceable by `aria-label`
+1. **`<label for="id">`** - native HTML; best browser + AT support; clicking label focuses control
+2. **`aria-labelledby="label-id"`** - when label cannot use `for` (complex composites)
+3. **`aria-label="string"`** - when no visible label is possible (icon-only controls); last resort
+4. **`<legend>` inside `<fieldset>`** - for groups of related controls; not replaceable by `aria-label`
 
 ### Accessibility Rules
 
-- NEVER use `placeholder` as the only label — it disappears on input and fails colour contrast *(WAI-ARIA APG, WCAG 1.3.1)*
+- NEVER use `placeholder` as the only label - it disappears on input and fails colour contrast *(WAI-ARIA APG, WCAG 1.3.1)*
 - Required fields: mark with `aria-required="true"` on the control AND `*` visually; provide a form-level note explaining the `*` convention
-- Optional fields: prefer marking optional fields with "(optional)" text over marking every required field with `*` — reduces asterisk clutter in long forms *(Polaris, Carbon)*
-- Group labels: `<legend>` inside `<fieldset>` is the ONLY proper group label technique — `aria-label` on a `<div>` group is inadequate for radio/checkbox groups in most AT
-- Visually hidden labels: use `.sr-only` CSS — never `display:none` (removes from AT tree) or `visibility:hidden`
+- Optional fields: prefer marking optional fields with "(optional)" text over marking every required field with `*` - reduces asterisk clutter in long forms *(Polaris, Carbon)*
+- Group labels: `<legend>` inside `<fieldset>` is the ONLY proper group label technique - `aria-label` on a `<div>` group is inadequate for radio/checkbox groups in most AT
+- Visually hidden labels: use `.sr-only` CSS - never `display:none` (removes from AT tree) or `visibility:hidden`
 
 ---
 
@@ -129,15 +129,15 @@ Cross-link: `reference/typography.md` — label sizing rules
 
 ### Do
 - Place labels above controls, not beside them, for forms wider than 240px *(Carbon, Polaris, Atlassian)*
-- Use `<label for="id">` — the click zone extends to the full label, improving usability *(WAI-ARIA APG, all)*
+- Use `<label for="id">` - the click zone extends to the full label, improving usability *(WAI-ARIA APG, all)*
 - Explain the `*` required indicator once near the top of the form *(Polaris, Carbon)*
-- Use `<legend>` for groups — it is read before each option in the group *(WAI-ARIA APG)*
+- Use `<legend>` for groups - it is read before each option in the group *(WAI-ARIA APG)*
 
 ### Don't
-- Don't use `placeholder` as the only label — it fails at 3 accessibility criteria *(WAI-ARIA APG, WCAG 1.3.1, 1.4.3)*
-- Don't use `display:none` on labels — removes them from the AT accessibility tree *(WAI-ARIA APG)*
-- Don't write labels as questions ("What is your name?") — prefer noun phrases ("Full name") *(Polaris, Carbon)*
-- Don't truncate label text — ellipsis hides required information from all users *(Atlassian, Carbon)*
+- Don't use `placeholder` as the only label - it fails at 3 accessibility criteria *(WAI-ARIA APG, WCAG 1.3.1, 1.4.3)*
+- Don't use `display:none` on labels - removes them from the AT accessibility tree *(WAI-ARIA APG)*
+- Don't write labels as questions ("What is your name?") - prefer noun phrases ("Full name") *(Polaris, Carbon)*
+- Don't truncate label text - ellipsis hides required information from all users *(Atlassian, Carbon)*
 
 ---
 

package/reference/components/link.md

@@ -1,4 +1,4 @@
-# Link — Benchmark Spec
+# Link - Benchmark Spec
 
 **Harvested from**: Carbon, Polaris, Primer (GitHub), Fluent 2, WAI-ARIA APG, Material 3, Mantine, Atlassian
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## 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)*
+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)*
 
 ---
 
@@ -28,11 +28,11 @@ External: [Open dashboard ↗]
 | 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" |
+| 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 |
+| `rel="noopener noreferrer"` | Yes (external) | Security - prevents opener access |
 
 ---
 
@@ -47,8 +47,8 @@ External: [Open dashboard ↗]
 | 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.
+**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.
 
 ---
 
@@ -57,9 +57,9 @@ External: [Open dashboard ↗]
 | 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 | — |
+| 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"` |
 
@@ -67,11 +67,11 @@ External: [Open dashboard ↗]
 
 ## Sizing & Spacing
 
-- Links inherit parent font-size and line-height — do not override
+- 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
+Cross-link: `reference/surfaces.md` - hit-area pattern for standalone links
 
 ---
 
@@ -79,7 +79,7 @@ Cross-link: `reference/surfaces.md` — hit-area pattern for standalone links
 
 - 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
+- Never use ALL CAPS for links - reduces readability and implies different semantics
 - Truncate with ellipsis + `title` attribute only when space is genuinely constrained
 
 ---
@@ -87,11 +87,11 @@ Cross-link: `reference/surfaces.md` — hit-area pattern for standalone links
 ## 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
+> **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*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/link/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -101,11 +101,11 @@ Cross-link: `reference/surfaces.md` — hit-area pattern for standalone links
 
 ### Accessibility Rules
 
-- Link text MUST describe the destination — "click here" and "read more" fail 2.4.6 (descriptive labels)
+- 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)
+- 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
 
 ---
@@ -123,12 +123,12 @@ Cross-link: `reference/surfaces.md` — hit-area pattern for standalone links
 
 ### 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)*
+- 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 `<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)*

package/reference/components/list.md

@@ -1,4 +1,4 @@
-# List (Interactive & Display) — Benchmark Spec
+# List (Interactive & Display) - Benchmark Spec
 
 **Harvested from**: Carbon, Polaris, Material 3, Mantine, WAI-ARIA APG, UUPM (app-interface, MIT)
 **Wave**: 4 · **Category**: Navigation & Data
@@ -7,7 +7,7 @@
 
 ## 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)*
+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)*
 
 ---
 
@@ -58,8 +58,8 @@ Display list:              Interactive listbox:
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Items visible; none selected | `aria-selected="false"` on all options |
-| option-hover | pointer over | 8% overlay | — |
+| 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"` |
@@ -90,7 +90,7 @@ Display list:              Interactive listbox:
 - Empty state heading: heading-sm, center-aligned
 - Empty state body: body-sm, `color: --text-subtle`
 
-Cross-link: `reference/typography.md` — body-sm, heading scale
+Cross-link: `reference/typography.md` - body-sm, heading scale
 
 ---
 
@@ -101,7 +101,7 @@ Cross-link: `reference/typography.md` — body-sm, heading scale
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -117,14 +117,14 @@ Cross-link: `reference/typography.md` — body-sm, heading scale
 
 ### 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
+- 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
+Cross-link: `reference/accessibility.md` - listbox pattern, virtual list accessibility
 
 ---
 
@@ -136,25 +136,25 @@ Cross-link: `reference/accessibility.md` — listbox pattern, virtual list acces
 | 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.
+**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
+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 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)*
+- 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)*
 
 ---
 
@@ -162,7 +162,7 @@ Cross-link: `reference/motion.md` — skeleton shimmer, list animations
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on interactive elements - `reference/anti-patterns.md#ban-04` |
 
 ---
 

package/reference/components/menu.md

@@ -1,4 +1,4 @@
-# Menu (Dropdown / Context Menu) — Benchmark Spec
+# Menu (Dropdown / Context Menu) - Benchmark Spec
 
 **Harvested from**: Radix UI, WAI-ARIA APG, Carbon, Atlassian, Material 3, Polaris
 **Wave**: 4 · **Category**: Navigation
@@ -7,7 +7,7 @@
 
 ## 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)*
+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)*
 
 ---
 
@@ -29,7 +29,7 @@ A menu presents a list of actions or options in a temporary overlay anchored to
 | 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 |
+| 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` |
@@ -56,7 +56,7 @@ A menu presents a list of actions or options in a temporary overlay anchored to
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| closed | — | Trigger visible; overlay hidden | `aria-expanded="false"` on trigger |
+| 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 |
@@ -82,12 +82,12 @@ A menu presents a list of actions or options in a temporary overlay anchored to
 
 ## Typography
 
-- Item label: body-sm (13–14px), weight 400 — not bold; action labels read as text, not controls
+- 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
+Cross-link: `reference/typography.md` - body-sm scale
 
 ---
 
@@ -98,7 +98,7 @@ Cross-link: `reference/typography.md` — body-sm scale
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -115,14 +115,14 @@ Cross-link: `reference/typography.md` — body-sm scale
 
 ### Accessibility Rules
 
-- Menu MUST open on click only — never on hover for primary open (hover may preview sub-menus)
+- 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
+- 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
+Cross-link: `reference/accessibility.md` - focus management, roving tabindex
 
 ---
 
@@ -135,9 +135,9 @@ Cross-link: `reference/accessibility.md` — focus management, roving tabindex
 | 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.
+**BAN**: `transition: all` on menu items - triggers layout thrash on width changes.
 
-Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
+Cross-link: `reference/motion.md` - overlay entry pattern, BAN-04
 
 ---
 
@@ -145,15 +145,15 @@ Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
 
 ### 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)*
+- 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)*
+- 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)*
 
 ---
 
@@ -161,7 +161,7 @@ Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on interactive elements - `reference/anti-patterns.md#ban-04` |
 
 ---
 
@@ -207,6 +207,6 @@ grep -rn 'role="menu"' src/ | grep -v 'aria-labelledby\|aria-label'
 </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`.
+**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).