@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/color-theory.md

@@ -9,23 +9,23 @@ last_updated: 2026-05-18
 
 # Color Theory
 
-The existing [palette catalog](./palette-catalog.md) gives industry-vertical lookup — read a row, adopt the baseline tokens, ship. This file gives the underlying model so an agent can reason about color *before* applying it: which color space to author in, how to construct a harmony that holds together under motion and across viewing conditions, how surrounding context shifts perception, which hue pairs collapse under common color-blindness, and why default sRGB interpolation produces muddy mid-transitions in animation. Where the catalog says "shift the primary hue ±15°", this file replaces that hand-wave with explicit OKLCH ΔL/ΔC/Δh guidance.
+The existing [palette catalog](./palette-catalog.md) gives industry-vertical lookup - read a row, adopt the baseline tokens, ship. This file gives the underlying model so an agent can reason about color *before* applying it: which color space to author in, how to construct a harmony that holds together under motion and across viewing conditions, how surrounding context shifts perception, which hue pairs collapse under common color-blindness, and why default sRGB interpolation produces muddy mid-transitions in animation. Where the catalog says "shift the primary hue ±15°", this file replaces that hand-wave with explicit OKLCH ΔL/ΔC/Δh guidance.
 
-This is the file an agent should consult any time it is *constructing* color — picking a new palette, generating a harmony, animating a color, or auditing a contrast pair under the color-blindness lens.
+This is the file an agent should consult any time it is *constructing* color - picking a new palette, generating a harmony, animating a color, or auditing a contrast pair under the color-blindness lens.
 
 ---
 
-## Color Spaces — sRGB / HSL / OKLCH / LCH
+## Color Spaces - sRGB / HSL / OKLCH / LCH
 
 Color is not one thing. Every "color" lives in some color space, and every color space makes a trade between three concerns: device gamut (what monitors can actually display), authoring ergonomics (what a human can predict from the numbers), and perceptual uniformity (whether equal numeric jumps produce equal perceived jumps). Choosing the wrong space costs hours of token tweaking and produces palettes that drift under interpolation.
 
 ### sRGB
 
-sRGB is the device-coordinate space — three channels (`r`, `g`, `b`), each `0–255` or `0–1`, mapped onto the standard-monitor gamut defined by IEC 61966-2-1 (1996). It models *what the monitor emits*, not *what the eye perceives*. Equal numeric jumps are not equal perceptual jumps: stepping `rgb(50 50 50)` → `rgb(100 100 100)` looks like a much larger lightness change than `rgb(200 200 200)` → `rgb(250 250 250)`, even though both are a +50 step. Use sRGB only at the output layer (final compiled CSS), not as the authoring space for a palette.
+sRGB is the device-coordinate space - three channels (`r`, `g`, `b`), each `0–255` or `0–1`, mapped onto the standard-monitor gamut defined by IEC 61966-2-1 (1996). It models *what the monitor emits*, not *what the eye perceives*. Equal numeric jumps are not equal perceptual jumps: stepping `rgb(50 50 50)` → `rgb(100 100 100)` looks like a much larger lightness change than `rgb(200 200 200)` → `rgb(250 250 250)`, even though both are a +50 step. Use sRGB only at the output layer (final compiled CSS), not as the authoring space for a palette.
 
 ### HSL
 
-HSL was the first authoring-friendly attempt: three channels (`h` 0–360°, `s` 0–100%, `l` 0–100%) that decompose color into hue, saturation, and lightness — the dimensions a human reasons in. The catch: HSL's `l` is *not* perceptual lightness. `hsl(60 100% 50%)` (pure yellow) and `hsl(240 100% 50%)` (pure blue) both have `l: 50%`, but yellow looks vastly brighter than blue at identical `l`. This means a design instruction like "shift hue 30°, hold lightness constant" can produce wildly different perceived lightnesses across hue ranges. HSL is fine for quick mental math; it is wrong for token-system construction.
+HSL was the first authoring-friendly attempt: three channels (`h` 0–360°, `s` 0–100%, `l` 0–100%) that decompose color into hue, saturation, and lightness - the dimensions a human reasons in. The catch: HSL's `l` is *not* perceptual lightness. `hsl(60 100% 50%)` (pure yellow) and `hsl(240 100% 50%)` (pure blue) both have `l: 50%`, but yellow looks vastly brighter than blue at identical `l`. This means a design instruction like "shift hue 30°, hold lightness constant" can produce wildly different perceived lightnesses across hue ranges. HSL is fine for quick mental math; it is wrong for token-system construction.
 
 ### OKLCH
 
@@ -35,13 +35,13 @@ OKLCH is the modern authoring default: three channels (`L` 0–1 perceptual ligh
 2. **Independent C and h axes.** Adjusting chroma does not drift lightness; rotating hue does not drift either. Token systems become predictable.
 3. **Wide-gamut aware.** OKLCH expresses Display-P3 and Rec.2020 colors that sRGB cannot represent, while remaining a single authoring space.
 
-Browser support: CSS Color Module 4 `oklch(L C H)` shipped in Safari 15.4, Chrome 111, Firefox 113 — already production-safe for token authoring with sRGB fallback.
+Browser support: CSS Color Module 4 `oklch(L C H)` shipped in Safari 15.4, Chrome 111, Firefox 113 - already production-safe for token authoring with sRGB fallback.
 
 ### LCH
 
-LCH (CIE Lab-based) is OKLCH's older sibling: same three-axis structure (`L`, `C`, `h`), built on the 1976 CIE L*a*b* color space. It is perceptually uniform but has well-documented hue-rotation kinks in the blue range — straight-line hue interpolation through LCH visibly bends toward purple. OKLCH was specifically designed to fix this. Use LCH only when matching an existing print or video pipeline; otherwise prefer OKLCH.
+LCH (CIE Lab-based) is OKLCH's older sibling: same three-axis structure (`L`, `C`, `h`), built on the 1976 CIE L*a*b* color space. It is perceptually uniform but has well-documented hue-rotation kinks in the blue range - straight-line hue interpolation through LCH visibly bends toward purple. OKLCH was specifically designed to fix this. Use LCH only when matching an existing print or video pipeline; otherwise prefer OKLCH.
 
-### Concrete CSS — the same color in four spaces
+### Concrete CSS - the same color in four spaces
 
 Using `#1A56DB` from the FinTech/Banking row of [./palette-catalog.md](./palette-catalog.md) as the authoritative primary:
 
@@ -65,7 +65,7 @@ Using `#1A56DB` from the FinTech/Banking row of [./palette-catalog.md](./palette
 
 ## Color Harmonies
 
-All six harmonies expressed in OKLCH — adjust hue offset while holding `L` and `C` constant for perceptual stability. The hue offset is what defines the harmony; the lightness and chroma stay anchored so the relationship reads as a *family*, not a collision.
+All six harmonies expressed in OKLCH - adjust hue offset while holding `L` and `C` constant for perceptual stability. The hue offset is what defines the harmony; the lightness and chroma stay anchored so the relationship reads as a *family*, not a collision.
 
 ### Complementary
 
@@ -83,7 +83,7 @@ Formula: `h + 180°`, hold `L` and `C` constant.
 
 ### Analogous
 
-Three hues at small offsets — typically 30°. Reads as a single mood with internal modulation; ideal for backgrounds, illustrations, and gentle gradients.
+Three hues at small offsets - typically 30°. Reads as a single mood with internal modulation; ideal for backgrounds, illustrations, and gentle gradients.
 
 Formula: `[h - 30°, h, h + 30°]`, hold `L` and `C` constant.
 
@@ -98,7 +98,7 @@ Formula: `[h - 30°, h, h + 30°]`, hold `L` and `C` constant.
 
 ### Triadic
 
-Three hues evenly spaced 120° apart. High visual energy, balanced — used for playful brand systems and category color coding.
+Three hues evenly spaced 120° apart. High visual energy, balanced - used for playful brand systems and category color coding.
 
 Formula: `[h, h + 120°, h + 240°]`, hold `L` and `C` constant.
 
@@ -128,7 +128,7 @@ Formula: `[h, h + 150°, h + 210°]`, hold `L` and `C` constant.
 
 ### Tetradic
 
-Four hues forming a rectangle on the hue wheel — two complementary pairs offset from each other. Very rich; demands one dominant hue and three accents at lower chroma to avoid noise.
+Four hues forming a rectangle on the hue wheel - two complementary pairs offset from each other. Very rich; demands one dominant hue and three accents at lower chroma to avoid noise.
 
 Formula: `[h, h + 60°, h + 180°, h + 240°]`, hold `L` and `C` constant.
 
@@ -166,14 +166,14 @@ Formula: hold `h` constant; vary `L` across `0.95 → 0.15` for a 9-step scale;
 - **Two clear actions (primary vs. destructive):** complementary.
 - **Three-category coding (status: ok / warn / error):** triadic.
 - **Dashboard with one hero accent + supporting hues:** split-complement.
-- **Editorial / illustrative / rich brand:** tetradic — but reduce chroma on three of the four hues.
+- **Editorial / illustrative / rich brand:** tetradic - but reduce chroma on three of the four hues.
 - **Token system primarily expressing depth, not category:** monochromatic, scaled across `L`.
 
 ---
 
 ## Simultaneous Contrast and Warm-Cool Effects
 
-Color is never seen in isolation. The eye continuously normalizes color relative to its surround — a phenomenon Josef Albers documented exhaustively in *Interaction of Color* (1963) and which the perceptual literature calls *simultaneous contrast*. The same OKLCH value placed against a darker surround reads *lighter and more saturated* than placed against a lighter surround; against a complementary surround, hue itself shifts. Token-level lesson: a contrast ratio measured against pure white at design time is not the contrast a user perceives at runtime in a card-on-card-on-background layout.
+Color is never seen in isolation. The eye continuously normalizes color relative to its surround - a phenomenon Josef Albers documented exhaustively in *Interaction of Color* (1963) and which the perceptual literature calls *simultaneous contrast*. The same OKLCH value placed against a darker surround reads *lighter and more saturated* than placed against a lighter surround; against a complementary surround, hue itself shifts. Token-level lesson: a contrast ratio measured against pure white at design time is not the contrast a user perceives at runtime in a card-on-card-on-background layout.
 
 ```css
 /* Same foreground token, two surrounds. The same token reads as a different color. */
@@ -187,15 +187,15 @@ Color is never seen in isolation. The eye continuously normalizes color relative
 }
 ```
 
-Warm-cool effects are simultaneous contrast's spatial cousin. Warm hues (red through yellow, OKLCH `h` roughly 0–90°) read as *advancing* — they appear closer to the viewer; cool hues (green through blue, OKLCH `h` roughly 140–270°) read as *receding*. Place a warm accent against a cool field and the accent leaps forward; reverse the relationship and the same hue retreats. Use this deliberately: warm accents pull the eye to primary actions and selected states; cool accents recede appropriately for ambient information, hover states, and large background fields where you do not want the surface competing for attention.
+Warm-cool effects are simultaneous contrast's spatial cousin. Warm hues (red through yellow, OKLCH `h` roughly 0–90°) read as *advancing* - they appear closer to the viewer; cool hues (green through blue, OKLCH `h` roughly 140–270°) read as *receding*. Place a warm accent against a cool field and the accent leaps forward; reverse the relationship and the same hue retreats. Use this deliberately: warm accents pull the eye to primary actions and selected states; cool accents recede appropriately for ambient information, hover states, and large background fields where you do not want the surface competing for attention.
 
 ---
 
-## Color-Blindness — Deutan / Protan / Tritan
+## Color-Blindness - Deutan / Protan / Tritan
 
-Color-vision deficiency is common — roughly 8% of males and 0.5% of females of Northern European descent have some form. The three clinical types collapse different hue pairs:
+Color-vision deficiency is common - roughly 8% of males and 0.5% of females of Northern European descent have some form. The three clinical types collapse different hue pairs:
 
-- **Deutan** (deuteranomaly / deuteranopia, ~6% of males — the most common): reduced green sensitivity. Confuses red-green pairs at similar lightness, and green-brown at similar saturation.
+- **Deutan** (deuteranomaly / deuteranopia, ~6% of males - the most common): reduced green sensitivity. Confuses red-green pairs at similar lightness, and green-brown at similar saturation.
 - **Protan** (protanomaly / protanopia, ~1% of males): reduced red sensitivity. Confuses red-green pairs; reds appear darker than to typical vision.
 - **Tritan** (tritanomaly / tritanopia, very rare, <0.01%): reduced blue sensitivity. Confuses blue-yellow pairs and blue-green pairs.
 
@@ -204,9 +204,9 @@ Token-level guidance:
 1. **Never encode status with red/green alone at similar `L`.** A red-green status pair where both tokens sit at `oklch(0.6 …)` is invisible to a deutan viewer. Either separate `L` by at least 0.15, or distinguish with an icon/shape.
 2. **Prefer hue pairs separated by ≥ 120° in OKLCH `h` for category coding.** Red (`h ≈ 30°`) vs. blue (`h ≈ 260°`) is ~230° apart and reads reliably across all three types. Red (`h ≈ 30°`) vs. green (`h ≈ 140°`) is only ~110° apart and collapses under deutan.
 3. **Test the destructive / success pair under deutan simulation.** If a deutan filter renders them indistinguishable, raise their lightness contrast.
-4. **Add a non-color carrier.** Icons, underlines, bold weight, position — color must never be the *only* differentiator (WCAG 1.4.1, Use of Color).
+4. **Add a non-color carrier.** Icons, underlines, bold weight, position - color must never be the *only* differentiator (WCAG 1.4.1, Use of Color).
 
-A good starting palette is the **Wong 8-color CB-safe palette** (Bang Wong, *Nature Methods* 2011) — designed for scientific visualization to remain distinguishable under all three CVD types. Concrete OKLCH approximations of three of its colors for direct use in a token system:
+A good starting palette is the **Wong 8-color CB-safe palette** (Bang Wong, *Nature Methods* 2011) - designed for scientific visualization to remain distinguishable under all three CVD types. Concrete OKLCH approximations of three of its colors for direct use in a token system:
 
 ```css
 /* Three of the 8 Wong CB-safe palette colors, approximated in OKLCH. */
@@ -217,13 +217,13 @@ A good starting palette is the **Wong 8-color CB-safe palette** (Bang Wong, *Nat
 }
 ```
 
-See [./accessibility.md](./accessibility.md) for the WCAG intersection — color must not be the only differentiator (WCAG 1.4.1), and the chosen pair must still satisfy 4.5:1 body-text and 3:1 UI-element contrast thresholds at any combination used.
+See [./accessibility.md](./accessibility.md) for the WCAG intersection - color must not be the only differentiator (WCAG 1.4.1), and the chosen pair must still satisfy 4.5:1 body-text and 3:1 UI-element contrast thresholds at any combination used.
 
 ---
 
 ## Color Interpolation in Animation
 
-Animating from one color to another is interpolation across a color space, and the choice of space changes what the user sees mid-transition. When CSS animates `background-color` from red to green in default sRGB, the midpoint becomes muddy gray — sRGB's interpolation path crosses the desaturated valley between hues, dragging chroma toward 0 at the midpoint. The same animation in OKLCH walks a perceptually-clean arc along the hue wheel, preserving chroma and lightness across the transition. The user never sees gray.
+Animating from one color to another is interpolation across a color space, and the choice of space changes what the user sees mid-transition. When CSS animates `background-color` from red to green in default sRGB, the midpoint becomes muddy gray - sRGB's interpolation path crosses the desaturated valley between hues, dragging chroma toward 0 at the midpoint. The same animation in OKLCH walks a perceptually-clean arc along the hue wheel, preserving chroma and lightness across the transition. The user never sees gray.
 
 ```css
 /* BAD — default interpolation space is sRGB. Red → green midpoint is muddy gray. */
@@ -258,13 +258,13 @@ Animating from one color to another is interpolation across a color space, and t
 }
 ```
 
-Lab-based interpolation (`in lab` or `in oklab`) is also chromatically clean and is the right choice when matching a print pipeline; OKLCH is the right choice for everything else because hue stays on the perceptual wheel and lightness stays steady. Avoid `in hsl` for cross-hue interpolation — it inherits HSL's non-perceptual lightness and produces lightness drift across hue families.
+Lab-based interpolation (`in lab` or `in oklab`) is also chromatically clean and is the right choice when matching a print pipeline; OKLCH is the right choice for everything else because hue stays on the perceptual wheel and lightness stays steady. Avoid `in hsl` for cross-hue interpolation - it inherits HSL's non-perceptual lightness and produces lightness drift across hue families.
 
 Practical defaults:
 
 - **Same-hue intensity changes** (e.g., disabled → enabled, hover): any space is acceptable; OKLCH is still preferred for predictability.
 - **Cross-hue transitions** (status changes, theme swaps, brand-moment flourishes): mandate `in oklch` or `color-mix(in oklch, …)`. Default sRGB is the muddy-mid bug.
-- **Dark-mode swap animations**: mandate `in oklch` for the same reason — sRGB midpoints across the L extremes are visibly grayed.
+- **Dark-mode swap animations**: mandate `in oklch` for the same reason - sRGB midpoints across the L extremes are visibly grayed.
 
 See [./motion-interpolate.md](./motion-interpolate.md) for the cross-system motion-interpolation discipline that owns interpolation rules across spaces (timing, easing, value mapping). That file owns the interpolation rules; this section owns the color-specific reasoning.
 
@@ -272,8 +272,8 @@ See [./motion-interpolate.md](./motion-interpolate.md) for the cross-system moti
 
 ## Cross-References
 
-- [./palette-catalog.md](./palette-catalog.md) — industry-vertical lookup table; this file replaces its Step 4 "shift hue ±15°" instruction with explicit OKLCH ΔL/ΔC/Δh guidance and supplies the underlying color-space model.
-- [./motion-interpolate.md](./motion-interpolate.md) — cross-system motion-interpolation discipline; this file's §Color Interpolation in Animation links out to it for the broader interpolation rules.
-- [./accessibility.md](./accessibility.md) — WCAG 2.1 thresholds; this file's §Color-Blindness section intersects with WCAG 1.4.1 (Use of Color) and 1.4.3 (Contrast Minimum).
+- [./palette-catalog.md](./palette-catalog.md) - industry-vertical lookup table; this file replaces its Step 4 "shift hue ±15°" instruction with explicit OKLCH ΔL/ΔC/Δh guidance and supplies the underlying color-space model.
+- [./motion-interpolate.md](./motion-interpolate.md) - cross-system motion-interpolation discipline; this file's §Color Interpolation in Animation links out to it for the broader interpolation rules.
+- [./accessibility.md](./accessibility.md) - WCAG 2.1 thresholds; this file's §Color-Blindness section intersects with WCAG 1.4.1 (Use of Color) and 1.4.3 (Contrast Minimum).
 
-Reciprocal inbound cross-links land in Phase 28-06 (additive-only, D-06) — the other files will gain pointers back to this one without altering their existing content.
+Reciprocal inbound cross-links land in Phase 28-06 (additive-only, D-06) - the other files will gain pointers back to this one without altering their existing content.

package/reference/component-authoring.md

@@ -1,6 +1,6 @@
 # Component Authoring Principles
 
-Source: Emil Kowalski's work on Sonner, Vaul, and cmdk — synthesised from his published writing and talks. See also: `reference/framer-motion-patterns.md`, `reference/motion-advanced.md`.
+Source: Emil Kowalski's work on Sonner, Vaul, and cmdk - synthesised from his published writing and talks. See also: `reference/framer-motion-patterns.md`, `reference/motion-advanced.md`.
 
 Use this file when authoring, reviewing, or auditing UI components. The 6 principles apply as a lens during code review and design verification. Each principle has a grep-able audit signal.
 
@@ -25,7 +25,7 @@ grep -E "^\s+\w+: " src/components/Button.tsx | grep -v "?" | wc -l
 - 6–9 props total: acceptable if logically grouped
 - ≥10 props: flag for decomposition
 
-**Pattern — variant over prop explosion:**
+**Pattern - variant over prop explosion:**
 ```tsx
 // BAD — prop explosion
 <Button color="blue" size="md" rounded={true} shadow={true} uppercase={false} />
@@ -48,7 +48,7 @@ The right abstraction lets consumers build what they need by combining small pie
 grep -rE "(backgroundColor|textColor|borderRadius|fontSize)=" src/components/ --include="*.tsx"
 ```
 
-**Pattern — slot composition:**
+**Pattern - slot composition:**
 ```tsx
 // BAD — too much configuration
 <Card title="Hello" subtitle="World" icon="user" rightContent={<Badge />} />
@@ -78,7 +78,7 @@ A component with sensible defaults doesn't require the consumer to know its inte
 grep -E "^\s+\w+: " src/components/Toast.tsx | grep -v "?" | wc -l
 ```
 
-**The Sonner model:** `<Toaster />` with zero props renders a toast system that follows the OS color scheme, positions correctly on all viewports, stacks properly, and auto-dismisses at a sensible duration. All options exist — but the zero-prop case works.
+**The Sonner model:** `<Toaster />` with zero props renders a toast system that follows the OS color scheme, positions correctly on all viewports, stacks properly, and auto-dismisses at a sensible duration. All options exist - but the zero-prop case works.
 
 **Anti-pattern:** Required props for things with a logical default (e.g., `position` on a modal that should always default to `center`).
 

package/reference/components/README.md

@@ -3,16 +3,16 @@
 Per-component design specifications harvested from 18 major design systems.
 Each spec is ≤350 lines, greppable, diff-friendly, and agent-consumable.
 
-**Spec shape**: `TEMPLATE.md` — Purpose · Anatomy · Variants · States · Sizing ·
+**Spec shape**: `TEMPLATE.md` - Purpose · Anatomy · Variants · States · Sizing ·
 Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations · Grep signatures
 
 **Harvest source list**: `connections/design-corpora.md` (18 systems)
 **Tooling**: `agents/component-benchmark-harvester.md` → `agents/component-benchmark-synthesizer.md`
-**CLI**: `/gdd:benchmark <component>` — see `skills/benchmark/SKILL.md`
+**CLI**: `/gdd:benchmark <component>` - see `skills/benchmark/SKILL.md`
 
 ---
 
-## Wave 1 — Inputs (foundational)
+## Wave 1 - Inputs (foundational)
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
@@ -27,7 +27,7 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 
 ---
 
-## Wave 2 — Containers
+## Wave 2 - Containers
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
@@ -41,7 +41,7 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 
 ---
 
-## Wave 3 — Feedback
+## Wave 3 - Feedback
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
@@ -54,7 +54,7 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 
 ---
 
-## Wave 4 — Navigation & Data *(v1.17.0 · plan 17-02)*
+## Wave 4 - Navigation & Data *(v1.17.0 · plan 17-02)*
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
@@ -70,7 +70,7 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 
 ---
 
-## Wave 5 — Data & Advanced
+## Wave 5 - Data & Advanced
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
@@ -86,9 +86,9 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 
 | Wave | Specs | Status |
 |------|-------|--------|
-| Wave 1 — Inputs | 8 | v1.16.0 |
-| Wave 2 — Containers | 7 | v1.16.0 |
-| Wave 3 — Feedback | 6 | v1.17.0 |
-| Wave 4 — Navigation & Data | 9 | v1.17.0 |
-| Wave 5 — Data & Advanced | 5 | v1.17.0 |
-| **Total** | **35** | — |
+| Wave 1 - Inputs | 8 | v1.16.0 |
+| Wave 2 - Containers | 7 | v1.16.0 |
+| Wave 3 - Feedback | 6 | v1.17.0 |
+| Wave 4 - Navigation & Data | 9 | v1.17.0 |
+| Wave 5 - Data & Advanced | 5 | v1.17.0 |
+| **Total** | **35** | - |

package/reference/components/TEMPLATE.md

@@ -1,4 +1,4 @@
-# [Component Name] — Benchmark Spec
+# [Component Name] - Benchmark Spec
 
 > **Template version**: 1.0 (Phase 16)
 > Replace every placeholder in `[brackets]`. Delete this block before committing.
@@ -55,10 +55,10 @@ distinguishes it visually/behaviorally.]
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | [description] | — |
-| hover | pointer over | [description] | — |
-| focus | keyboard focus | focus-visible ring | — |
-| active / pressed | mousedown / Space/Enter | [description] | — |
+| default | - | [description] | - |
+| hover | pointer over | [description] | - |
+| focus | keyboard focus | focus-visible ring | - |
+| active / pressed | mousedown / Space/Enter | [description] | - |
 | disabled | `disabled` attr | [description] | `aria-disabled="true"` |
 | loading | [if applicable] | [description] | `aria-busy="true"` |
 | error | [if applicable] | [description] | `aria-invalid="true"` |
@@ -84,7 +84,7 @@ for typographic and radius rules.]
 
 [Any typographic constraints: weight, size relative to body, line-height cap, truncation rules.]
 
-Cross-link: `reference/typography.md` — [relevant section]
+Cross-link: `reference/typography.md` - [relevant section]
 
 ---
 
@@ -95,7 +95,7 @@ Cross-link: `reference/typography.md` — [relevant section]
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — [pattern URL] — W3C — [access date]*
+*Quoted verbatim from WAI-ARIA APG - [pattern URL] - W3C - [access date]*
 
 | Key | Action |
 |-----|--------|
@@ -103,11 +103,11 @@ Cross-link: `reference/typography.md` — [relevant section]
 
 ### Accessibility Rules
 
-- [Rule 1 — e.g., must have visible label or `aria-label`]
-- [Rule 2 — e.g., focus-visible ring must not be suppressed]
-- [Rule 3 — e.g., disabled state uses `aria-disabled`, not `disabled` attr, if interactive]
+- [Rule 1 - e.g., must have visible label or `aria-label`]
+- [Rule 2 - e.g., focus-visible ring must not be suppressed]
+- [Rule 3 - e.g., disabled state uses `aria-disabled`, not `disabled` attr, if interactive]
 
-Cross-link: `reference/accessibility.md` — [relevant section]
+Cross-link: `reference/accessibility.md` - [relevant section]
 
 ---
 
@@ -121,7 +121,7 @@ Cross-link: `reference/accessibility.md` — [relevant section]
 
 **BAN**: [any motion anti-patterns specific to this component]
 
-Cross-link: `reference/motion.md` — [relevant section]
+Cross-link: `reference/motion.md` - [relevant section]
 
 ---
 
@@ -143,7 +143,7 @@ Cross-link: `reference/motion.md` — [relevant section]
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| [BAN-XX] | [brief name] — `reference/anti-patterns.md#ban-xx` |
+| [BAN-XX] | [brief name] - `reference/anti-patterns.md#ban-xx` |
 
 ---
 

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.