@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/components/accordion.md

@@ -1,4 +1,4 @@
-# Accordion — Benchmark Spec
+# Accordion - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG, Radix UI, Carbon, Chakra UI, Material 3, Mantine, shadcn/ui, Atlassian
 **Wave**: 2 · **Category**: Containers
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-An accordion is a vertically stacked set of headers that each reveal or conceal an associated section of content when activated. It reduces visual clutter by hiding content that is not immediately relevant. The header MUST be a button (or have `role="button"`) — users must be able to activate sections by keyboard. *(WAI-ARIA APG, Radix, Carbon all agree)*
+An accordion is a vertically stacked set of headers that each reveal or conceal an associated section of content when activated. It reduces visual clutter by hiding content that is not immediately relevant. The header MUST be a button (or have `role="button"`) - users must be able to activate sections by keyboard. *(WAI-ARIA APG, Radix, Carbon all agree)*
 
 ---
 
@@ -47,7 +47,7 @@ An accordion is a vertically stacked set of headers that each reveal or conceal
 | With icon | Leading icon per header | Carbon, Atlassian |
 
 **Norm** (≥5/18): chevron icon rotates on open (180°); panel animates height.
-**Diverge**: single-open vs. multi-open — Radix defaults to multi-open (more flexible); Material 3 defaults to single-open (simpler UX). Multi-open is safer for long FAQ pages where users may want to compare sections.
+**Diverge**: single-open vs. multi-open - Radix defaults to multi-open (more flexible); Material 3 defaults to single-open (simpler UX). Multi-open is safer for long FAQ pages where users may want to compare sections.
 
 ---
 
@@ -57,8 +57,8 @@ An accordion is a vertically stacked set of headers that each reveal or conceal
 |-------|---------|--------|------|
 | collapsed | default | Panel hidden | `aria-expanded="false"` on button |
 | expanded | button activated | Panel visible | `aria-expanded="true"` on button |
-| hover | pointer over header | Header background tint | — |
-| focus | keyboard | 2px focus ring on button | — |
+| hover | pointer over header | Header background tint | - |
+| focus | keyboard | 2px focus ring on button | - |
 | disabled | programmatic | 38% opacity; non-interactive | `aria-disabled="true"` on button |
 
 ---
@@ -77,7 +77,7 @@ An accordion is a vertically stacked set of headers that each reveal or conceal
 
 ## Typography
 
-- Header: 14–16px/500 — slightly heavier than panel body
+- Header: 14–16px/500 - slightly heavier than panel body
 - Panel body: 14px/400
 - Disabled header: same size, 38% opacity
 
@@ -91,7 +91,7 @@ An accordion is a vertically stacked set of headers that each reveal or conceal
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/accordion/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/accordion/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -107,12 +107,12 @@ Arrow/Home/End navigation is optional; Tab navigation between headers is always
 
 ### Accessibility Rules
 
-- Header MUST be wrapped in an `<h2>`–`<h6>` tag to maintain document outline — the heading level should match the surrounding page hierarchy
-- The trigger MUST be a `<button>` (or `role="button"`) — `<div>` headers are inaccessible by keyboard
+- Header MUST be wrapped in an `<h2>`–`<h6>` tag to maintain document outline - the heading level should match the surrounding page hierarchy
+- The trigger MUST be a `<button>` (or `role="button"`) - `<div>` headers are inaccessible by keyboard
 - `aria-expanded` MUST be on the trigger button, not the panel
-- Panel SHOULD have `role="region"` + `aria-labelledby` referencing the trigger button id — this creates a named region for landmark navigation
+- Panel SHOULD have `role="region"` + `aria-labelledby` referencing the trigger button id - this creates a named region for landmark navigation
 - `role="region"` should be omitted if there are more than 6 accordions (too many regions = noisy landmark nav)
-- Avoid `display:none` for the panel in open state — use `hidden` or height animation
+- Avoid `display:none` for the panel in open state - use `hidden` or height animation
 
 ---
 
@@ -131,7 +131,7 @@ Arrow/Home/End navigation is optional; Tab navigation between headers is always
 .panel > div { overflow: hidden; }
 ```
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip height animation, instant toggle
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip height animation, instant toggle
 
 ---
 
@@ -140,13 +140,13 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip height anim
 ### Do
 - Wrap header triggers in proper heading tags (`<h2>`–`<h6>`) *(WAI-ARIA APG, Carbon)*
 - Use `aria-expanded` on the trigger button, not on the panel *(WAI-ARIA APG)*
-- Animate height with `grid-template-rows` trick — no JS height measurement needed *(CSS-only pattern)*
+- Animate height with `grid-template-rows` trick - no JS height measurement needed *(CSS-only pattern)*
 - Support Tab navigation between accordion headers at minimum *(WAI-ARIA APG)*
 
 ### Don't
 - Don't use `<div>` as the accordion header without `role="button"` *(WAI-ARIA APG)*
-- Don't use `display:none` to hide the panel in collapsed state if you want animation — use CSS grid trick *(CSS pattern)*
-- Don't use `role="region"` for more than 6 accordions — excessive landmarks harm screen reader navigation *(WAI-ARIA APG note)*
+- Don't use `display:none` to hide the panel in collapsed state if you want animation - use CSS grid trick *(CSS pattern)*
+- Don't use `role="region"` for more than 6 accordions - excessive landmarks harm screen reader navigation *(WAI-ARIA APG note)*
 - Don't auto-close other panels in a "single-open" accordion without announcing the change *(Atlassian)*
 
 ---

package/reference/components/alert.md

@@ -1,4 +1,4 @@
-# Alert / Banner — Benchmark Spec
+# Alert / Banner - Benchmark Spec
 
 **Harvested from**: Material 3 (Banner), Carbon (InlineNotification), Polaris (Banner), Atlassian (SectionMessage)
 **Wave**: 3 · **Category**: Feedback
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-An alert (inline notification or banner) is a persistent in-page message that communicates status, warnings, or errors relevant to the current context. Unlike Toast, it does not auto-dismiss — it remains visible until the user dismisses it or the underlying condition resolves. Use alert for messages that require acknowledgement or that must remain visible for reference. *(Material 3, Carbon, Polaris, Atlassian agree: alert = persistent inline feedback)*
+An alert (inline notification or banner) is a persistent in-page message that communicates status, warnings, or errors relevant to the current context. Unlike Toast, it does not auto-dismiss - it remains visible until the user dismisses it or the underlying condition resolves. Use alert for messages that require acknowledgement or that must remain visible for reference. *(Material 3, Carbon, Polaris, Atlassian agree: alert = persistent inline feedback)*
 
 ---
 
@@ -43,7 +43,7 @@ An alert (inline notification or banner) is a persistent in-page message that co
 | Warning | Amber; potentially harmful condition; `role="alert"` assertive | All |
 | Error | Red; failure or blocking condition; `role="alert"` assertive | All |
 
-**Norm** (≥4/18 systems agree): four-variant semantic model (info/success/warning/error) with matching color, icon, and role. Icon is REQUIRED — color alone violates WCAG 1.4.1.
+**Norm** (≥4/18 systems agree): four-variant semantic model (info/success/warning/error) with matching color, icon, and role. Icon is REQUIRED - color alone violates WCAG 1.4.1.
 **Diverge**: Atlassian names this "SectionMessage" and omits dismiss; Carbon always includes an X; Polaris supports titled and untitled variants; Material 3 "Banner" supports one CTA only.
 
 ---
@@ -53,8 +53,8 @@ An alert (inline notification or banner) is a persistent in-page message that co
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
 | visible | render | Full opacity, inline position | `role="alert"` or `role="status"` |
-| hover | pointer over action | Action underline / background change | — |
-| focus | keyboard on action/dismiss | focus-visible ring on button | — |
+| hover | pointer over action | Action underline / background change | - |
+| focus | keyboard on action/dismiss | focus-visible ring on button | - |
 | dismissed | click dismiss button | Collapsed / removed | Removed from DOM |
 
 ---
@@ -78,11 +78,11 @@ An alert (inline notification or banner) is a persistent in-page message that co
 
 ## Typography
 
-- Title: label-md (14px/600) — gives quick scannable context for complex errors
-- Message: body-sm (14px/400) — readable at inline scale
-- Action: label-sm (13px/500) — matches action button label weight
+- Title: label-md (14px/600) - gives quick scannable context for complex errors
+- Message: body-sm (14px/400) - readable at inline scale
+- Action: label-sm (13px/500) - matches action button label weight
 
-Cross-link: `reference/typography.md` — body-sm, label-md definitions
+Cross-link: `reference/typography.md` - body-sm, label-md definitions
 
 ---
 
@@ -93,7 +93,7 @@ Cross-link: `reference/typography.md` — body-sm, label-md definitions
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/alert/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/alert/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -105,14 +105,14 @@ The alert container itself is not focusable. Child buttons follow standard butto
 
 ### Accessibility Rules
 
-- Icon MUST be `aria-hidden="true"` — the icon is decorative reinforcement; the `role` and text carry the semantic meaning *(WCAG 1.4.1)*
-- Color MUST NOT be the sole differentiator between variants — icon shape and text label must also differ *(WCAG 1.4.1)*
-- `role="alert"` causes immediate assertion by screen readers — only use for error and warning severity
-- `role="status"` uses a polite live region — appropriate for info and success
+- Icon MUST be `aria-hidden="true"` - the icon is decorative reinforcement; the `role` and text carry the semantic meaning *(WCAG 1.4.1)*
+- Color MUST NOT be the sole differentiator between variants - icon shape and text label must also differ *(WCAG 1.4.1)*
+- `role="alert"` causes immediate assertion by screen readers - only use for error and warning severity
+- `role="status"` uses a polite live region - appropriate for info and success
 - Dismiss button MUST have `aria-label` (e.g. `aria-label="Dismiss warning"`) *(WAI-ARIA APG)*
-- Do NOT auto-dismiss alerts — that is Toast's job; alert stays until explicitly dismissed *(Carbon, Polaris)*
+- Do NOT auto-dismiss alerts - that is Toast's job; alert stays until explicitly dismissed *(Carbon, Polaris)*
 
-Cross-link: `reference/accessibility.md` — live-regions, color-contrast sections
+Cross-link: `reference/accessibility.md` - live-regions, color-contrast sections
 
 ---
 
@@ -122,27 +122,27 @@ Cross-link: `reference/accessibility.md` — live-regions, color-contrast sectio
 |------------|----------|--------|-------|
 | Enter (height expand + fade) | 200ms | ease-out | Pushes content down; avoids position:fixed |
 | Exit (height collapse + fade) | 150ms | ease-in | Content reflows up as alert closes |
-| Icon entrance | 0ms | — | No animation on icon; immediate |
+| Icon entrance | 0ms | - | No animation on icon; immediate |
 
-**BAN**: Slide-in from edge (reserve for Toast). Alert is inline — it should feel like content appearing, not a notification arriving.
+**BAN**: Slide-in from edge (reserve for Toast). Alert is inline - it should feel like content appearing, not a notification arriving.
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip height animation, instant show/hide
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip height animation, instant show/hide
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Always include an icon matching the semantic variant *(WCAG 1.4.1 — color not sole differentiator)*
+- Always include an icon matching the semantic variant *(WCAG 1.4.1 - color not sole differentiator)*
 - Use `role="alert"` for warning/error (assertive) and `role="status"` for info/success (polite) *(WAI-ARIA APG)*
 - Keep alert visible until the condition is resolved or user dismisses *(Carbon, Polaris)*
 - Use full-width for page-level alerts; rounded inline for component-level *(Material 3, Carbon)*
 
 ### Don't
-- Don't auto-dismiss alerts — use Toast for transient messages *(Material 3, Carbon)*
-- Don't use color alone to distinguish severity — always include an icon and text label *(WCAG 1.4.1)*
-- Don't stack more than 2 alerts in the same section — consolidate into a single summary *(Polaris)*
-- Don't use `role="alert"` for info/success — overly assertive announcements desensitize users *(WAI-ARIA APG)*
+- Don't auto-dismiss alerts - use Toast for transient messages *(Material 3, Carbon)*
+- Don't use color alone to distinguish severity - always include an icon and text label *(WCAG 1.4.1)*
+- Don't stack more than 2 alerts in the same section - consolidate into a single summary *(Polaris)*
+- Don't use `role="alert"` for info/success - overly assertive announcements desensitize users *(WAI-ARIA APG)*
 
 ---
 
@@ -193,6 +193,6 @@ grep -rn 'alert--error\|alert--warning\|alert-error\|alert-warning' src/ | grep
 </div>
 ```
 
-**Why it fails**: No `role="alert"` so screen readers do not announce the error message. Color class alone distinguishes severity — users with color blindness or high-contrast themes cannot distinguish this from a neutral message. No icon provides a shape-based cue.
+**Why it fails**: No `role="alert"` so screen readers do not announce the error message. Color class alone distinguishes severity - users with color blindness or high-contrast themes cannot distinguish this from a neutral message. No icon provides a shape-based cue.
 **Grep detection**: `grep -rn 'class.*alert--error\|class.*alert-error' src/ | grep -v 'role='`
 **Fix**: Add `role="alert"`, include an error icon with `aria-hidden="true"`, and ensure the variant is communicated through text or visually-hidden label in addition to color.

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` |
 
 ---