@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/components/modal-dialog.md

@@ -1,4 +1,4 @@
-# Modal / Dialog — Benchmark Spec
+# Modal / Dialog - Benchmark Spec
 
 **Harvested from**: Radix UI Dialog, WAI-ARIA APG, Material 3, Atlassian, Carbon, Mantine, shadcn/ui, Fluent 2
 **Wave**: 2 · **Category**: Containers
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A modal dialog is a blocking overlay that requires user interaction before returning to the main content. It is rendered in a portal above the page, traps keyboard focus within itself, prevents interaction with the background, and closes on Escape. Use modals sparingly — they interrupt flow. Prefer inline feedback or slide-out drawers for non-critical workflows. *(Material 3, Atlassian, Polaris all advise modal restraint)*
+A modal dialog is a blocking overlay that requires user interaction before returning to the main content. It is rendered in a portal above the page, traps keyboard focus within itself, prevents interaction with the background, and closes on Escape. Use modals sparingly - they interrupt flow. Prefer inline feedback or slide-out drawers for non-critical workflows. *(Material 3, Atlassian, Polaris all advise modal restraint)*
 
 ---
 
@@ -50,7 +50,7 @@ A modal dialog is a blocking overlay that requires user interaction before retur
 | Scrollable content | Body scrolls; header/footer sticky | All |
 
 **Norm** (≥6/18): Escape closes; backdrop click may close (configurable); focus trapped inside.
-**Diverge**: backdrop-click-to-close — Material 3 and shadcn default to close; Atlassian and Carbon recommend NOT closing on backdrop click to prevent accidental dismissal of forms.
+**Diverge**: backdrop-click-to-close - Material 3 and shadcn default to close; Atlassian and Carbon recommend NOT closing on backdrop click to prevent accidental dismissal of forms.
 
 ---
 
@@ -71,12 +71,12 @@ A modal dialog is a blocking overlay that requires user interaction before retur
 | sm | 400px | 80vh | Confirm dialogs |
 | md (default) | 560px | 80vh | Standard |
 | lg | 720px | 90vh | Complex forms |
-| full | 100vw/100vh | — | Mobile sheet pattern |
+| full | 100vw/100vh | - | Mobile sheet pattern |
 
 Padding: 24px (header/footer), 24px (body horizontal), 20px (body vertical).
 Body scroll: `overflow-y: auto` with `overscroll-behavior: contain`.
 
-Cross-link: `reference/surfaces.md` — concentric radius, elevation (shadow-as-border)
+Cross-link: `reference/surfaces.md` - concentric radius, elevation (shadow-as-border)
 
 ---
 
@@ -95,7 +95,7 @@ Cross-link: `reference/surfaces.md` — concentric radius, elevation (shadow-as-
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -106,13 +106,13 @@ Cross-link: `reference/surfaces.md` — concentric radius, elevation (shadow-as-
 ### Focus Management
 
 1. **On open**: focus moves to the first focusable element inside the dialog (or to the dialog itself if no focusable children)
-2. **While open**: Tab/Shift+Tab cycle only within the dialog — focus MUST NOT leave the dialog
+2. **While open**: Tab/Shift+Tab cycle only within the dialog - focus MUST NOT leave the dialog
 3. **On close**: focus MUST return to the element that triggered the dialog open
 
 ### Accessibility Rules
 
-- `aria-modal="true"` MUST be set — tells AT to ignore background content (supplement with `inert` attribute on background for browsers without full `aria-modal` support)
-- Dialog title MUST have an `id` referenced by `aria-labelledby` — screen reader announces "Dialog: [title]" on open
+- `aria-modal="true"` MUST be set - tells AT to ignore background content (supplement with `inert` attribute on background for browsers without full `aria-modal` support)
+- Dialog title MUST have an `id` referenced by `aria-labelledby` - screen reader announces "Dialog: [title]" on open
 - `role="alertdialog"` for confirmation dialogs where the user must respond (delete confirmations, logout confirmation)
 - Scroll-lock: prevent `<body>` scroll when dialog is open (`overflow: hidden` on `<body>`)
 - Portal: render dialog in `document.body` to escape stacking context issues (z-index isolation)
@@ -126,10 +126,10 @@ Cross-link: `reference/surfaces.md` — concentric radius, elevation (shadow-as-
 | Backdrop fade in | 200ms | ease-out | opacity 0→0.5 |
 | Dialog enter | 200ms | ease-out | scale 0.95→1 + fade |
 | Dialog exit | 150ms | ease-in | scale 1→0.95 + fade |
-| Backdrop fade out | 150ms | ease-in | — |
+| Backdrop fade out | 150ms | ease-in | - |
 
 Use `AnimatePresence` (Framer Motion) or `data-state` + CSS for mount/unmount animation.
-Cross-link: `reference/motion.md` — `AnimatePresence initial={false}`, `prefers-reduced-motion`
+Cross-link: `reference/motion.md` - `AnimatePresence initial={false}`, `prefers-reduced-motion`
 
 ---
 
@@ -142,10 +142,10 @@ Cross-link: `reference/motion.md` — `AnimatePresence initial={false}`, `prefer
 - Set `overflow:hidden` on `<body>` to prevent background scroll *(Material 3, Carbon)*
 
 ### Don't
-- Don't close on backdrop click for dialogs with form input — data loss risk *(Atlassian, Carbon)*
-- Don't use `role="dialog"` without `aria-labelledby` — dialog is announced without a name *(WAI-ARIA APG)*
-- Don't use `display:none` to hide a dialog — use DOM removal or `hidden` attribute for correct AT behavior *(WAI-ARIA APG)*
-- Don't stack more than 2 dialogs — use a single dialog with internal step navigation *(Material 3, Atlassian)*
+- Don't close on backdrop click for dialogs with form input - data loss risk *(Atlassian, Carbon)*
+- Don't use `role="dialog"` without `aria-labelledby` - dialog is announced without a name *(WAI-ARIA APG)*
+- Don't use `display:none` to hide a dialog - use DOM removal or `hidden` attribute for correct AT behavior *(WAI-ARIA APG)*
+- Don't stack more than 2 dialogs - use a single dialog with internal step navigation *(Material 3, Atlassian)*
 
 ---
 
@@ -205,6 +205,6 @@ grep -rn 'modal.*open\|isOpen.*modal' src/ | grep -v 'overflow\|scroll-lock\|bod
 </div>
 ```
 
-**Why it fails**: No `role="dialog"`, no `aria-modal`, no `aria-labelledby` — screen readers cannot announce the dialog name or suppress background content. Tab escapes the modal. Escape does nothing.
+**Why it fails**: No `role="dialog"`, no `aria-modal`, no `aria-labelledby` - screen readers cannot announce the dialog name or suppress background content. Tab escapes the modal. Escape does nothing.
 **Grep detection**: `grep -rn 'class.*modal\|class.*dialog' src/ | grep -v 'role=\|aria-'`
 **Fix**: Use Radix `<Dialog>` or implement WAI-ARIA dialog pattern with `role="dialog"`, `aria-modal="true"`, `aria-labelledby`, focus trap, Escape handler, and portal rendering.

package/reference/components/navbar.md

@@ -1,4 +1,4 @@
-# Navbar (Top Navigation Bar) — Benchmark Spec
+# Navbar (Top Navigation Bar) - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Polaris, Atlassian, Primer, UUPM (app-interface, MIT)
 **Wave**: 4 · **Category**: Navigation
@@ -22,7 +22,7 @@ A navbar is the primary horizontal navigation surface at the top of an applicati
 
 | Part | Required | Notes |
 |------|----------|-------|
-| `<header>` wrapper | Yes | `role="banner"` — one per page |
+| `<header>` wrapper | Yes | `role="banner"` - one per page |
 | `<nav>` | Yes | `role="navigation"` + `aria-label="Primary"` |
 | Skip-to-main link | Yes | First focusable element; `href="#main-content"`; visible on focus |
 | Logo / home link | Yes | `<a href="/">` with `aria-label="[App name] home"` |
@@ -53,10 +53,10 @@ A navbar is the primary horizontal navigation surface at the top of an applicati
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Full nav visible, no shadow | — |
-| scrolled | scroll > 0 | `box-shadow` bottom border appears | — |
-| nav-item-hover | pointer over item | underline or bg highlight | — |
-| nav-item-focus | keyboard focus | 2px focus-visible ring | — |
+| default | - | Full nav visible, no shadow | - |
+| scrolled | scroll > 0 | `box-shadow` bottom border appears | - |
+| nav-item-hover | pointer over item | underline or bg highlight | - |
+| nav-item-focus | keyboard focus | 2px focus-visible ring | - |
 | nav-item-active | current route | `font-weight: 600` + indicator underline or pill | `aria-current="page"` |
 | mobile-collapsed | viewport < breakpoint | Nav items hidden; hamburger visible | `aria-expanded="false"` on hamburger |
 | mobile-expanded | hamburger activated | Nav items shown as vertical list | `aria-expanded="true"` on hamburger |
@@ -81,9 +81,9 @@ Mobile breakpoint: collapse at ≤768px (Carbon, Polaris); ≤960px for complex
 - Nav item labels: body-sm to body-md (13–15px), weight 500 for active, 400 for inactive
 - Active item visual distinction must not rely on color alone (add font-weight or underline indicator)
 - Secondary action icons: 20px, with `aria-label` on each button
-- Skip link text: `body-sm`, matches surrounding text — it only needs to be visible on focus
+- Skip link text: `body-sm`, matches surrounding text - it only needs to be visible on focus
 
-Cross-link: `reference/typography.md` — body scale, weight tokens
+Cross-link: `reference/typography.md` - body scale, weight tokens
 
 ---
 
@@ -94,7 +94,7 @@ Cross-link: `reference/typography.md` — body scale, weight tokens
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/landmark-regions/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/landmark-regions/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -105,13 +105,13 @@ Cross-link: `reference/typography.md` — body scale, weight tokens
 
 ### Accessibility Rules
 
-- `<nav>` MUST have `aria-label="Primary"` — multiple `<nav>` landmarks on a page must all be distinctly labelled
-- Skip-to-main link MUST be the first focusable element on the page — keyboard users need to bypass repetitive nav
-- Active nav item MUST use `aria-current="page"` — color alone is insufficient for AT users
-- Hamburger button MUST have `aria-expanded` and `aria-controls` — AT users need to know the nav state
+- `<nav>` MUST have `aria-label="Primary"` - multiple `<nav>` landmarks on a page must all be distinctly labelled
+- Skip-to-main link MUST be the first focusable element on the page - keyboard users need to bypass repetitive nav
+- Active nav item MUST use `aria-current="page"` - color alone is insufficient for AT users
+- Hamburger button MUST have `aria-expanded` and `aria-controls` - AT users need to know the nav state
 - `role="banner"` MUST appear only once per page (one `<header>` at page level)
 
-Cross-link: `reference/accessibility.md` — landmark regions, skip navigation
+Cross-link: `reference/accessibility.md` - landmark regions, skip navigation
 
 ---
 
@@ -124,9 +124,9 @@ Cross-link: `reference/accessibility.md` — landmark regions, skip navigation
 | Mobile menu close | 150ms | ease-in | Collapse |
 | Transparent → opaque on scroll | 200ms | ease-out | Background-color transition |
 
-**BAN**: Animating navbar height on scroll — causes layout reflow and jank on every scroll event.
+**BAN**: Animating navbar height on scroll - causes layout reflow and jank on every scroll event.
 
-Cross-link: `reference/motion.md` — layout-affecting transitions
+Cross-link: `reference/motion.md` - layout-affecting transitions
 
 ---
 
@@ -139,9 +139,9 @@ Cross-link: `reference/motion.md` — layout-affecting transitions
 - Manage z-index explicitly on sticky navbars to prevent overlap issues *(Material 3, Carbon)*
 
 ### Don't
-- Don't use multiple unlabelled `<nav>` landmarks — screen reader users can't distinguish them *(WCAG 4.1.2)*
+- Don't use multiple unlabelled `<nav>` landmarks - screen reader users can't distinguish them *(WCAG 4.1.2)*
 - Don't rely on color alone to indicate the active nav item *(WCAG 1.4.1)*
-- Don't put more than 7 primary nav items — overwhelming and hard to scan *(Carbon, Polaris HIG)*
+- Don't put more than 7 primary nav items - overwhelming and hard to scan *(Carbon, Polaris HIG)*
 - Don't use `position: fixed` on mobile without accounting for virtual keyboard displacement
 
 ---
@@ -150,7 +150,7 @@ Cross-link: `reference/motion.md` — layout-affecting transitions
 
 | 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/pagination.md

@@ -1,4 +1,4 @@
-# Pagination — Benchmark Spec
+# Pagination - Benchmark Spec
 
 **Harvested from**: Carbon, Polaris, Atlassian, Mantine, Material 3, UUPM (app-interface, MIT)
 **Wave**: 4 · **Category**: Navigation
@@ -53,12 +53,12 @@ Pagination divides a large dataset into discrete pages and provides controls to
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | All buttons enabled except current page | — |
-| current-page | — | Filled/highlighted button | `aria-current="page"` |
+| default | - | All buttons enabled except current page | - |
+| current-page | - | Filled/highlighted button | `aria-current="page"` |
 | prev-disabled | page = 1 | Previous button dimmed | `disabled` or `aria-disabled="true"` |
 | next-disabled | page = last | Next button dimmed | `disabled` or `aria-disabled="true"` |
-| button-hover | pointer over | 8% overlay | — |
-| button-focus | keyboard focus | 2px focus-visible ring | — |
+| button-hover | pointer over | 8% overlay | - |
+| button-focus | keyboard focus | 2px focus-visible ring | - |
 | loading | page change in flight | Spinner overlay on content; buttons retain focus | `aria-busy="true"` on results region |
 
 ---
@@ -84,7 +84,7 @@ Pagination divides a large dataset into discrete pages and provides controls to
 - Results summary: body-sm, `color: --text-subtle`
 - Per-page label: label-sm (12px), always visible above or beside the select
 
-Cross-link: `reference/typography.md` — body-sm, label scale
+Cross-link: `reference/typography.md` - body-sm, label scale
 
 ---
 
@@ -95,7 +95,7 @@ Cross-link: `reference/typography.md` — body-sm, label scale
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/landmark-regions/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/landmark-regions/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -105,14 +105,14 @@ Cross-link: `reference/typography.md` — body-sm, label scale
 
 ### Accessibility Rules
 
-- `aria-label="Pagination"` MUST be on the `<nav>` — distinguishes from other navigation landmarks on the page
-- `aria-current="page"` MUST be on the currently active page button — screen readers announce "Page 3, current"
+- `aria-label="Pagination"` MUST be on the `<nav>` - distinguishes from other navigation landmarks on the page
+- `aria-current="page"` MUST be on the currently active page button - screen readers announce "Page 3, current"
 - Previous button on page 1 and Next button on last page MUST use `disabled` or `aria-disabled="true"` + visually dimmed
 - `aria-label` on each page number button ("Page 1", "Page 2") prevents screen readers from just announcing the number alone
 - Results summary text MUST use `aria-live="polite"` so screen reader users hear the count update after page change
-- Per-page `<select>` MUST have a visible `<label>` — not just a placeholder
+- Per-page `<select>` MUST have a visible `<label>` - not just a placeholder
 
-Cross-link: `reference/accessibility.md` — aria-current, landmark labelling, live regions
+Cross-link: `reference/accessibility.md` - aria-current, landmark labelling, live regions
 
 ---
 
@@ -124,9 +124,9 @@ Cross-link: `reference/accessibility.md` — aria-current, landmark labelling, l
 | Page change content transition | 150ms | ease-out | Fade the results region; managed by page, not pagination |
 | Ellipsis expand (if interactive) | 120ms | ease-out | Reveal hidden page buttons |
 
-**BAN**: Do not animate the pagination bar itself when a page changes — only the content region transitions.
+**BAN**: Do not animate the pagination bar itself when a page changes - only the content region transitions.
 
-Cross-link: `reference/motion.md` — content region transitions
+Cross-link: `reference/motion.md` - content region transitions
 
 ---
 
@@ -139,10 +139,10 @@ Cross-link: `reference/motion.md` — content region transitions
 - Show a results summary ("Showing 51–75 of 587") near the pagination controls *(Carbon, Polaris)*
 
 ### Don't
-- Don't use `<a href>` with pushState without `aria-current` — screen readers won't know which page is current *(WAI-ARIA)*
-- Don't show more than 7 page buttons without ellipsis truncation — visually overwhelming *(Carbon, Mantine)*
-- Don't disable the Previous/Next buttons with only visual styling — use `disabled` attr or `aria-disabled` *(WCAG 1.4.3)*
-- Don't place pagination at the top only — bottom placement is expected; both positions is acceptable *(Polaris, Carbon)*
+- Don't use `<a href>` with pushState without `aria-current` - screen readers won't know which page is current *(WAI-ARIA)*
+- Don't show more than 7 page buttons without ellipsis truncation - visually overwhelming *(Carbon, Mantine)*
+- Don't disable the Previous/Next buttons with only visual styling - use `disabled` attr or `aria-disabled` *(WCAG 1.4.3)*
+- Don't place pagination at the top only - bottom placement is expected; both positions is acceptable *(Polaris, Carbon)*
 
 ---
 
@@ -150,7 +150,7 @@ Cross-link: `reference/motion.md` — content region 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/popover.md

@@ -1,4 +1,4 @@
-# Popover — Benchmark Spec
+# Popover - Benchmark Spec
 
 **Harvested from**: Radix UI Popover, Floating UI, Mantine, Atlassian, WAI-ARIA APG, shadcn/ui, Carbon, Material 3
 **Wave**: 2 · **Category**: Containers
@@ -48,7 +48,7 @@ A popover is an anchored overlay that appears beside a trigger element, containi
 | Inline picker | Date, color, emoji picker | Material 3, Mantine |
 
 **Norm** (≥5/18): Escape closes; outside-click closes; arrow pointer indicates anchor.
-**Diverge**: focus trap — Radix Popover does NOT trap focus (non-modal); Radix Dialog DOES. Use Dialog-pattern when content isolation is required.
+**Diverge**: focus trap - Radix Popover does NOT trap focus (non-modal); Radix Dialog DOES. Use Dialog-pattern when content isolation is required.
 
 ---
 
@@ -64,7 +64,7 @@ A popover is an anchored overlay that appears beside a trigger element, containi
 
 ## Positioning
 
-*Per Floating UI — https://floating-ui.com — MIT — 2024*
+*Per Floating UI - https://floating-ui.com - MIT - 2024*
 
 | Property | Recommended Value | Notes |
 |----------|-------------------|-------|
@@ -97,7 +97,7 @@ Positioning must update on scroll and resize (`autoUpdate` from Floating UI).
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/ (non-modal variant) — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/ (non-modal variant) - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -112,7 +112,7 @@ Positioning must update on scroll and resize (`autoUpdate` from Floating UI).
 - When popover is dismissed, focus MUST return to the trigger element
 - Non-modal popover: Tab MAY leave the popover (focus is not trapped)
 - Modal popover (form isolation): add `role="dialog"` + `aria-modal="true"` + focus trap
-- Popover with interactive content: do NOT use `role="tooltip"` — tooltip cannot contain interactive elements
+- Popover with interactive content: do NOT use `role="tooltip"` - tooltip cannot contain interactive elements
 
 ---
 
@@ -122,25 +122,25 @@ Positioning must update on scroll and resize (`autoUpdate` from Floating UI).
 |------------|----------|--------|-------|
 | Open | 120ms | ease-out | scale 0.95→1 + fade; origin at trigger |
 | Close | 80ms | ease-in | fade only |
-| Position update | 0ms | — | No animation on reposition (prevents jank on scroll) |
+| Position update | 0ms | - | No animation on reposition (prevents jank on scroll) |
 
-Cross-link: `reference/motion.md` — `AnimatePresence`, `data-state` trigger for CSS transitions
+Cross-link: `reference/motion.md` - `AnimatePresence`, `data-state` trigger for CSS transitions
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Use Floating UI or equivalent for positioning — manual positioning breaks on scroll and viewport edge *(Radix, Mantine, shadcn)*
+- Use Floating UI or equivalent for positioning - manual positioning breaks on scroll and viewport edge *(Radix, Mantine, shadcn)*
 - Dismiss on outside-click AND Escape *(WAI-ARIA APG, Radix, all systems)*
 - Return focus to trigger on close *(WAI-ARIA APG)*
 - Auto-flip and auto-shift so popover stays in viewport *(Floating UI)*
 
 ### Don't
-- Don't use `role="tooltip"` for popovers with interactive content — tooltip has a different contract *(WAI-ARIA APG)*
-- Don't position with `position: absolute` without a Floating UI — it will misalign on scroll *(Floating UI docs)*
-- Don't make popovers wider than 360px — use a modal for complex content *(Atlassian, Carbon)*
-- Don't auto-open popovers on hover — use tooltip for hover-triggered content *(Radix, WAI-ARIA APG)*
+- Don't use `role="tooltip"` for popovers with interactive content - tooltip has a different contract *(WAI-ARIA APG)*
+- Don't position with `position: absolute` without a Floating UI - it will misalign on scroll *(Floating UI docs)*
+- Don't make popovers wider than 360px - use a modal for complex content *(Atlassian, Carbon)*
+- Don't auto-open popovers on hover - use tooltip for hover-triggered content *(Radix, WAI-ARIA APG)*
 
 ---
 

package/reference/components/progress.md

@@ -1,4 +1,4 @@
-# Progress — Benchmark Spec
+# Progress - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon (ProgressIndicator), Polaris, Mantine
 **Wave**: 3 · **Category**: Feedback
@@ -33,8 +33,8 @@ A progress indicator communicates the status of an ongoing operation. Determinat
 |------|----------|-------|
 | Track | Yes | Background rail (linear) or ring background (circular) |
 | Fill / indicator | Yes | Foreground showing progress amount |
-| Label (visually hidden ok) | Yes | `aria-label` or `aria-labelledby` — describes what is loading |
-| Value text | No | Rendered percentage (e.g. "45%") — supplement to ARIA value |
+| Label (visually hidden ok) | Yes | `aria-label` or `aria-labelledby` - describes what is loading |
+| Value text | No | Rendered percentage (e.g. "45%") - supplement to ARIA value |
 
 ---
 
@@ -70,7 +70,7 @@ A progress indicator communicates the status of an ongoing operation. Determinat
 | Size | Height | Notes |
 |------|--------|-------|
 | sm | 4px (default) | Decorative; thin above content |
-| md | 8px | Accessible minimum — recommended when bar is the primary indicator |
+| md | 8px | Accessible minimum - recommended when bar is the primary indicator |
 | lg | 12px | High-emphasis; file upload, step progress |
 
 **Circular**
@@ -87,11 +87,11 @@ A progress indicator communicates the status of an ongoing operation. Determinat
 
 ## Typography
 
-- Value label (if shown): numeric-sm (12px/tabular-nums) — percentage readability
-- Associated label (if visible): body-sm (14px/400) — describes what is loading
+- Value label (if shown): numeric-sm (12px/tabular-nums) - percentage readability
+- Associated label (if visible): body-sm (14px/400) - describes what is loading
 - Do not truncate the associated label; use a visually-hidden version if space is constrained
 
-Cross-link: `reference/typography.md` — tabular-nums for percentage values
+Cross-link: `reference/typography.md` - tabular-nums for percentage values
 
 ---
 
@@ -102,7 +102,7 @@ Cross-link: `reference/typography.md` — tabular-nums for percentage values
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/meter/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/meter/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -112,14 +112,14 @@ Progress indicators are read-only status elements. They receive no keyboard focu
 
 ### Accessibility Rules
 
-- `aria-label` or `aria-labelledby` MUST describe what is loading (e.g. "Uploading file", "Loading results") — a bare `role="progressbar"` with no label is announced as empty *(WAI-ARIA APG)*
+- `aria-label` or `aria-labelledby` MUST describe what is loading (e.g. "Uploading file", "Loading results") - a bare `role="progressbar"` with no label is announced as empty *(WAI-ARIA APG)*
 - Determinate bars MUST include `aria-valuenow` matching the current integer percentage *(WAI-ARIA APG)*
 - Indeterminate bars MUST omit `aria-valuenow` and instead set `aria-valuetext="Loading"` or similar *(WAI-ARIA APG)*
 - `aria-valuemin` and `aria-valuemax` MUST be present on all progress bars (default 0 and 100)
-- Indeterminate animation MUST respect `prefers-reduced-motion` — reduce to opacity pulse or static indicator *(WCAG 2.3.3)*
+- Indeterminate animation MUST respect `prefers-reduced-motion` - reduce to opacity pulse or static indicator *(WCAG 2.3.3)*
 - Color contrast of fill vs. track MUST meet 3:1 minimum for non-text UI components *(WCAG 1.4.11)*
 
-Cross-link: `reference/accessibility.md` — `prefers-reduced-motion`, WCAG 1.4.11
+Cross-link: `reference/accessibility.md` - `prefers-reduced-motion`, WCAG 1.4.11
 
 ---
 
@@ -132,9 +132,9 @@ Cross-link: `reference/accessibility.md` — `prefers-reduced-motion`, WCAG 1.4.
 | Circular spin | 1.2s | linear | Single full rotation per cycle |
 | Complete → remove | 400ms | ease-in | Brief hold at 100% then fade/collapse |
 
-**BAN**: Bouncing or elasticity on indeterminate loop — communicates false progress rhythm. Do not use `transition: all` (catches color changes during theme swap).
+**BAN**: Bouncing or elasticity on indeterminate loop - communicates false progress rhythm. Do not use `transition: all` (catches color changes during theme swap).
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: replace sweep with opacity 0.5→1 pulse
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: replace sweep with opacity 0.5→1 pulse
 
 ---
 
@@ -143,14 +143,14 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: replace sweep wi
 ### Do
 - Always provide `aria-label` describing what is loading *(WAI-ARIA APG)*
 - Use `aria-valuenow` on determinate variants and omit on indeterminate *(WAI-ARIA APG)*
-- Use 8px+ height for standalone linear bars — 4px bars lack sufficient touch and visual target *(Carbon)*
+- Use 8px+ height for standalone linear bars - 4px bars lack sufficient touch and visual target *(Carbon)*
 - Transition fill smoothly (300ms ease-out) when value updates *(Material 3, Mantine)*
 
 ### Don't
-- Don't use `aria-valuenow` on indeterminate bars — it implies a known value *(WAI-ARIA APG)*
-- Don't show a spinner (circular indeterminate) when content shape is known — use Skeleton instead *(Carbon, Polaris)*
-- Don't remove the progress bar the instant it hits 100% — hold briefly so the completion is registered *(Material 3)*
-- Don't animate with infinite bounce — implies bouncing progress rhythm *(Carbon, Mantine)*
+- Don't use `aria-valuenow` on indeterminate bars - it implies a known value *(WAI-ARIA APG)*
+- Don't show a spinner (circular indeterminate) when content shape is known - use Skeleton instead *(Carbon, Polaris)*
+- Don't remove the progress bar the instant it hits 100% - hold briefly so the completion is registered *(Material 3)*
+- Don't animate with infinite bounce - implies bouncing progress rhythm *(Carbon, Mantine)*
 
 ---
 

package/reference/components/radio.md

@@ -1,4 +1,4 @@
-# Radio — Benchmark Spec
+# Radio - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Fluent 2, Mantine, WAI-ARIA APG, Polaris, Ant Design, Chakra UI
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A radio button represents one option within a mutually exclusive group. Selecting one radio button deselects all others in the same group. Always wrap radio buttons in a `<fieldset>` + `<legend>` and group them with the same `name` attribute. Never use a single radio button — it creates an unresettable state. Use a checkbox for binary choices.
+A radio button represents one option within a mutually exclusive group. Selecting one radio button deselects all others in the same group. Always wrap radio buttons in a `<fieldset>` + `<legend>` and group them with the same `name` attribute. Never use a single radio button - it creates an unresettable state. Use a checkbox for binary choices.
 
 ---
 
@@ -44,7 +44,7 @@ A radio button represents one option within a mutually exclusive group. Selectin
 | Button group | Segmented-control appearance | Material 3, Fluent 2, Carbon |
 
 **Norm** (≥6/18): vertical stacking default; horizontal allowed for ≤3 short labels.
-**Diverge**: button-group vs. radio-card — visual styling differs but keyboard contract is identical.
+**Diverge**: button-group vs. radio-card - visual styling differs but keyboard contract is identical.
 
 ---
 
@@ -52,10 +52,10 @@ A radio button represents one option within a mutually exclusive group. Selectin
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| unselected | default | Empty circle | — |
+| unselected | default | Empty circle | - |
 | selected | user interaction / programmatic | Filled dot | `checked` attr |
-| hover | pointer over | Circle border darkens | — |
-| focus | keyboard (Tab into group) | 2px focus ring on currently selected / first | — |
+| hover | pointer over | Circle border darkens | - |
+| focus | keyboard (Tab into group) | 2px focus ring on currently selected / first | - |
 | disabled | `disabled` attr | 38% opacity | `aria-disabled="true"` |
 | error | group-level | Red border on legend/container | `aria-describedby` on `<fieldset>` |
 
@@ -71,14 +71,14 @@ A radio button represents one option within a mutually exclusive group. Selectin
 | Item spacing (vertical) | 8–12px | *(Carbon: 8px, Material 3: 8px)* |
 | Touch target | 44×44px via pseudo-element | `reference/surfaces.md` |
 
-Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
+Cross-link: `reference/surfaces.md` - hit-area pseudo-element pattern
 
 ---
 
 ## Typography
 
-- Label: 14px/400 — same as body; option is a choice, not a heading
-- Legend: 14px/500 or 12px/600 uppercase — distinct from option labels
+- Label: 14px/400 - same as body; option is a choice, not a heading
+- Legend: 14px/500 or 12px/600 uppercase - distinct from option labels
 - Helper/error: 12px/400
 
 ---
@@ -91,7 +91,7 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/radio/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/radio/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -105,10 +105,10 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
 
 ### Accessibility Rules
 
-- `<fieldset>` + `<legend>` MUST wrap the entire group — legend text is prepended to each option announcement
+- `<fieldset>` + `<legend>` MUST wrap the entire group - legend text is prepended to each option announcement
 - All radios in a group MUST share the same `name` attribute
-- Tab focuses the selected radio (or first, if none selected) — arrow keys navigate within the group
-- Never use a single radio button — it creates a state the user cannot unset; use a checkbox
+- Tab focuses the selected radio (or first, if none selected) - arrow keys navigate within the group
+- Never use a single radio button - it creates a state the user cannot unset; use a checkbox
 - Error state applies to the group: `aria-describedby` on the `<fieldset>` or `role="radiogroup"` container
 - `required`: apply to all radios in the group or use `aria-required` on the group container
 
@@ -122,7 +122,7 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
 | Deselect | 80ms | ease | Dot scale 1→0 |
 | Hover border | 80ms | ease | Border colour only |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip dot animation, show fill instantly
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip dot animation, show fill instantly
 
 ---
 
@@ -132,11 +132,11 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip dot animati
 - Always use `<fieldset>` + `<legend>` for the group *(WAI-ARIA APG, Carbon, Polaris)*
 - Use the same `name` attribute for all radios in a group *(HTML spec, all systems)*
 - Pre-select a default option where appropriate to reduce cognitive load *(Material 3, Polaris)*
-- Use arrow keys to navigate within a group — Tab moves to the group, not each item *(WAI-ARIA APG)*
+- Use arrow keys to navigate within a group - Tab moves to the group, not each item *(WAI-ARIA APG)*
 
 ### Don't
-- Don't use a single radio button — use a checkbox instead *(Material 3, Carbon, WAI-ARIA APG)*
-- Don't use radio buttons for mutually exclusive options that require confirmation — use a select *(Polaris)*
+- Don't use a single radio button - use a checkbox instead *(Material 3, Carbon, WAI-ARIA APG)*
+- Don't use radio buttons for mutually exclusive options that require confirmation - use a select *(Polaris)*
 - Don't mix radio and checkbox styles in the same group *(Carbon, Polaris)*
 - Don't require the user to make a selection before seeing other page content (premature required state) *(Polaris)*