@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/components/slider.md

@@ -1,4 +1,4 @@
-# Slider — Benchmark Spec
+# Slider - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG Slider pattern, Material 3, Radix Slider, Carbon Design System
 **Wave**: 5 · **Category**: Advanced
@@ -8,7 +8,7 @@
 
 ## Purpose
 
-A Slider lets users select a numeric value (or range of values) by dragging a thumb along a track. It is appropriate when the range of values is meaningful as a continuum — volume, price, opacity, temperature — and the exact numeric value matters less than relative position. For precise numeric entry, pair the slider with a text input. For a range, use two thumbs. *(Material 3, Carbon, Radix agree: slider = continuous or discrete value selection with visual track.)*
+A Slider lets users select a numeric value (or range of values) by dragging a thumb along a track. It is appropriate when the range of values is meaningful as a continuum - volume, price, opacity, temperature - and the exact numeric value matters less than relative position. For precise numeric entry, pair the slider with a text input. For a range, use two thumbs. *(Material 3, Carbon, Radix agree: slider = continuous or discrete value selection with visual track.)*
 
 ---
 
@@ -56,10 +56,10 @@ Range:
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Track + thumb at resting position | `aria-valuenow` reflects current value |
-| hover | Pointer over thumb | Thumb expands or shows halo | — |
-| focus | Keyboard focus on thumb | Focus-visible ring on thumb | — |
-| dragging / active | Mousedown / touch on thumb | Value tooltip visible; thumb slightly enlarged | — |
+| default | - | Track + thumb at resting position | `aria-valuenow` reflects current value |
+| hover | Pointer over thumb | Thumb expands or shows halo | - |
+| focus | Keyboard focus on thumb | Focus-visible ring on thumb | - |
+| dragging / active | Mousedown / touch on thumb | Value tooltip visible; thumb slightly enlarged | - |
 | disabled | `disabled` / `aria-disabled` | 38% opacity; cursor: not-allowed | `aria-disabled="true"` |
 
 ---
@@ -74,7 +74,7 @@ Range:
 
 **Norm**: 4px track height (Material 3, Carbon). Thumb visual diameter 20px with ::before/::after expanding the touch target to ≥44px without inflating layout.
 
-Cross-link: `reference/surfaces.md` — 44×44px touch-target minimum; use padding trick, not enlarged visual.
+Cross-link: `reference/surfaces.md` - 44×44px touch-target minimum; use padding trick, not enlarged visual.
 
 ---
 
@@ -84,7 +84,7 @@ Cross-link: `reference/surfaces.md` — 44×44px touch-target minimum; use paddi
 - Tick labels: caption-xs, secondary color, centered below tick mark
 - Min/Max endpoint labels: caption-sm, secondary color, flush with track ends
 
-Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digits don't shift width during drag.
+Cross-link: `reference/typography.md` - tabular-nums on value tooltip so digits don't shift width during drag.
 
 ---
 
@@ -95,7 +95,7 @@ Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digit
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/slider/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/slider/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -112,12 +112,12 @@ Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digit
 
 - Every slider thumb MUST have `aria-valuenow`; update it continuously during drag
 - `aria-valuetext` MUST be provided when raw number is not human-readable (e.g., "Low", "Medium", "High" for a quality setting, or "$45" for a price)
-- Range slider: label each thumb distinctly (e.g., `aria-label="Minimum price"` and `aria-label="Maximum price"`) — identical labels confuse screen readers
+- Range slider: label each thumb distinctly (e.g., `aria-label="Minimum price"` and `aria-label="Maximum price"`) - identical labels confuse screen readers
 - Thumb touch target MUST be ≥44×44px; use `::before`/`::after` pseudo-element padding if visual thumb is smaller
-- Do not use `<input type="range">` hidden behind a custom div without ARIA — the native element is preferable when no custom styling is required
+- Do not use `<input type="range">` hidden behind a custom div without ARIA - the native element is preferable when no custom styling is required
 - Disabled sliders: use `aria-disabled="true"`; keep thumb in tab order so AT can announce the current value
 
-Cross-link: `reference/accessibility.md` — slider role, aria-valuetext guidance.
+Cross-link: `reference/accessibility.md` - slider role, aria-valuetext guidance.
 
 ---
 
@@ -125,15 +125,15 @@ Cross-link: `reference/accessibility.md` — slider role, aria-valuetext guidanc
 
 | Transition | Duration | Easing | Notes |
 |------------|----------|--------|-------|
-| Thumb drag | 0ms | — | No easing on drag — follows pointer exactly |
+| Thumb drag | 0ms | - | No easing on drag - follows pointer exactly |
 | Keyboard step | 80ms | ease-out | Smooth snap to new position |
 | Value tooltip appear | 100ms | ease-out | Fade in on focus/drag |
 | Value tooltip dismiss | 150ms | ease-in | Fade out on blur |
 | Tick mark appear | 120ms | ease-out | When switching to discrete mode |
 
-**BAN**: Do not add momentum or inertia easing to thumb drag — feels broken and breaks accessibility (thumb does not match pointer).
+**BAN**: Do not add momentum or inertia easing to thumb drag - feels broken and breaks accessibility (thumb does not match pointer).
 
-Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step animation; thumb jumps instantly.
+Cross-link: `reference/motion.md` - reduced-motion: remove keyboard-step animation; thumb jumps instantly.
 
 ---
 
@@ -146,9 +146,9 @@ Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step anima
 - Show tick marks only for discrete sliders with ≤10 steps *(Material 3, Carbon)*
 
 ### Don't
-- Don't build a slider from `<div>` with mouse events only — no keyboard, no ARIA *(diverges from all 4 systems)*
-- Don't omit `aria-valuenow` updates during drag — AT users hear a stale value *(WAI-ARIA APG)*
-- Don't let the visual thumb area be smaller than 12px with no hit-area expansion — fails WCAG 2.5.8 *(Material 3)*
+- Don't build a slider from `<div>` with mouse events only - no keyboard, no ARIA *(diverges from all 4 systems)*
+- Don't omit `aria-valuenow` updates during drag - AT users hear a stale value *(WAI-ARIA APG)*
+- Don't let the visual thumb area be smaller than 12px with no hit-area expansion - fails WCAG 2.5.8 *(Material 3)*
 - Don't use identical `aria-label` for both range thumbs *(WAI-ARIA APG)*
 
 ---
@@ -157,8 +157,8 @@ Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step anima
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-09 | Custom interactive widget with mouse events only, no keyboard — `reference/anti-patterns.md#ban-09` |
-| BAN-11 | Touch target below 44px without padding expansion — `reference/anti-patterns.md#ban-11` |
+| BAN-09 | Custom interactive widget with mouse events only, no keyboard - `reference/anti-patterns.md#ban-09` |
+| BAN-11 | Touch target below 44px without padding expansion - `reference/anti-patterns.md#ban-11` |
 
 ---
 

package/reference/components/stepper.md

@@ -1,4 +1,4 @@
-# Stepper / Wizard — Benchmark Spec
+# Stepper / Wizard - Benchmark Spec
 
 **Harvested from**: Carbon (ProgressIndicator + StepNavigation), Material 3 Stepper, Atlassian Design System, Mantine Stepper
 **Wave**: 5 · **Category**: Advanced
@@ -8,7 +8,7 @@
 
 ## Purpose
 
-A Stepper (or Wizard) guides users through a sequential multi-step flow — onboarding, checkout, multi-page forms, settings setup. It communicates how many steps exist, which step is current, which are complete, and which are upcoming. Unlike Tabs (free navigation), a linear Stepper enforces order: the user must complete the current step before advancing. *(Carbon, Material 3, Atlassian, Mantine agree: step indicator list + content area + explicit Next/Back buttons is the canonical wizard pattern.)*
+A Stepper (or Wizard) guides users through a sequential multi-step flow - onboarding, checkout, multi-page forms, settings setup. It communicates how many steps exist, which step is current, which are complete, and which are upcoming. Unlike Tabs (free navigation), a linear Stepper enforces order: the user must complete the current step before advancing. *(Carbon, Material 3, Atlassian, Mantine agree: step indicator list + content area + explicit Next/Back buttons is the canonical wizard pattern.)*
 
 ---
 
@@ -59,7 +59,7 @@ Actions:
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| upcoming | Step not yet reached | Muted circle/number, secondary text color | — |
+| upcoming | Step not yet reached | Muted circle/number, secondary text color | - |
 | current | Active step | Brand-color filled circle; bold label | `aria-current="step"` |
 | completed | Step passed + valid | Check icon; full-opacity; clickable if non-linear | `aria-label="Step N: [name] - completed"` |
 | error | Step has validation errors | Error color circle; error icon | `aria-label="Step N: [name] - has errors"` |
@@ -77,7 +77,7 @@ Actions:
 
 **Norm**: Step circles 32px default *(Carbon, Mantine)*. Horizontal spacing between steps should scale with the available width so the indicator spans the container. Connector line is centered between circles.
 
-Cross-link: `reference/surfaces.md` — minimum 44×44px touch target for clickable step indicators.
+Cross-link: `reference/surfaces.md` - minimum 44×44px touch target for clickable step indicators.
 
 ---
 
@@ -86,9 +86,9 @@ Cross-link: `reference/surfaces.md` — minimum 44×44px touch target for clicka
 - Step label: body-sm (completed/upcoming) → body-sm weight 600 (current)
 - Step number/icon inside circle: caption-sm, center-aligned
 - Step description (optional sub-label): caption-sm, secondary color
-- Action buttons: body-md, weight 500 — same as standard button spec
+- Action buttons: body-md, weight 500 - same as standard button spec
 
-Cross-link: `reference/typography.md` — label weight change for current state.
+Cross-link: `reference/typography.md` - label weight change for current state.
 
 ---
 
@@ -99,27 +99,27 @@ Cross-link: `reference/typography.md` — label weight change for current state.
 
 ### Keyboard Contract
 
-*Derived from WAI-ARIA APG list and button patterns — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+*Derived from WAI-ARIA APG list and button patterns - https://www.w3.org/WAI/ARIA/apg/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
 | Tab | Move focus through interactive elements: clickable completed steps (non-linear), Back button, Next/Submit button |
 | Enter / Space | Activate focused Back, Next, Submit button; activate clickable completed step (non-linear) |
-| (No arrow-key navigation) | Steps are NOT tabs — do not implement roving tabindex / arrow-key navigation between steps |
+| (No arrow-key navigation) | Steps are NOT tabs - do not implement roving tabindex / arrow-key navigation between steps |
 
 Steps are NOT `role="tab"` and do not use the tab keyboard pattern. Upcoming steps are not focusable in linear mode. Only completed steps are interactive (and focusable) in non-linear mode.
 
 ### Accessibility Rules
 
-- Step indicators MUST use `role="list"` + `role="listitem"` — not `role="tablist"` + `role="tab"` (tabs allow free navigation; wizard steps do not)
-- Current step MUST have `aria-current="step"` — this is the correct token (not `aria-selected` or `aria-checked`)
+- Step indicators MUST use `role="list"` + `role="listitem"` - not `role="tablist"` + `role="tab"` (tabs allow free navigation; wizard steps do not)
+- Current step MUST have `aria-current="step"` - this is the correct token (not `aria-selected` or `aria-checked`)
 - Completed steps in non-linear mode MUST be `<button>` elements (or have `role="button"` + `tabindex="0"`) with `aria-label` including the step name and "completed" state
-- Step connector lines MUST be `aria-hidden="true"` — they are purely decorative
+- Step connector lines MUST be `aria-hidden="true"` - they are purely decorative
 - Validate current step before allowing Next; display inline error messages with `aria-describedby` associations
-- "Next", "Back", and "Submit" MUST be explicit text labels — do not use icon-only navigation buttons
+- "Next", "Back", and "Submit" MUST be explicit text labels - do not use icon-only navigation buttons
 - Announce step transitions via `aria-live="polite"` on the content region header (e.g., "Step 2 of 4: Profile")
 
-Cross-link: `reference/accessibility.md` — aria-current values, list semantics.
+Cross-link: `reference/accessibility.md` - aria-current values, list semantics.
 
 ---
 
@@ -132,25 +132,25 @@ Cross-link: `reference/accessibility.md` — aria-current values, list semantics
 | Error state appear | 150ms | ease-out | Circle color change + icon fade in |
 | Back navigation | 200ms | ease-in-out | Slide right (reverse direction) |
 
-**BAN**: Do not use the same slide direction for both forward and backward step navigation — direction must be consistent with the mental model (forward = left, backward = right).
+**BAN**: Do not use the same slide direction for both forward and backward step navigation - direction must be consistent with the mental model (forward = left, backward = right).
 
-Cross-link: `reference/motion.md` — reduced-motion: skip slide; cross-fade content area only.
+Cross-link: `reference/motion.md` - reduced-motion: skip slide; cross-fade content area only.
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Use `role="list"` for the step indicator — steps are a list, not a tab set *(WAI-ARIA APG, Carbon)*
+- Use `role="list"` for the step indicator - steps are a list, not a tab set *(WAI-ARIA APG, Carbon)*
 - Set `aria-current="step"` on the active step *(WAI-ARIA spec §aria-current)*
 - Validate the current step before advancing and show inline errors *(Carbon, Atlassian)*
-- Label Back/Next/Submit buttons explicitly — not icons or chevrons *(Material 3, Carbon, Mantine)*
+- Label Back/Next/Submit buttons explicitly - not icons or chevrons *(Material 3, Carbon, Mantine)*
 
 ### Don't
-- Don't use `role="tablist"` for steps — tabs allow free navigation; wizard steps are ordered and gated *(diverges from all 4 systems)*
-- Don't allow jumping to future unvisited steps in linear mode — breaks the sequential contract *(Carbon, Atlassian)*
-- Don't use `aria-selected` on steps — `aria-current="step"` is the correct token *(WAI-ARIA spec)*
-- Don't omit the Back button — users must be able to correct previous steps *(Material 3, Atlassian)*
+- Don't use `role="tablist"` for steps - tabs allow free navigation; wizard steps are ordered and gated *(diverges from all 4 systems)*
+- Don't allow jumping to future unvisited steps in linear mode - breaks the sequential contract *(Carbon, Atlassian)*
+- Don't use `aria-selected` on steps - `aria-current="step"` is the correct token *(WAI-ARIA spec)*
+- Don't omit the Back button - users must be able to correct previous steps *(Material 3, Atlassian)*
 
 ---
 
@@ -158,8 +158,8 @@ Cross-link: `reference/motion.md` — reduced-motion: skip slide; cross-fade con
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-14 | Stepper using role="tablist" — semantically incorrect navigation model — `reference/anti-patterns.md#ban-14` |
-| BAN-07 | Missing aria-current on active step — `reference/anti-patterns.md#ban-07` |
+| BAN-14 | Stepper using role="tablist" - semantically incorrect navigation model - `reference/anti-patterns.md#ban-14` |
+| BAN-07 | Missing aria-current on active step - `reference/anti-patterns.md#ban-07` |
 
 ---
 
@@ -215,6 +215,6 @@ grep -rn 'wizard.*next\|stepper.*next\|wizard.*back\|stepper.*back' src/ | grep
 </ul>
 ```
 
-**Why it fails**: `role="tablist"` implies that all tabs are independently activatable and content switches freely — this is correct for Tabs but wrong for a wizard where steps are gated. AT users expect arrow-key navigation between tabs; in a wizard this would allow jumping to uncompleted future steps. `aria-selected` is the tab token; the correct token for a wizard is `aria-current="step"`.
+**Why it fails**: `role="tablist"` implies that all tabs are independently activatable and content switches freely - this is correct for Tabs but wrong for a wizard where steps are gated. AT users expect arrow-key navigation between tabs; in a wizard this would allow jumping to uncompleted future steps. `aria-selected` is the tab token; the correct token for a wizard is `aria-current="step"`.
 **Grep detection**: `grep -rn 'role="tablist"' src/ | grep -i 'step\|wizard'`
 **Fix**: Replace `<ul role="tablist">` with `<ol role="list">` (ordered list signals sequence), each `<li>` with `role="listitem"`, remove `aria-selected`, and add `aria-current="step"` to the current step. Make only completed steps keyboard-focusable (as `<button>`) in non-linear mode; upcoming steps are not interactive.

package/reference/components/switch.md

@@ -1,4 +1,4 @@
-# Switch — Benchmark Spec
+# Switch - Benchmark Spec
 
 **Harvested from**: Apple HIG, Material 3, Radix UI, Spectrum (Adobe), Polaris, Fluent 2, Mantine, shadcn/ui
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A switch (toggle) represents an immediate binary action — changes take effect without a confirm step, like enabling dark mode or activating a feature. It differs from a checkbox in this immediacy: a checkbox is a form option submitted later; a switch acts now. Do not use a switch inside a form that requires a submit button to apply changes. *(Apple HIG, Material 3, Polaris all distinguish switch from checkbox this way)*
+A switch (toggle) represents an immediate binary action - changes take effect without a confirm step, like enabling dark mode or activating a feature. It differs from a checkbox in this immediacy: a checkbox is a form option submitted later; a switch acts now. Do not use a switch inside a form that requires a submit button to apply changes. *(Apple HIG, Material 3, Polaris all distinguish switch from checkbox this way)*
 
 ---
 
@@ -41,7 +41,7 @@ Label                     ← visible text describing the setting
 | Large | 32px height | Material 3, Apple HIG |
 
 **Norm** (≥5/18): label appears to the left of the switch (LTR); toggle is right-aligned.
-**Diverge**: thumb icon vs. bare thumb — Material 3 adds check icon on ON, x on OFF; most others use bare thumb. Bare is simpler and more portable across themes.
+**Diverge**: thumb icon vs. bare thumb - Material 3 adds check icon on ON, x on OFF; most others use bare thumb. Bare is simpler and more portable across themes.
 
 ---
 
@@ -51,8 +51,8 @@ Label                     ← visible text describing the setting
 |-------|--------|------|
 | OFF (unchecked) | Thumb left, track muted | `aria-checked="false"` |
 | ON (checked) | Thumb right, track colored | `aria-checked="true"` |
-| hover | Thumb scale up slightly (1.1×) | — |
-| focus | 2px focus ring around track | — |
+| hover | Thumb scale up slightly (1.1×) | - |
+| focus | 2px focus ring around track | - |
 | disabled OFF | 38% opacity, thumb left | `aria-disabled="true"` |
 | disabled ON | 38% opacity, thumb right | `aria-disabled="true"` |
 
@@ -66,17 +66,17 @@ Label                     ← visible text describing the setting
 | md (default) | 44×24px | 20px | 44×44px |
 | lg | 52×28px | 24px | 48×48px |
 
-Track radius: `border-radius: 9999px` (pill shape — all 8 systems agree).
+Track radius: `border-radius: 9999px` (pill shape - all 8 systems agree).
 Thumb travel: track width − thumb diameter − (2 × inset padding ≈ 2px).
 
-Cross-link: `reference/surfaces.md` — concentric radius rule does NOT apply here (pill shape is intentional, not nested radius)
+Cross-link: `reference/surfaces.md` - concentric radius rule does NOT apply here (pill shape is intentional, not nested radius)
 
 ---
 
 ## Typography
 
 - Label: 14px/400 body weight; not distinguished from surrounding text
-- State text (optional): 10–11px/600 uppercase inside track — ensure ≥4.5:1 contrast against track colour
+- State text (optional): 10–11px/600 uppercase inside track - ensure ≥4.5:1 contrast against track colour
 
 ---
 
@@ -87,7 +87,7 @@ Cross-link: `reference/surfaces.md` — concentric radius rule does NOT apply he
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/switch/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/switch/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -96,9 +96,9 @@ Cross-link: `reference/surfaces.md` — concentric radius rule does NOT apply he
 
 ### Accessibility Rules
 
-- `role="switch"` with `aria-checked="true/false"` — not `role="checkbox"` (different semantic contract; switch implies immediate action)
+- `role="switch"` with `aria-checked="true/false"` - not `role="checkbox"` (different semantic contract; switch implies immediate action)
 - Label MUST be associated: `<label>` with `for` on the switch element, or `aria-label`/`aria-labelledby`
-- State text ("ON"/"OFF") inside the track is a visual enhancement only — it MUST NOT be the sole accessible name
+- State text ("ON"/"OFF") inside the track is a visual enhancement only - it MUST NOT be the sole accessible name
 - Disabled: use `aria-disabled="true"` (not native `disabled` attr) if keyboard focus should remain (e.g. to explain why it's disabled via tooltip)
 - Announce state change via `aria-live="polite"` if switching triggers a significant UI change distant from the control
 
@@ -113,7 +113,7 @@ Cross-link: `reference/surfaces.md` — concentric radius rule does NOT apply he
 | Thumb scale on hover | 80ms | ease | 1→1.1× scale |
 | Press scale | 80ms | ease | 1→0.96× (canonical press scale) |
 
-Cross-link: `reference/motion.md` — spring bounce=0 canonical values, canonical scale-on-press 0.96
+Cross-link: `reference/motion.md` - spring bounce=0 canonical values, canonical scale-on-press 0.96
 
 ---
 
@@ -121,15 +121,15 @@ Cross-link: `reference/motion.md` — spring bounce=0 canonical values, canonica
 
 ### Do
 - Use `role="switch"` not `role="checkbox"` for toggle-with-immediate-effect *(WAI-ARIA APG, Radix)*
-- Animate the thumb sliding — static snap removes the "toggle" affordance *(Apple HIG, Material 3)*
+- Animate the thumb sliding - static snap removes the "toggle" affordance *(Apple HIG, Material 3)*
 - Place label to the left of the switch in LTR layouts *(Apple HIG, Material 3, Polaris)*
-- Apply changes immediately on toggle — no submit button required *(Apple HIG, Polaris)*
+- Apply changes immediately on toggle - no submit button required *(Apple HIG, Polaris)*
 
 ### Don't
-- Don't use a switch inside a form where the user must click "Save" — use a checkbox *(Apple HIG, Polaris)*
-- Don't rely on track colour alone to communicate state (colour blind users) — add icon or label *(Spectrum, Material 3)*
-- Don't use the same `aria-label` for ON and OFF states — screen readers read the current state via `aria-checked` *(WAI-ARIA APG)*
-- Don't animate thumb with `transition: all` — it catches border-radius changes and causes thumb deformation *(BAN-04)*
+- Don't use a switch inside a form where the user must click "Save" - use a checkbox *(Apple HIG, Polaris)*
+- Don't rely on track colour alone to communicate state (colour blind users) - add icon or label *(Spectrum, Material 3)*
+- Don't use the same `aria-label` for ON and OFF states - screen readers read the current state via `aria-checked` *(WAI-ARIA APG)*
+- Don't animate thumb with `transition: all` - it catches border-radius changes and causes thumb deformation *(BAN-04)*
 
 ---
 
@@ -137,7 +137,7 @@ Cross-link: `reference/motion.md` — spring bounce=0 canonical values, canonica
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` - `reference/anti-patterns.md#ban-04` |
 | Checkbox semantics for immediate-action toggle | `reference/anti-patterns.md` |
 
 ---

package/reference/components/table.md

@@ -1,4 +1,4 @@
-# Table (Data Table / Data Grid) — Benchmark Spec
+# Table (Data Table / Data Grid) - Benchmark Spec
 
 **Harvested from**: Carbon DataTable, Polaris DataTable, Atlassian DynamicTable, Ant Design Table, UUPM (app-interface, MIT)
 **Wave**: 4 · **Category**: Navigation & Data
@@ -63,15 +63,15 @@ A data table presents structured, comparable information in rows and columns. It
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Alternating row colors or border separators | — |
-| row-hover | pointer over row | Subtle row highlight (4% overlay) | — |
+| default | - | Alternating row colors or border separators | - |
+| row-hover | pointer over row | Subtle row highlight (4% overlay) | - |
 | row-selected | checkbox checked | Row highlight; checkbox filled | `aria-selected="true"` on `<tr>` |
 | header-sort-asc | sort click | Arrow indicator up; column highlight | `aria-sort="ascending"` on `<th>` |
 | header-sort-desc | sort click again | Arrow indicator down | `aria-sort="descending"` on `<th>` |
 | header-sort-none | default or reset | No indicator | `aria-sort="none"` on sortable `<th>` |
-| header-focus | keyboard focus on sortable `<th>` | 2px focus-visible ring | — |
+| header-focus | keyboard focus on sortable `<th>` | 2px focus-visible ring | - |
 | loading | data fetch | Skeleton rows or spinner overlay | `aria-busy="true"` on table or container |
-| empty | no results | Empty state illustration + message | — |
+| empty | no results | Empty state illustration + message | - |
 
 ---
 
@@ -92,10 +92,10 @@ Virtualise rows when `rowCount > 200`; use TanStack Virtual or react-virtual.
 
 - Column header: body-sm or label-sm (12–13px), weight 600, `color: --text-secondary`
 - Cell text: body-sm (13–14px), weight 400
-- Numeric cells: `font-variant-numeric: tabular-nums` — column values align on decimal point
+- Numeric cells: `font-variant-numeric: tabular-nums` - column values align on decimal point
 - Truncation: `text-overflow: ellipsis` on cells with `max-width`; tooltip reveals full value on hover
 
-Cross-link: `reference/typography.md` — tabular-nums, body-sm
+Cross-link: `reference/typography.md` - tabular-nums, body-sm
 
 ---
 
@@ -106,7 +106,7 @@ Cross-link: `reference/typography.md` — tabular-nums, body-sm
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/grid/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/grid/ - W3C - 2024*
 
 | Key | Action (role="grid") |
 |-----|---------------------|
@@ -123,14 +123,14 @@ Cross-link: `reference/typography.md` — tabular-nums, body-sm
 
 ### Accessibility Rules
 
-- ALL `<th>` column headers MUST have `scope="col"` — missing scope breaks AT table navigation
+- ALL `<th>` column headers MUST have `scope="col"` - missing scope breaks AT table navigation
 - Sortable `<th>` elements MUST have `aria-sort` with value `ascending`, `descending`, or `none`
-- Selected rows MUST use `aria-selected="true"` on `<tr>` — CSS class alone is invisible to AT
+- Selected rows MUST use `aria-selected="true"` on `<tr>` - CSS class alone is invisible to AT
 - `<table>` MUST have a `<caption>` or `aria-label` to announce the table's purpose
 - The responsive scroll wrapper MUST have `tabindex="0"` so keyboard users can scroll horizontally
 - `role="grid"` enables cell-level arrow-key navigation; use only when cells contain interactive controls
 
-Cross-link: `reference/accessibility.md` — table semantics, grid pattern
+Cross-link: `reference/accessibility.md` - table semantics, grid pattern
 
 ---
 
@@ -144,25 +144,25 @@ Cross-link: `reference/accessibility.md` — table semantics, grid pattern
 | Expandable row open | 150ms | ease-out | Height expand |
 | Skeleton shimmer | 1500ms | linear loop | Loading placeholder |
 
-**BAN**: Do not animate `width` on table columns — causes full table relayout on every frame.
+**BAN**: Do not animate `width` on table columns - causes full table relayout on every frame.
 
-Cross-link: `reference/motion.md` — layout-affecting transitions, skeleton shimmer
+Cross-link: `reference/motion.md` - layout-affecting transitions, skeleton shimmer
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Add `scope="col"` to every `<th>` — screen readers use this to announce column context *(WAI-ARIA, Carbon)*
-- Use `aria-sort` on sortable headers — not just a visual arrow icon *(Carbon, Polaris, Atlassian)*
+- Add `scope="col"` to every `<th>` - screen readers use this to announce column context *(WAI-ARIA, Carbon)*
+- Use `aria-sort` on sortable headers - not just a visual arrow icon *(Carbon, Polaris, Atlassian)*
 - Use `tabindex="0"` on horizontal scroll wrapper for keyboard accessibility *(WCAG 2.1.1)*
-- Virtualise rows at > 200 items — prevents browser paint lag *(Carbon, Ant)*
+- Virtualise rows at > 200 items - prevents browser paint lag *(Carbon, Ant)*
 
 ### Don't
-- Don't build a "table" with `<div>` elements and no ARIA grid roles — invisible to AT *(WCAG 1.3.1)*
-- Don't use `aria-sort` on non-sortable columns — misleads users into clicking non-interactive headers *(WAI-ARIA)*
-- Don't place `overflow-x: auto` on `<table>` directly — wrap in a `<div>` with `tabindex="0"` *(WCAG 2.1.1)*
-- Don't use `display: contents` on `<thead>/<tbody>/<tr>` — breaks AT table parsing *(WCAG 1.3.1)*
+- Don't build a "table" with `<div>` elements and no ARIA grid roles - invisible to AT *(WCAG 1.3.1)*
+- Don't use `aria-sort` on non-sortable columns - misleads users into clicking non-interactive headers *(WAI-ARIA)*
+- Don't place `overflow-x: auto` on `<table>` directly - wrap in a `<div>` with `tabindex="0"` *(WCAG 2.1.1)*
+- Don't use `display: contents` on `<thead>/<tbody>/<tr>` - breaks AT table parsing *(WCAG 1.3.1)*
 
 ---
 
@@ -170,7 +170,7 @@ Cross-link: `reference/motion.md` — layout-affecting transitions, skeleton shi
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on table cells — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on table cells - `reference/anti-patterns.md#ban-04` |
 
 ---
 

package/reference/components/tabs.md

@@ -1,4 +1,4 @@
-# Tabs — Benchmark Spec
+# Tabs - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Radix UI, Carbon, Mantine, Material 3, Chakra UI, Atlassian, Fluent 2
 **Wave**: 2 · **Category**: Containers
@@ -51,7 +51,7 @@ Vertical tabs (sidebar):
 | Icon + label | Icon above or beside label | Material 3, Carbon |
 
 **Norm** (≥6/18): arrow keys navigate between tabs; Tab key moves to active panel content.
-**Diverge**: automatic vs. manual activation — automatic (arrow key selects immediately) vs. manual (arrow key moves focus, Enter selects). WAI-ARIA APG recommends manual for complex panels; Radix defaults to automatic.
+**Diverge**: automatic vs. manual activation - automatic (arrow key selects immediately) vs. manual (arrow key moves focus, Enter selects). WAI-ARIA APG recommends manual for complex panels; Radix defaults to automatic.
 
 ---
 
@@ -96,7 +96,7 @@ Vertical tabs (sidebar):
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -116,12 +116,12 @@ Vertical tabs (sidebar):
 
 ### Accessibility Rules
 
-- Only the selected tab has `tabindex="0"` — all other tabs have `tabindex="-1"` (roving tabindex pattern)
+- Only the selected tab has `tabindex="0"` - all other tabs have `tabindex="-1"` (roving tabindex pattern)
 - `tablist` MUST have a label: `aria-label="[Section name]"` or `aria-labelledby`
 - Inactive panels MUST be hidden with `hidden` attribute (not just CSS) so AT skips them
 - Panel SHOULD have `tabindex="0"` to allow focusing the panel after Tab from the tablist
 - Icon-only tabs MUST have `aria-label` on the tab element
-- Linked tabs (tabs that change URL): use `role="link"` semantics or native `<a>` within tab — but note this changes the keyboard contract
+- Linked tabs (tabs that change URL): use `role="link"` semantics or native `<a>` within tab - but note this changes the keyboard contract
 
 ---
 
@@ -133,23 +133,23 @@ Vertical tabs (sidebar):
 | Panel fade | 150ms | ease | Crossfade between panels |
 | Scroll reveal | 200ms | ease | When scrolling to new active tab in overflow |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: disable indicator slide + panel fade
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: disable indicator slide + panel fade
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Use roving tabindex — `tabindex="0"` on selected, `tabindex="-1"` on all others *(WAI-ARIA APG)*
+- Use roving tabindex - `tabindex="0"` on selected, `tabindex="-1"` on all others *(WAI-ARIA APG)*
 - Navigate with arrow keys between tabs, not Tab key *(WAI-ARIA APG)*
 - Label the tablist with `aria-label` or `aria-labelledby` *(WAI-ARIA APG)*
 - Hide inactive panels with `hidden` attribute so AT skips them *(WAI-ARIA APG)*
 
 ### Don't
-- Don't use Tab key to navigate between tabs — Tab moves in/out of the tablist *(WAI-ARIA APG)*
-- Don't show all tab panel content simultaneously — defeats the purpose of tabs *(all systems)*
-- Don't use more than 7 tabs in a horizontal tab strip — prefer a select or dropdown for overflow *(Carbon, Atlassian)*
-- Don't use tabs for steps that must be completed in order — use a stepper *(Material 3, Atlassian)*
+- Don't use Tab key to navigate between tabs - Tab moves in/out of the tablist *(WAI-ARIA APG)*
+- Don't show all tab panel content simultaneously - defeats the purpose of tabs *(all systems)*
+- Don't use more than 7 tabs in a horizontal tab strip - prefer a select or dropdown for overflow *(Carbon, Atlassian)*
+- Don't use tabs for steps that must be completed in order - use a stepper *(Material 3, Atlassian)*
 
 ---
 

package/reference/components/toast.md

@@ -1,4 +1,4 @@
-# Toast / Snackbar — Benchmark Spec
+# Toast / Snackbar - Benchmark Spec
 
 **Harvested from**: Radix UI Toast, Material 3 (Snackbar), Polaris (Toast), Carbon (Notification Toast)
 **Wave**: 3 · **Category**: Feedback
@@ -52,7 +52,7 @@ A toast (snackbar) is a transient, non-blocking notification that appears briefl
 |-------|---------|--------|------|
 | entering | mount | Slide-in from bottom-right + fade-in, 200ms ease-out | Live region populated |
 | visible | auto | Full opacity, static position | `role="status"` or `role="alert"` |
-| hover / focus | pointer/keyboard | Auto-dismiss timer paused | — |
+| hover / focus | pointer/keyboard | Auto-dismiss timer paused | - |
 | exiting | dismiss / timeout | Slide-out + fade-out, 150ms ease-in | Removed from DOM |
 | queued | >3 toasts active | Off-screen; waits for visible slot | Not yet in DOM |
 
@@ -75,11 +75,11 @@ A toast (snackbar) is a transient, non-blocking notification that appears briefl
 
 ## Typography
 
-- Message: body-sm (14px/400) — same as body to ensure readability at a glance
-- Action label: label-sm (13px/500) — slightly heavier to signal interactivity
-- No wrapping beyond 2 lines — if message exceeds 2 lines, use Alert instead
+- Message: body-sm (14px/400) - same as body to ensure readability at a glance
+- Action label: label-sm (13px/500) - slightly heavier to signal interactivity
+- No wrapping beyond 2 lines - if message exceeds 2 lines, use Alert instead
 
-Cross-link: `reference/typography.md` — body-sm, label-sm definitions
+Cross-link: `reference/typography.md` - body-sm, label-sm definitions
 
 ---
 
@@ -90,7 +90,7 @@ Cross-link: `reference/typography.md` — body-sm, label-sm definitions
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/alert/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/alert/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -102,14 +102,14 @@ Toast container itself is not focusable. Only interactive children (action, dism
 
 ### Accessibility Rules
 
-- `role="alert"` on warning/error toasts causes immediate announcement by screen readers — do NOT use for info/success (too noisy)
-- `role="status"` on info/success uses a polite live region — announced at next opportunity
-- The live region container MUST be present in the DOM before the toast text is injected — injecting `role="alert"` dynamically may not announce *(WCAG 4.1.3)*
-- Dismiss button MUST have `aria-label="Dismiss notification"` or similar — the ✕ icon alone is not an accessible name
-- Auto-dismiss timer MUST pause when the toast is hovered or focused *(WCAG 2.2.1 — Timing Adjustable)*
+- `role="alert"` on warning/error toasts causes immediate announcement by screen readers - do NOT use for info/success (too noisy)
+- `role="status"` on info/success uses a polite live region - announced at next opportunity
+- The live region container MUST be present in the DOM before the toast text is injected - injecting `role="alert"` dynamically may not announce *(WCAG 4.1.3)*
+- Dismiss button MUST have `aria-label="Dismiss notification"` or similar - the ✕ icon alone is not an accessible name
+- Auto-dismiss timer MUST pause when the toast is hovered or focused *(WCAG 2.2.1 - Timing Adjustable)*
 - Error toasts MUST either be persistent or have an explicit dismiss mechanism *(Polaris, Carbon)*
 
-Cross-link: `reference/accessibility.md` — live-regions section
+Cross-link: `reference/accessibility.md` - live-regions section
 
 ---
 
@@ -121,9 +121,9 @@ Cross-link: `reference/accessibility.md` — live-regions section
 | Exit (slide-out + fade) | 150ms | ease-in | Reverse direction on dismiss |
 | Stack reflow | 150ms | ease-out | Other toasts shift position when one exits |
 
-**BAN**: Bouncing or spring physics on enter — toast is informational, not celebratory. Avoid `transition: all` (catches layout shifts during stack reflow).
+**BAN**: Bouncing or spring physics on enter - toast is informational, not celebratory. Avoid `transition: all` (catches layout shifts during stack reflow).
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip slide, use fade-only at 100ms
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip slide, use fade-only at 100ms
 
 ---
 
@@ -136,10 +136,10 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip slide, use
 - Keep message text ≤80 characters; use action button for follow-up *(Material 3, Polaris)*
 
 ### Don't
-- Don't use toast for errors that require user action — use a modal or alert *(Material 3, Carbon)*
-- Don't stack more than 3 toasts — queue the rest *(Radix, Polaris)*
-- Don't put more than one action in a toast — use a modal for complex decisions *(Material 3)*
-- Don't rely on toast alone for critical status — supplement with in-page feedback *(Carbon)*
+- Don't use toast for errors that require user action - use a modal or alert *(Material 3, Carbon)*
+- Don't stack more than 3 toasts - queue the rest *(Radix, Polaris)*
+- Don't put more than one action in a toast - use a modal for complex decisions *(Material 3)*
+- Don't rely on toast alone for critical status - supplement with in-page feedback *(Carbon)*
 
 ---