@hegemonart/get-design-done 1.41.5 → 1.43.0

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

package/reference/components/tooltip.md

@@ -1,4 +1,4 @@
-# Tooltip — Benchmark Spec
+# Tooltip - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Radix UI, Material 3, Carbon, Mantine, Fluent 2, Atlassian, Apple HIG
 **Wave**: 2 · **Category**: Containers
@@ -43,7 +43,7 @@ A tooltip is a small, non-interactive label that appears on hover or keyboard fo
 | Light | Light background | Mantine (inverted) |
 
 **Norm** (≥7/18): 300ms show delay, 0ms hide; max-width 240px; never interactive content.
-**Diverge**: delay duration — Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
+**Diverge**: delay duration - Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
 
 ---
 
@@ -72,8 +72,8 @@ A tooltip is a small, non-interactive label that appears on hover or keyboard fo
 
 ## Typography
 
-- 12px/400 — tooltip text is supplemental; smaller weight and size distinguish it from primary content
-- No bold, no headings inside tooltip — it is a single line of text (≤60 chars preferred)
+- 12px/400 - tooltip text is supplemental; smaller weight and size distinguish it from primary content
+- No bold, no headings inside tooltip - it is a single line of text (≤60 chars preferred)
 - Multi-line: allowed if content genuinely requires it; still no interactive elements
 
 ---
@@ -81,11 +81,11 @@ A tooltip is a small, non-interactive label that appears on hover or keyboard fo
 ## Keyboard & Accessibility
 
 > **WAI-ARIA role**: `tooltip`
-> **Trigger attributes**: `aria-describedby="tooltip-id"` — links the supplemental label
+> **Trigger attributes**: `aria-describedby="tooltip-id"` - links the supplemental label
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -97,11 +97,11 @@ Tooltip does NOT receive focus. It is purely a visual label attached to the trig
 
 ### Accessibility Rules
 
-- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` — screen readers read tooltip content as supplemental description
-- Tooltip is `role="tooltip"` — NOT `role="dialog"` (no interactivity, no focus trap)
-- Tooltip MUST appear on keyboard focus, not only on hover — keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
-- Do NOT put interactive content inside a tooltip — use Popover (`reference/components/popover.md`)
-- Do NOT use tooltip as the only accessible name for a control — use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
+- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` - screen readers read tooltip content as supplemental description
+- Tooltip is `role="tooltip"` - NOT `role="dialog"` (no interactivity, no focus trap)
+- Tooltip MUST appear on keyboard focus, not only on hover - keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
+- Do NOT put interactive content inside a tooltip - use Popover (`reference/components/popover.md`)
+- Do NOT use tooltip as the only accessible name for a control - use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
 - Escape MUST dismiss the tooltip without removing focus from the trigger *(WAI-ARIA APG)*
 
 ---
@@ -112,25 +112,25 @@ Tooltip does NOT receive focus. It is purely a visual label attached to the trig
 |------------|----------|--------|-------|
 | Show | 100ms | ease-out | Fade only; no scale (too flashy for a label) |
 | Hide | 80ms | ease | Fade only; immediate on Escape |
-| Delay | 300ms | — | CSS `transition-delay` or JS timeout |
+| Delay | 300ms | - | CSS `transition-delay` or JS timeout |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip fade, instant show/hide
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip fade, instant show/hide
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Show on keyboard focus AND hover — not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
+- Show on keyboard focus AND hover - not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
 - Use `aria-describedby` to link trigger to tooltip *(WAI-ARIA APG)*
-- Limit tooltip content to ≤60 chars — longer content belongs in a popover *(Carbon, Material 3)*
+- Limit tooltip content to ≤60 chars - longer content belongs in a popover *(Carbon, Material 3)*
 - Apply 300ms show delay to prevent accidental triggers while cursor passes *(WAI-ARIA APG, Carbon)*
 
 ### Don't
-- Don't put interactive elements inside a tooltip *(WAI-ARIA APG — this makes it a popover)*
-- Don't use tooltip as the only accessible name — `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
-- Don't trigger tooltip on click — use a popover *(Radix, WAI-ARIA APG)*
-- Don't use tooltip for critical information — it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
+- Don't put interactive elements inside a tooltip *(WAI-ARIA APG - this makes it a popover)*
+- Don't use tooltip as the only accessible name - `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
+- Don't trigger tooltip on click - use a popover *(Radix, WAI-ARIA APG)*
+- Don't use tooltip for critical information - it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
 
 ---