@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/components/menu.md

@@ -1,4 +1,4 @@
-# Menu (Dropdown / Context Menu) — Benchmark Spec
+# Menu (Dropdown / Context Menu) - Benchmark Spec
 
 **Harvested from**: Radix UI, WAI-ARIA APG, Carbon, Atlassian, Material 3, Polaris
 **Wave**: 4 · **Category**: Navigation
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A menu presents a list of actions or options in a temporary overlay anchored to a trigger element. It differs from a Select/Combobox (which chooses a value) — a menu executes commands or navigates. Use a Dropdown Menu for trigger-button scenarios; use a Context Menu for right-click/long-press on an element. *(Radix DropdownMenu, Carbon OverflowMenu, Atlassian DropdownMenu, WAI-ARIA APG Menu agree: menus are action lists, not value selectors)*
+A menu presents a list of actions or options in a temporary overlay anchored to a trigger element. It differs from a Select/Combobox (which chooses a value) - a menu executes commands or navigates. Use a Dropdown Menu for trigger-button scenarios; use a Context Menu for right-click/long-press on an element. *(Radix DropdownMenu, Carbon OverflowMenu, Atlassian DropdownMenu, WAI-ARIA APG Menu agree: menus are action lists, not value selectors)*
 
 ---
 
@@ -29,7 +29,7 @@ A menu presents a list of actions or options in a temporary overlay anchored to
 | Trigger | Yes | `<button>` with `aria-haspopup="menu"` + `aria-expanded` |
 | Menu container | Yes | `role="menu"` + `aria-labelledby` pointing to trigger |
 | Menu item | Yes | `role="menuitem"` on each action |
-| Separator | No | `role="separator"` — groups related items |
+| Separator | No | `role="separator"` - groups related items |
 | Checkbox item | No | `role="menuitemcheckbox"` + `aria-checked` |
 | Radio item | No | `role="menuitemradio"` + `aria-checked`; group in `role="group"` |
 | Sub-menu trigger | No | `role="menuitem"` + `aria-haspopup="menu"` + `aria-expanded` |
@@ -56,7 +56,7 @@ A menu presents a list of actions or options in a temporary overlay anchored to
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| closed | — | Trigger visible; overlay hidden | `aria-expanded="false"` on trigger |
+| closed | - | Trigger visible; overlay hidden | `aria-expanded="false"` on trigger |
 | open | Click trigger | Overlay visible; first item focused | `aria-expanded="true"` on trigger |
 | item-hover / focus | Arrow keys or pointer | Item highlight (8% overlay) | `tabindex="-1"` managed via roving tabindex |
 | item-disabled | `disabled` prop | 38% opacity, cursor: default | `aria-disabled="true"` on item |
@@ -82,12 +82,12 @@ A menu presents a list of actions or options in a temporary overlay anchored to
 
 ## Typography
 
-- Item label: body-sm (13–14px), weight 400 — not bold; action labels read as text, not controls
+- Item label: body-sm (13–14px), weight 400 - not bold; action labels read as text, not controls
 - Destructive items: same weight, color token `--color-text-danger`
 - Keyboard shortcut hints: body-xs (11–12px), muted color, right-aligned, `aria-hidden="true"`
 - Truncate item labels with `text-overflow: ellipsis`; never wrap item text
 
-Cross-link: `reference/typography.md` — body-sm scale
+Cross-link: `reference/typography.md` - body-sm scale
 
 ---
 
@@ -98,7 +98,7 @@ Cross-link: `reference/typography.md` — body-sm scale
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -115,14 +115,14 @@ Cross-link: `reference/typography.md` — body-sm scale
 
 ### Accessibility Rules
 
-- Menu MUST open on click only — never on hover for primary open (hover may preview sub-menus)
+- Menu MUST open on click only - never on hover for primary open (hover may preview sub-menus)
 - All items MUST be reachable by keyboard; no mouse-only items
 - Focus returns to the trigger element when the menu closes
-- Keyboard shortcut labels (e.g. "⌘K") are `aria-hidden="true"` — the shortcut must be registered separately
+- Keyboard shortcut labels (e.g. "⌘K") are `aria-hidden="true"` - the shortcut must be registered separately
 - `role="separator"` dividers are not focusable
 - Disabled items use `aria-disabled="true"` (keep focusable so AT users know the option exists)
 
-Cross-link: `reference/accessibility.md` — focus management, roving tabindex
+Cross-link: `reference/accessibility.md` - focus management, roving tabindex
 
 ---
 
@@ -135,9 +135,9 @@ Cross-link: `reference/accessibility.md` — focus management, roving tabindex
 | Item highlight | 80ms | ease-out | Background color transition only |
 | Sub-menu enter | 120ms | ease-out | Same as menu enter |
 
-**BAN**: `transition: all` on menu items — triggers layout thrash on width changes.
+**BAN**: `transition: all` on menu items - triggers layout thrash on width changes.
 
-Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
+Cross-link: `reference/motion.md` - overlay entry pattern, BAN-04
 
 ---
 
@@ -145,15 +145,15 @@ Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
 
 ### Do
 - Use `role="menu"` + `role="menuitem"` for all action menus *(WAI-ARIA APG)*
-- Group related items with `role="separator"` — keep groups ≤ 7 items *(Carbon, Atlassian)*
+- Group related items with `role="separator"` - keep groups ≤ 7 items *(Carbon, Atlassian)*
 - Return focus to the trigger on close *(WAI-ARIA APG)*
 - Use `role="menuitemcheckbox"` for persistent toggle states *(Radix, Material 3)*
 
 ### Don't
-- Don't open the menu on hover as the primary interaction — keyboard users can't discover hover *(WCAG 1.3.3)*
-- Don't exceed 2 levels of sub-menus — deeply nested menus are cognitively expensive *(Atlassian, Carbon)*
-- Don't put form controls (inputs, sliders) inside a menu — use a Popover instead *(WAI-ARIA APG)*
-- Don't use `<div>` items without `role="menuitem"` — invisible to screen readers *(WAI-ARIA)*
+- Don't open the menu on hover as the primary interaction - keyboard users can't discover hover *(WCAG 1.3.3)*
+- Don't exceed 2 levels of sub-menus - deeply nested menus are cognitively expensive *(Atlassian, Carbon)*
+- Don't put form controls (inputs, sliders) inside a menu - use a Popover instead *(WAI-ARIA APG)*
+- Don't use `<div>` items without `role="menuitem"` - invisible to screen readers *(WAI-ARIA)*
 
 ---
 
@@ -161,7 +161,7 @@ Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
 
 | 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` |
 
 ---
 
@@ -207,6 +207,6 @@ grep -rn 'role="menu"' src/ | grep -v 'aria-labelledby\|aria-label'
 </div>
 ```
 
-**Why it fails**: No `role="menu"` or `role="menuitem"` — screen readers cannot announce this as a menu; items are not keyboard-navigable; no arrow-key navigation; trigger lacks `aria-haspopup` and `aria-expanded`.
+**Why it fails**: No `role="menu"` or `role="menuitem"` - screen readers cannot announce this as a menu; items are not keyboard-navigable; no arrow-key navigation; trigger lacks `aria-haspopup` and `aria-expanded`.
 **Grep detection**: `grep -rn '<div.*onclick\|<div.*onClick' src/ | grep -i 'menu\|dropdown'`
 **Fix**: Use `<ul role="menu">` with `<li role="menuitem" tabindex="-1">` items, or a headless menu primitive (Radix DropdownMenu, Downshift).

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