@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/components/file-upload.md

@@ -1,4 +1,4 @@
-# File Upload — Benchmark Spec
+# File Upload - Benchmark Spec
 
 **Harvested from**: Polaris (DropZone), Carbon (FileUploader), Atlassian Design System, Material 3
 **Wave**: 5 · **Category**: Advanced
@@ -34,7 +34,7 @@ File list (appears after selection):
 | 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 |
+| `<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 |
@@ -62,11 +62,11 @@ File list (appears after selection):
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Dashed border, instructional text | — |
+| 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 | — |
+| 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-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 |
 
@@ -80,9 +80,9 @@ File list (appears after selection):
 | 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)*.
+**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.
+Cross-link: `reference/surfaces.md` - minimum 44×44px touch targets for remove buttons.
 
 ---
 
@@ -94,7 +94,7 @@ Cross-link: `reference/surfaces.md` — minimum 44×44px touch targets for remov
 - File size: caption-sm, secondary color
 - Status text (Done / Error): caption-sm, success or error semantic color
 
-Cross-link: `reference/typography.md` — truncation rules.
+Cross-link: `reference/typography.md` - truncation rules.
 
 ---
 
@@ -105,12 +105,12 @@ Cross-link: `reference/typography.md` — truncation rules.
 
 ### Keyboard Contract
 
-*Derived from native `<input type="file">` behavior and WAI-ARIA APG button pattern — W3C — 2024*
+*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 |
+| 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 |
 
@@ -118,15 +118,15 @@ Drag-and-drop is pointer-only; keyboard users MUST be able to complete the entir
 
 ### 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
+- `<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
+- 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.
+Cross-link: `reference/accessibility.md` - aria-live regions, accessible file input patterns.
 
 ---
 
@@ -140,9 +140,9 @@ Cross-link: `reference/accessibility.md` — aria-live regions, accessible file
 | 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`.
+**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.
+Cross-link: `reference/motion.md` - reduced-motion: skip slide/collapse animations; keep progress bar updates.
 
 ---
 
@@ -155,10 +155,10 @@ Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animat
 - 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)*
+- 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)*
 
 ---
 
@@ -166,8 +166,8 @@ Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animat
 
 | 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` |
+| 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` |
 
 ---
 

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` |
 
 ---