@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/components/badge.md

@@ -1,4 +1,4 @@
-# Badge — Benchmark Spec
+# Badge - Benchmark Spec
 
 **Harvested from**: Material 3, Polaris, Carbon, Radix
 **Wave**: 3 · **Category**: Feedback
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A badge is a compact numeric counter or status indicator overlaid on or beside a parent element (icon, avatar, button) to communicate a count (unread messages, notification count) or status (online, offline, busy). It is purely decorative — the accessible count or status is surfaced through the parent element's `aria-label`. *(Material 3, Polaris, Carbon, Radix agree: badge is decorative; parent carries accessible state)*
+A badge is a compact numeric counter or status indicator overlaid on or beside a parent element (icon, avatar, button) to communicate a count (unread messages, notification count) or status (online, offline, busy). It is purely decorative - the accessible count or status is surfaced through the parent element's `aria-label`. *(Material 3, Polaris, Carbon, Radix agree: badge is decorative; parent carries accessible state)*
 
 ---
 
@@ -36,7 +36,7 @@ A badge is a compact numeric counter or status indicator overlaid on or beside a
 | Badge element | Yes | Pill or circle shape containing count or dot |
 | Count / label text | Conditional | Present for count/icon variants; absent for dot |
 | Parent element | Yes (for attached) | Carries `aria-label` with accessible count |
-| Dot indicator | No | Status dot variant — no number, pure color/shape |
+| Dot indicator | No | Status dot variant - no number, pure color/shape |
 
 ---
 
@@ -70,7 +70,7 @@ A badge is a compact numeric counter or status indicator overlaid on or beside a
 |---------|-----------|-----------|-----------|-------|
 | Count (sm) | 16px | 16px (= height) | 10px/500 | Single digit fills circle |
 | Count (md) | 20px | 20px (= height) | 12px/500 | Two-digit + "99+" |
-| Dot | 8px | 8px | — | No text; absolute top-right |
+| Dot | 8px | 8px | - | No text; absolute top-right |
 
 - **Shape**: pill when width > height; circle when width = height (single digit)
 - **Position** (attached): `position: absolute; top: -4px; right: -4px` relative to parent
@@ -82,11 +82,11 @@ A badge is a compact numeric counter or status indicator overlaid on or beside a
 
 ## Typography
 
-- Count text: 10–12px / 500 (medium weight) — legible at small scale
+- Count text: 10–12px / 500 (medium weight) - legible at small scale
 - No wrapping; never truncate count text; use "99+" cap instead
-- Letter-spacing: 0 — tight spacing at 10–12px scale
+- Letter-spacing: 0 - tight spacing at 10–12px scale
 
-Cross-link: `reference/typography.md` — small label scale (10–12px)
+Cross-link: `reference/typography.md` - small label scale (10–12px)
 
 ---
 
@@ -97,7 +97,7 @@ Cross-link: `reference/typography.md` — small label scale (10–12px)
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -107,14 +107,14 @@ Badge never receives focus. It is a purely visual overlay. All keyboard interact
 
 ### Accessibility Rules
 
-- Badge element itself MUST have `aria-hidden="true"` — screen readers should not announce the badge number separately; they read it as part of the parent's `aria-label`
+- Badge element itself MUST have `aria-hidden="true"` - screen readers should not announce the badge number separately; they read it as part of the parent's `aria-label`
 - Parent element MUST have an `aria-label` that includes the count: `aria-label="Messages, 3 unread"` *(WAI-ARIA APG, Material 3)*
-- Parent `aria-label` MUST be updated dynamically when count changes — use `aria-live` on the parent if the count changes while the page is rendered *(WCAG 4.1.3)*
-- Zero badge: if badge is hidden at zero, remove it from DOM (or `display: none`) — do NOT leave it with empty text in the DOM *(Polaris)*
+- Parent `aria-label` MUST be updated dynamically when count changes - use `aria-live` on the parent if the count changes while the page is rendered *(WCAG 4.1.3)*
+- Zero badge: if badge is hidden at zero, remove it from DOM (or `display: none`) - do NOT leave it with empty text in the DOM *(Polaris)*
 - Dot variant: parent `aria-label` MUST include the status: `aria-label="User profile, status: online"` *(Radix)*
-- Never rely on badge color alone to communicate status — include text in parent `aria-label` *(WCAG 1.4.1)*
+- Never rely on badge color alone to communicate status - include text in parent `aria-label` *(WCAG 1.4.1)*
 
-Cross-link: `reference/accessibility.md` — dynamic label updates, aria-live
+Cross-link: `reference/accessibility.md` - dynamic label updates, aria-live
 
 ---
 
@@ -126,9 +126,9 @@ Cross-link: `reference/accessibility.md` — dynamic label updates, aria-live
 | Badge appear | 100ms | ease-out | Fade + scale from 0.5 |
 | Badge disappear (at zero) | 80ms | ease-in | Fade + scale to 0 |
 
-**BAN**: Continuous bounce animation on badge — implies urgency and is distracting; one-shot pulse on value change is acceptable.
+**BAN**: Continuous bounce animation on badge - implies urgency and is distracting; one-shot pulse on value change is acceptable.
 
-Cross-link: `reference/motion.md` — scale-in/scale-out; `prefers-reduced-motion`: skip all badge animation
+Cross-link: `reference/motion.md` - scale-in/scale-out; `prefers-reduced-motion`: skip all badge animation
 
 ---
 
@@ -142,9 +142,9 @@ Cross-link: `reference/motion.md` — scale-in/scale-out; `prefers-reduced-motio
 
 ### Don't
 - Don't surface badge count only through color (dot badge without parent label) *(WCAG 1.4.1)*
-- Don't put interactive content in a badge — it is always decorative *(Material 3, Carbon)*
-- Don't animate badge continuously — one-shot pulse on value change only *(Polaris)*
-- Don't use badge text as the only accessible notification — always update parent `aria-label` *(WAI-ARIA APG)*
+- Don't put interactive content in a badge - it is always decorative *(Material 3, Carbon)*
+- Don't animate badge continuously - one-shot pulse on value change only *(Polaris)*
+- Don't use badge text as the only accessible notification - always update parent `aria-label` *(WAI-ARIA APG)*
 
 ---
 

package/reference/components/breadcrumbs.md

@@ -1,4 +1,4 @@
-# Breadcrumbs — Benchmark Spec
+# Breadcrumbs - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Carbon, Polaris, Material 3, Atlassian
 **Wave**: 4 · **Category**: Navigation
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A breadcrumb trail shows a user's location within a hierarchical navigation structure, providing a supplemental path back to any ancestor page. It is not primary navigation — the current page is always the last item and is never a link. Breadcrumbs are most valuable in deep hierarchies (> 2 levels) and information-dense applications. *(WAI-ARIA APG breadcrumb pattern, Carbon, Polaris, Material 3, Atlassian all define breadcrumb as a supplemental location indicator)*
+A breadcrumb trail shows a user's location within a hierarchical navigation structure, providing a supplemental path back to any ancestor page. It is not primary navigation - the current page is always the last item and is never a link. Breadcrumbs are most valuable in deep hierarchies (> 2 levels) and information-dense applications. *(WAI-ARIA APG breadcrumb pattern, Carbon, Polaris, Material 3, Atlassian all define breadcrumb as a supplemental location indicator)*
 
 ---
 
@@ -26,7 +26,7 @@ A breadcrumb trail shows a user's location within a hierarchical navigation stru
 | Part | Required | Notes |
 |------|----------|-------|
 | `<nav>` container | Yes | `role="navigation"` + `aria-label="Breadcrumb"` |
-| `<ol>` list | Yes | Ordered list — sequence matters |
+| `<ol>` list | Yes | Ordered list - sequence matters |
 | `<li>` items | Yes | One per level in the path |
 | Ancestor links | Yes | `<a href>` pointing to each ancestor URL |
 | Current page | Yes | Plain text `<span>` (not a link) + `aria-current="page"` |
@@ -45,7 +45,7 @@ A breadcrumb trail shows a user's location within a hierarchical navigation stru
 | Large / heading-inline | Larger type, sits beside or below a page title | Polaris, Atlassian |
 
 **Norm** (≥4 systems agree): separator is `aria-hidden`; current page uses `aria-current="page"`; last item is never a link.
-**Diverge**: Polaris uses `>` as separator; Carbon uses `/`; Material 3 uses `›` (chevron). All are acceptable — choose to match your product's visual language.
+**Diverge**: Polaris uses `>` as separator; Carbon uses `/`; Material 3 uses `›` (chevron). All are acceptable - choose to match your product's visual language.
 
 ---
 
@@ -53,10 +53,10 @@ A breadcrumb trail shows a user's location within a hierarchical navigation stru
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Ancestor links + muted separator + current page text | — |
-| link-hover | pointer over ancestor | Underline or color shift | — |
-| link-focus | keyboard focus on ancestor | 2px focus-visible ring | — |
-| current | — | No underline; muted or bold treatment; not clickable | `aria-current="page"` |
+| default | - | Ancestor links + muted separator + current page text | - |
+| link-hover | pointer over ancestor | Underline or color shift | - |
+| link-focus | keyboard focus on ancestor | 2px focus-visible ring | - |
+| current | - | No underline; muted or bold treatment; not clickable | `aria-current="page"` |
 | truncated | path > 4 levels | Middle items hidden; "…" button shown | `aria-label="Show full path"` on ellipsis button |
 
 ---
@@ -80,9 +80,9 @@ A breadcrumb trail shows a user's location within a hierarchical navigation stru
 - Ancestor links: body-sm, weight 400, `color: --text-link`; underline on hover
 - Current page: body-sm, weight 500 or 600 (bold for emphasis), `color: --text-primary`; no underline
 - Separator: body-sm, `color: --text-subtle`, `aria-hidden="true"`
-- Do not use uppercase or letter-spacing on breadcrumb items — they should read as natural path segments
+- Do not use uppercase or letter-spacing on breadcrumb items - they should read as natural path segments
 
-Cross-link: `reference/typography.md` — body-sm, link color tokens
+Cross-link: `reference/typography.md` - body-sm, link color tokens
 
 ---
 
@@ -93,7 +93,7 @@ Cross-link: `reference/typography.md` — body-sm, link color tokens
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -103,13 +103,13 @@ Cross-link: `reference/typography.md` — body-sm, link color tokens
 
 ### Accessibility Rules
 
-- `aria-current="page"` MUST be on the last item (current page) — this is the primary AT signal
-- Separators MUST be `aria-hidden="true"` — screen readers should announce "Home, Products, Widget Pro" not "Home › Products › Widget Pro"
-- The current page item MUST NOT be a link — it is the user's current location
+- `aria-current="page"` MUST be on the last item (current page) - this is the primary AT signal
+- Separators MUST be `aria-hidden="true"` - screen readers should announce "Home, Products, Widget Pro" not "Home › Products › Widget Pro"
+- The current page item MUST NOT be a link - it is the user's current location
 - `<ol>` conveys that order matters; do not use `<ul>` or a `<div>` list
 - `aria-label="Breadcrumb"` distinguishes this nav from primary/secondary navigation landmarks
 
-Cross-link: `reference/accessibility.md` — aria-current, landmark labelling
+Cross-link: `reference/accessibility.md` - aria-current, landmark labelling
 
 ---
 
@@ -120,25 +120,25 @@ Cross-link: `reference/accessibility.md` — aria-current, landmark labelling
 | Ellipsis expand | 150ms | ease-out | Reveal hidden items inline |
 | Ellipsis collapse | 120ms | ease-in | Hide middle items |
 
-**BAN**: Do not animate the breadcrumb trail on route change — route transitions are the page's responsibility, not the breadcrumb's.
+**BAN**: Do not animate the breadcrumb trail on route change - route transitions are the page's responsibility, not the breadcrumb's.
 
-Cross-link: `reference/motion.md` — layout transitions
+Cross-link: `reference/motion.md` - layout transitions
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Use `<ol>` for the list — order is meaningful in a hierarchical path *(WAI-ARIA APG)*
-- Mark the current page with `aria-current="page"` — not just a CSS class *(WAI-ARIA APG, Atlassian)*
+- Use `<ol>` for the list - order is meaningful in a hierarchical path *(WAI-ARIA APG)*
+- Mark the current page with `aria-current="page"` - not just a CSS class *(WAI-ARIA APG, Atlassian)*
 - Hide separators with `aria-hidden="true"` *(WAI-ARIA APG, Carbon, Polaris)*
 - Truncate middle items (not first/last) when path exceeds 4 levels *(Carbon, Polaris, Atlassian)*
 
 ### Don't
-- Don't make the current page item a link — it creates a circular self-referential link *(WAI-ARIA APG)*
-- Don't include separator text inside link labels — `aria-hidden` the separator element, not the link *(WAI-ARIA APG)*
-- Don't use breadcrumbs as the only navigation method — they supplement; primary nav is required *(Material 3, Polaris)*
-- Don't truncate the root or current page items — users need anchoring context at both ends *(Carbon, Atlassian)*
+- Don't make the current page item a link - it creates a circular self-referential link *(WAI-ARIA APG)*
+- Don't include separator text inside link labels - `aria-hidden` the separator element, not the link *(WAI-ARIA APG)*
+- Don't use breadcrumbs as the only navigation method - they supplement; primary nav is required *(Material 3, Polaris)*
+- Don't truncate the root or current page items - users need anchoring context at both ends *(Carbon, Atlassian)*
 
 ---
 
@@ -146,7 +146,7 @@ Cross-link: `reference/motion.md` — layout transitions
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-07 | Missing `aria-current` on active navigation items — `reference/anti-patterns.md#ban-07` |
+| BAN-07 | Missing `aria-current` on active navigation items - `reference/anti-patterns.md#ban-07` |
 
 ---
 

package/reference/components/button.md

@@ -1,4 +1,4 @@
-# Button — Benchmark Spec
+# Button - Benchmark Spec
 
 **Harvested from**: Material 3, Polaris, Carbon, Fluent 2, Radix, shadcn/ui, Primer, Atlassian
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A button triggers a discrete action in the current context — submitting a form, opening a dialog, executing a command. It is not a navigation element (use Link for href-based navigation). Buttons have an explicit visual affordance of clickability and must communicate their current state (loading, disabled) clearly. *(Material 3, Carbon, Polaris agree: button = action trigger, not navigation)*
+A button triggers a discrete action in the current context - submitting a form, opening a dialog, executing a command. It is not a navigation element (use Link for href-based navigation). Buttons have an explicit visual affordance of clickability and must communicate their current state (loading, disabled) clearly. *(Material 3, Carbon, Polaris agree: button = action trigger, not navigation)*
 
 ---
 
@@ -42,7 +42,7 @@ A button triggers a discrete action in the current context — submitting a form
 | Link-style | Looks like link, behaves as button | Carbon, Primer |
 
 **Norm** (≥6/18 systems agree): primary/secondary/ghost hierarchy; one primary per viewport section.
-**Diverge**: "tertiary" naming (Material 3) vs. "ghost" (Carbon) vs. "plain" (Polaris) — same visual intent, different labels.
+**Diverge**: "tertiary" naming (Material 3) vs. "ghost" (Carbon) vs. "plain" (Polaris) - same visual intent, different labels.
 
 ---
 
@@ -50,15 +50,15 @@ A button triggers a discrete action in the current context — submitting a form
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Resting fill/border | — |
-| hover | pointer over | 8% overlay (light) / 8% overlay (dark) | — |
-| focus | keyboard focus | 2px focus-visible ring, 2px offset | — |
-| active / pressed | mousedown / Space / Enter | 12% overlay; scale 0.96 | — |
+| default | - | Resting fill/border | - |
+| hover | pointer over | 8% overlay (light) / 8% overlay (dark) | - |
+| focus | keyboard focus | 2px focus-visible ring, 2px offset | - |
+| active / pressed | mousedown / Space / Enter | 12% overlay; scale 0.96 | - |
 | disabled | `disabled` attr | 38% opacity; cursor: not-allowed | `disabled` attr |
 | loading | async action in flight | Spinner, `aria-busy="true"` | `aria-busy="true"` |
 
 **Norm**: 96% scale on press (Material 3, shadcn, Carbon confirm). 38% opacity for disabled (Material 3 spec).
-**Diverge**: hover overlay vs. background tint — systems use either approach; overlay is more theme-portable.
+**Diverge**: hover overlay vs. background tint - systems use either approach; overlay is more theme-portable.
 
 ---
 
@@ -71,17 +71,17 @@ A button triggers a discrete action in the current context — submitting a form
 | lg | 48px | 24px | 96px | 16px/500 |
 
 **Norm**: 40px default height (Carbon, Polaris, Fluent all confirm). Min-width prevents single-character buttons.
-Cross-link: `reference/surfaces.md` — hit-area rule (minimum 44×44px accessible tap target via padding, not height).
+Cross-link: `reference/surfaces.md` - hit-area rule (minimum 44×44px accessible tap target via padding, not height).
 
 ---
 
 ## Typography
 
-- Weight: 500 (medium) — not bold; distinguishes from body text without being heavy *(Material 3, Carbon)*
+- Weight: 500 (medium) - not bold; distinguishes from body text without being heavy *(Material 3, Carbon)*
 - Letter-spacing: +0.01em for sm/md, 0 for lg
-- No text truncation — resize button or use icon-only variant; truncated button labels break affordance
+- No text truncation - resize button or use icon-only variant; truncated button labels break affordance
 
-Cross-link: `reference/typography.md` — tabular-nums rule (use on loading counters, not labels)
+Cross-link: `reference/typography.md` - tabular-nums rule (use on loading counters, not labels)
 
 ---
 
@@ -92,7 +92,7 @@ Cross-link: `reference/typography.md` — tabular-nums rule (use on loading coun
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/button/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/button/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -101,7 +101,7 @@ Cross-link: `reference/typography.md` — tabular-nums rule (use on loading coun
 
 ### Accessibility Rules
 
-- Icon-only buttons MUST have `aria-label` or `aria-labelledby` — a tooltip is not a substitute
+- Icon-only buttons MUST have `aria-label` or `aria-labelledby` - a tooltip is not a substitute
 - Loading state: set `aria-busy="true"` and disable pointer events; announce completion via `aria-live`
 - Disabled: use native `disabled` attribute (not `aria-disabled`) unless button must remain focusable for tooltip explanation
 - Never use `<div>` or `<a>` as a button trigger without `role="button"` and keyboard handlers
@@ -119,9 +119,9 @@ Cross-link: `reference/accessibility.md`
 | press scale (0.96) | 80ms | ease-in | Immediate tactile feedback |
 | loading spinner in | 150ms | ease-out | Replaces or overlays label |
 
-**BAN**: `transition: all` — catches width change on loading and causes layout jank.
+**BAN**: `transition: all` - catches width change on loading and causes layout jank.
 
-Cross-link: `reference/motion.md` — canonical scale-on-press 0.96, BAN-04 (`transition: all`)
+Cross-link: `reference/motion.md` - canonical scale-on-press 0.96, BAN-04 (`transition: all`)
 
 ---
 
@@ -134,10 +134,10 @@ Cross-link: `reference/motion.md` — canonical scale-on-press 0.96, BAN-04 (`tr
 - Maintain 8px minimum spacing between adjacent buttons *(Carbon, Fluent)*
 
 ### Don't
-- Don't use a button for navigation to another page — use `<a href>` (Link) *(Carbon, Primer)*
-- Don't disable a button without explaining why — prefer showing error state after submission *(Polaris)*
-- Don't use "Click here" or "Submit" as labels — be specific about the action *(Polaris, Carbon)*
-- Don't truncate button labels — buttons must fit their content *(Fluent, Atlassian)*
+- Don't use a button for navigation to another page - use `<a href>` (Link) *(Carbon, Primer)*
+- Don't disable a button without explaining why - prefer showing error state after submission *(Polaris)*
+- Don't use "Click here" or "Submit" as labels - be specific about the action *(Polaris, Carbon)*
+- Don't truncate button labels - buttons must fit their content *(Fluent, Atlassian)*
 
 ---
 
@@ -145,7 +145,7 @@ Cross-link: `reference/motion.md` — canonical scale-on-press 0.96, BAN-04 (`tr
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on interactive elements - `reference/anti-patterns.md#ban-04` |
 
 ---
 

package/reference/components/card.md

@@ -1,4 +1,4 @@
-# Card — Benchmark Spec
+# Card - Benchmark Spec
 
 **Harvested from**: Material 3, Polaris, Carbon, Atlassian, Mantine, shadcn/ui, Ant Design, Fluent 2
 **Wave**: 2 · **Category**: Containers
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A card is a contained surface that groups related information and actions. It is a visual container, not a navigation element by default — only make the entire card clickable when the primary action is navigation and there is a single dominant action. Mixed-content cards with multiple actions should not be entirely clickable. *(Material 3, Polaris, Carbon all agree on this boundary)*
+A card is a contained surface that groups related information and actions. It is a visual container, not a navigation element by default - only make the entire card clickable when the primary action is navigation and there is a single dominant action. Mixed-content cards with multiple actions should not be entirely clickable. *(Material 3, Polaris, Carbon all agree on this boundary)*
 
 ---
 
@@ -48,7 +48,7 @@ A card is a contained surface that groups related information and actions. It is
 | Compact | Dense layout; no media | Carbon, Fluent |
 
 **Norm** (≥5/18): outlined or elevated; ≤2 actions per card.
-**Diverge**: elevation vs. outline — both are valid; use elevated for content that needs to float (dashboards), outlined for dense lists (tables of cards).
+**Diverge**: elevation vs. outline - both are valid; use elevated for content that needs to float (dashboards), outlined for dense lists (tables of cards).
 
 ---
 
@@ -56,10 +56,10 @@ A card is a contained surface that groups related information and actions. It is
 
 | State | Trigger | Visual | ARIA/HTML |
 |-------|---------|--------|-----------|
-| default | — | Resting surface | — |
-| hover (clickable) | pointer | Shadow deepens or border darkens | — |
-| focus (clickable) | keyboard | 2px focus ring on outer card | — |
-| active (clickable) | mousedown | Scale 0.99 | — |
+| default | - | Resting surface | - |
+| hover (clickable) | pointer | Shadow deepens or border darkens | - |
+| focus (clickable) | keyboard | 2px focus ring on outer card | - |
+| active (clickable) | mousedown | Scale 0.99 | - |
 | selected | programmatic | Border + background tint | `aria-selected="true"` |
 | loading | async content | Skeleton placeholder | `aria-busy="true"` |
 | disabled | programmatic | 38% opacity | `aria-disabled="true"` |
@@ -77,7 +77,7 @@ A card is a contained surface that groups related information and actions. It is
 | Max width | 480px (typical) | Grid controls actual width; max-width is a guideline |
 | Gap between cards | 16px (sm grid), 24px (md grid) | |
 
-Cross-link: `reference/surfaces.md` — concentric radius, 3-layer shadow formula, elevation tokens
+Cross-link: `reference/surfaces.md` - concentric radius, 3-layer shadow formula, elevation tokens
 
 ---
 
@@ -96,14 +96,14 @@ Cross-link: `reference/surfaces.md` — concentric radius, 3-layer shadow formul
 
 ### Clickable Card Rules
 
-*Per WAI-ARIA APG link + button patterns — W3C — 2024*
+*Per WAI-ARIA APG link + button patterns - W3C - 2024*
 
 | Invocation | Element | Key |
 |------------|---------|-----|
 | Navigate to new page | `<a href>` wrapping or inside card | Enter |
 | Trigger action in context | `<button>` wrapping or inside card | Enter, Space |
 
-- **Do not wrap an entire card in `<a>` if it contains other interactive elements** (links, buttons inside) — nested interactive elements are inaccessible by keyboard
+- **Do not wrap an entire card in `<a>` if it contains other interactive elements** (links, buttons inside) - nested interactive elements are inaccessible by keyboard
 - Use the "card with primary action + secondary actions" pattern: one `<a>` stretched via `::after` pseudo-element to fill the card; secondary action buttons sit above in stacking context
 
 ### Accessibility Rules
@@ -123,7 +123,7 @@ Cross-link: `reference/surfaces.md` — concentric radius, 3-layer shadow formul
 | press scale | 80ms | ease | 1→0.99 (subtle; card is large) |
 | skeleton shimmer | 1.5s | linear loop | Respect `prefers-reduced-motion` |
 
-Cross-link: `reference/motion.md` — Skeleton shimmer pattern, `prefers-reduced-motion`
+Cross-link: `reference/motion.md` - Skeleton shimmer pattern, `prefers-reduced-motion`
 
 ---
 
@@ -139,7 +139,7 @@ Cross-link: `reference/motion.md` — Skeleton shimmer pattern, `prefers-reduced
 - Don't wrap the entire card in `<a>` if it contains other interactive elements *(WAI-ARIA APG)*
 - Don't use `<div>` as a clickable card without `role="button"` or `role="link"` + keyboard handler *(WAI-ARIA APG)*
 - Don't place the entire card title in a plain `<span>` when it could be `<h2>/<h3>` *(Atlassian, Carbon)*
-- Don't use more than 2 primary actions per card — extract to a detail view *(Material 3, Polaris)*
+- Don't use more than 2 primary actions per card - extract to a detail view *(Material 3, Polaris)*
 
 ---
 
@@ -197,4 +197,4 @@ grep -rn 'class.*card' src/ | xargs grep -L 'h[1-6]\|aria-label' 2>/dev/null
 
 **Why it fails**: Nested `<button>` inside `<a>` is invalid HTML. Keyboard users pressing Tab inside the link may reach the button, but Enter on the button may also trigger the link. Screen reader behavior is unpredictable.
 **Grep detection**: `grep -rn '<a.*href' src/ | xargs grep -l '<button' 2>/dev/null`
-**Fix**: Use the stretched-link pattern — `<h3><a href="/product/42">Product Name</a></h3>` with `::after { position: absolute; inset: 0; }` on the `<a>`, and position the "Add to cart" button above via `position: relative; z-index: 1`.
+**Fix**: Use the stretched-link pattern - `<h3><a href="/product/42">Product Name</a></h3>` with `::after { position: absolute; inset: 0; }` on the `<a>`, and position the "Add to cart" button above via `position: relative; z-index: 1`.

package/reference/components/checkbox.md

@@ -1,4 +1,4 @@
-# Checkbox — Benchmark Spec
+# Checkbox - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Polaris, Ant Design, WAI-ARIA APG, Mantine, Chakra UI, Atlassian
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A checkbox allows the user to select or deselect a binary option, or to represent an indeterminate state (partially selected group). Checkboxes are independent — selecting one does not affect others. Use radio buttons for mutually exclusive choices within a group. Always group related checkboxes in a `<fieldset>` with a `<legend>`.
+A checkbox allows the user to select or deselect a binary option, or to represent an indeterminate state (partially selected group). Checkboxes are independent - selecting one does not affect others. Use radio buttons for mutually exclusive choices within a group. Always group related checkboxes in a `<fieldset>` with a `<legend>`.
 
 ---
 
@@ -31,7 +31,7 @@ Group:
 | Part | Required | Notes |
 |------|----------|-------|
 | Input / control | Yes | Native `<input type="checkbox">` preferred |
-| Label | Yes | `<label for="id">` — click zone includes label text |
+| Label | Yes | `<label for="id">` - click zone includes label text |
 | Fieldset + legend | Yes (group) | Required when ≥2 related checkboxes |
 | Helper text | No | Below label; `aria-describedby` |
 | Error message | Conditional | Field-level or group-level |
@@ -49,8 +49,8 @@ Group:
 | Group | ≥2 checkboxes in `<fieldset>` | All |
 | With description | Label + helper text below | Material 3, Polaris, Carbon |
 
-**Norm** (≥6/18): indeterminate state is a visual-only UI state — the underlying `checked` value is still boolean; set via DOM `.indeterminate` property, not HTML attribute.
-**Diverge**: size — Material 3 uses 18px; Carbon 16px; Polaris 16px; Ant 14–16px. 16px is the de-facto norm.
+**Norm** (≥6/18): indeterminate state is a visual-only UI state - the underlying `checked` value is still boolean; set via DOM `.indeterminate` property, not HTML attribute.
+**Diverge**: size - Material 3 uses 18px; Carbon 16px; Polaris 16px; Ant 14–16px. 16px is the de-facto norm.
 
 ---
 
@@ -61,8 +61,8 @@ Group:
 | unchecked | default | Empty box | `aria-checked="false"` |
 | checked | user interaction | Checkmark | `aria-checked="true"` |
 | indeterminate | set via JS | Dash / minus | `aria-checked="mixed"` |
-| hover | pointer over | Box border darkens | — |
-| focus | keyboard | 2px focus ring around box | — |
+| hover | pointer over | Box border darkens | - |
+| focus | keyboard | 2px focus ring around box | - |
 | disabled unchecked | `disabled` | 38% opacity | `aria-disabled="true"` |
 | disabled checked | `disabled` | 38% opacity + check | `aria-disabled="true"` |
 | error | validation | Red box border | `aria-invalid="true"` |
@@ -79,14 +79,14 @@ Group:
 | Group item spacing | 8px vertical between items | *(Carbon, Material 3)* |
 | Indentation (nested) | 24px | When showing hierarchical groups |
 
-Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern (44×44px minimum touch target)
+Cross-link: `reference/surfaces.md` - hit-area pseudo-element pattern (44×44px minimum touch target)
 
 ---
 
 ## Typography
 
-- Label: 14px/400; same weight as body — checkboxes are options, not headings
-- Legend: 14px/500 or 12px/600 uppercase — distinguishes group from items
+- Label: 14px/400; same weight as body - checkboxes are options, not headings
+- Legend: 14px/500 or 12px/600 uppercase - distinguishes group from items
 - Helper/error: 12px/400
 
 ---
@@ -98,20 +98,20 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern (44×44p
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
 | Tab | Moves focus to the checkbox |
 | Space | Toggles the checkbox state (checked / unchecked / indeterminate) |
 
-Within a group: Tab moves between checkboxes (not arrow keys — checkboxes are independent).
+Within a group: Tab moves between checkboxes (not arrow keys - checkboxes are independent).
 
 ### Accessibility Rules
 
-- Label MUST be associated via `<label for="id">` — clicking the label must toggle the checkbox
-- `<fieldset>` + `<legend>` MUST wrap every group of related checkboxes — the legend provides group context to screen readers
-- Indeterminate state MUST be set via JS `.indeterminate = true` — there is no HTML attribute; `aria-checked="mixed"` must be set simultaneously on `role="checkbox"` elements
+- Label MUST be associated via `<label for="id">` - clicking the label must toggle the checkbox
+- `<fieldset>` + `<legend>` MUST wrap every group of related checkboxes - the legend provides group context to screen readers
+- Indeterminate state MUST be set via JS `.indeterminate = true` - there is no HTML attribute; `aria-checked="mixed"` must be set simultaneously on `role="checkbox"` elements
 - Disabled checkboxes: use native `disabled` attribute for form semantics; `aria-disabled="true"` if the element must remain in tab order (e.g. with explanatory tooltip)
 - Error state: `aria-invalid="true"` on the control; group-level error on the `<fieldset>` via `aria-describedby`
 
@@ -125,7 +125,7 @@ Within a group: Tab moves between checkboxes (not arrow keys — checkboxes are
 | indeterminate dash | 120ms | ease | Width animation of dash element |
 | hover border | 80ms | ease | Border colour only |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip path animation, show fill instantly
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip path animation, show fill instantly
 
 ---
 
@@ -138,10 +138,10 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip path animat
 - Align label text to the top of the control in multiline label scenarios *(Carbon)*
 
 ### Don't
-- Don't use checkboxes for mutually exclusive options — use radio buttons *(Material 3, Carbon, Polaris)*
+- Don't use checkboxes for mutually exclusive options - use radio buttons *(Material 3, Carbon, Polaris)*
 - Don't use a custom `<div>` checkbox without `role="checkbox"` and keyboard handler *(WAI-ARIA APG)*
-- Don't set `aria-checked="mixed"` via HTML attribute — it must be set dynamically *(WAI-ARIA APG)*
-- Don't rely on colour alone for checked state — always include a visible checkmark *(WCAG 1.4.1)*
+- Don't set `aria-checked="mixed"` via HTML attribute - it must be set dynamically *(WAI-ARIA APG)*
+- Don't rely on colour alone for checked state - always include a visible checkmark *(WCAG 1.4.1)*
 
 ---
 
@@ -195,7 +195,7 @@ grep -rn 'indeterminate' src/ | grep 'setAttribute\|attr(' | grep '"true"'
 </div>
 ```
 
-**Why it fails**: Screen readers announce each option without the group context ("Email — checkbox") — users don't know what these options belong to without reading surrounding text.
+**Why it fails**: Screen readers announce each option without the group context ("Email - checkbox") - users don't know what these options belong to without reading surrounding text.
 **Grep detection**: `grep -B5 'type="checkbox"' src/ | grep -v 'fieldset\|role="group"'`
 **Fix**:
 ```html