@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/checklists.md

@@ -1,6 +1,6 @@
 # Pre-Delivery Checklists
 
-Run these before saying "done." Each checklist below is **gated** — if any item fails, you cannot ship.
+Run these before saying "done." Each checklist below is **gated** - if any item fails, you cannot ship.
 
 ## Master pre-ship checklist
 
@@ -60,7 +60,7 @@ Use this before any design artifact goes to the user or into a PR.
 - [ ] Error messages: what happened + how to fix (not just what's wrong)
 - [ ] Empty state acknowledges state + explains value + one CTA
 - [ ] No "Oops!" / forced cheer in errors
-- [ ] No 3-adjective pile-up ("beautiful, seamless, intuitive")
+- [ ] No 3-adjective pile-up ("beautiful, smooth, intuitive")
 - [ ] Placeholders show format, not restated label
 
 ### Technical check (code artifacts)
@@ -78,7 +78,7 @@ Use this before any design artifact goes to the user or into a PR.
 
 ---
 
-## Quick checklist — Small changes
+## Quick checklist - Small changes
 
 When the change is a single-screen tweak, use this shortened list:
 
@@ -99,11 +99,11 @@ When the change is a single-screen tweak, use this shortened list:
 When adding tokens/components to the design system:
 
 - [ ] New tokens follow `[category].[variant].[property].[state]` naming
-- [ ] No primitive token used directly in a component — route through semantic
+- [ ] No primitive token used directly in a component - route through semantic
 - [ ] Component has full anatomy doc (slots + variants + states + behavior + platform notes + do/don't)
 - [ ] Figma spec frame exists OR explicit note that it doesn't
 - [ ] Component validated against: same-structure-variant rule, not-a-new-component rule
-- [ ] 30-min audit performed — no off-grid spacings, no duplicate color tokens
+- [ ] 30-min audit performed - no off-grid spacings, no duplicate color tokens
 
 ---
 
@@ -145,18 +145,18 @@ Use this checklist after the main design review for pixel-level craft verificati
 
 ### Typography micro
 - [ ] Headings use `text-wrap: balance`
-- [ ] Body/caption uses `text-wrap: pretty` (or no wrap setting — not `balance`)
+- [ ] Body/caption uses `text-wrap: pretty` (or no wrap setting - not `balance`)
 - [ ] Font smoothing applied at `:root` only, not per-element
 - [ ] Dynamic numbers (counters, prices, timers) use `font-variant-numeric: tabular-nums`
 
 ### Surfaces
 - [ ] Nested elements use concentric radius (`innerRadius = outerRadius − padding`)
 - [ ] No same-radius parent+child within padded container (see BAN-10 same-radius-nested)
-- [ ] Images have `outline: 1px solid rgba(0,0,0,0.08)` — no tinted outlines
+- [ ] Images have `outline: 1px solid rgba(0,0,0,0.08)` - no tinted outlines
 - [ ] Interactive elements <40px have `::after` hit-area extension to 40×40
 
 ### Motion
-- [ ] Press feedback uses `scale(0.96)` — not 0.95, not 0.97, not 0.98
+- [ ] Press feedback uses `scale(0.96)` - not 0.95, not 0.97, not 0.98
 - [ ] `AnimatePresence` on persistent UI has `initial={false}`
 - [ ] Icon cross-fade spring has `bounce: 0`
 - [ ] No `transition: all` anywhere (see BAN-12 transition-all)
@@ -165,30 +165,30 @@ Use this checklist after the main design review for pixel-level craft verificati
 
 ---
 
-## Rams Lens — 10 Design Questions
+## Rams Lens - 10 Design Questions
 
 Dieter Rams's 10 principles of good design (Vitsœ/Braun, 1970s–80s) applied as a self-audit lens. Each question maps to one principle.
 
-- [ ] **Innovative** — Does this design solve the problem in a way that was not possible or obvious before?
-- [ ] **Useful** — Does every element serve the primary function? Nothing decorative that doesn't earn its place?
-- [ ] **Aesthetic** — Is the visual appearance the minimum necessary for legibility and emotional resonance?
-- [ ] **Understandable** — Can the user figure out how to use this without reading documentation or a tooltip?
-- [ ] **Unobtrusive** — Does the design stay in the background and let the content or task take focus?
-- [ ] **Honest** — Does the design not imply capabilities, quality, or status that the product doesn't have?
-- [ ] **Long-lasting** — Is this design free of trend-dependent choices (gradients, micro-styles) that will age in 12 months?
-- [ ] **Thorough** — Have edge cases been considered and handled (empty states, error states, loading states, overflow text)?
-- [ ] **Environmentally friendly** — Is the performance footprint minimal? (image sizes, JS bundle, font weight)
-- [ ] **As little design as possible** — If you removed 20% of the design decisions, would the product be worse? If not, remove them.
+- [ ] **Innovative** - Does this design solve the problem in a way that was not possible or obvious before?
+- [ ] **Useful** - Does every element serve the primary function? Nothing decorative that doesn't earn its place?
+- [ ] **Aesthetic** - Is the visual appearance the minimum necessary for legibility and emotional resonance?
+- [ ] **Understandable** - Can the user figure out how to use this without reading documentation or a tooltip?
+- [ ] **Unobtrusive** - Does the design stay in the background and let the content or task take focus?
+- [ ] **Honest** - Does the design not imply capabilities, quality, or status that the product doesn't have?
+- [ ] **Long-lasting** - Is this design free of trend-dependent choices (gradients, micro-styles) that will age in 12 months?
+- [ ] **Thorough** - Have edge cases been considered and handled (empty states, error states, loading states, overflow text)?
+- [ ] **Environmentally friendly** - Is the performance footprint minimal? (image sizes, JS bundle, font weight)
+- [ ] **As little design as possible** - If you removed 20% of the design decisions, would the product be worse? If not, remove them.
 
 ---
 
-## Sonner / Component-Authoring Lens — 6 Questions
+## Sonner / Component-Authoring Lens - 6 Questions
 
 Emil Kowalski's component-authoring principles applied as a per-component self-audit. Full reference: `reference/component-authoring.md`.
 
-- [ ] **P-01 API surface** — Does this component work correctly in 1 line with zero configuration?
-- [ ] **P-02 Composability** — Does this component compose via slots/children, not via style-configuration props?
-- [ ] **P-03 Defaults** — Are the defaults so sensible that most consumers never need to pass any props?
-- [ ] **P-04 Animation** — Does every animation in this component communicate a state change? No decorative loops?
-- [ ] **P-05 Accessibility** — Does this component have a complete ARIA contract before any visual styling?
-- [ ] **P-06 Edge honesty** — Are known failure modes documented with `// KNOWN:` or `// EDGE:` comments?
+- [ ] **P-01 API surface** - Does this component work correctly in 1 line with zero configuration?
+- [ ] **P-02 Composability** - Does this component compose via slots/children, not via style-configuration props?
+- [ ] **P-03 Defaults** - Are the defaults so sensible that most consumers never need to pass any props?
+- [ ] **P-04 Animation** - Does every animation in this component communicate a state change? No decorative loops?
+- [ ] **P-05 Accessibility** - Does this component have a complete ARIA contract before any visual styling?
+- [ ] **P-06 Edge honesty** - Are known failure modes documented with `// KNOWN:` or `// EDGE:` comments?

package/reference/cli-localization.md

@@ -1,20 +1,20 @@
-# CLI Localization — GDD's Own Surface
+# CLI Localization - GDD's Own Surface
 
 Phase 40.5 contract. `reference/i18n.md` covers internationalizing *user designs*; this file covers
-**GDD's own CLI** — `--help`, the common error messages, and skill prompt headers. The goal is the
+**GDD's own CLI** - `--help`, the common error messages, and skill prompt headers. The goal is the
 lowest-effort, highest-impact subset; full skill-body translation is deferred (per-locale demand).
 
 ## Resolution
 
 `scripts/lib/i18n/index.cjs` resolves the active locale with this precedence:
 
-1. **`.design/config.json#locale`** — an explicit per-project override (set via `/gdd:locale <code>`).
-2. **`process.env`** — `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (normalized: `ru_RU.UTF-8` → `ru`).
-3. **`en`** — the default.
+1. **`.design/config.json#locale`** - an explicit per-project override (set via `/gdd:locale <code>`).
+2. **`process.env`** - `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (normalized: `ru_RU.UTF-8` → `ru`).
+3. **`en`** - the default.
 
 A `C` / `POSIX` env locale resolves to `en`. The resolved code then drives a **fallback chain**
 `locale → base → en` (e.g. `de-DE → de → en`), so a regional locale degrades to its base and finally
-to English — the complete source table.
+to English - the complete source table.
 
 ## Message tables
 
@@ -23,9 +23,9 @@ simplicity). Each is `{ "_meta": { locale, coverage, fallback }, "<key>": "<stri
 namespaced: `help.*` (usage + section headers), `error.*` (the common CLI errors), `prompt.*` (skill
 prompt headers), `status.*`.
 
-- **`en.json`** — the **complete source of truth**; every key lives here.
-- **`ru.json`** — a complete second-locale translation (covers every `en` key).
-- **`uk.json` / `de.json` / `fr.json` / `zh.json` / `ja.json`** — **placeholders**: a `_meta` marker
+- **`en.json`** - the **complete source of truth**; every key lives here.
+- **`ru.json`** - a complete second-locale translation (covers every `en` key).
+- **`uk.json` / `de.json` / `fr.json` / `zh.json` / `ja.json`** - **placeholders**: a `_meta` marker
   (`coverage: "placeholder"`) plus a starter subset. Any missing key falls back to `en` per the chain.
 
 `translate(tables, key, locale)` walks the chain and returns the first hit, or the key itself if no
@@ -35,7 +35,7 @@ table has it (a missing key is always visible, never a crash).
 
 Skills and agents may carry an **opt-in** `description_i18n: { <locale>: "<description>" }` map.
 `descriptionFor(frontmatter, locale)` returns the localized description via the fallback chain, or the
-plain English `description` when the locale is absent. The field is fully backward-compatible — a
+plain English `description` when the locale is absent. The field is fully backward-compatible - a
 skill/agent without it is unaffected, and the Phase 28.5 contract only validates it (as an object of
 locale→string) when present.
 
@@ -43,12 +43,12 @@ locale→string) when present.
 
 The completeness gate is **warn-only**. Only `en` (source) and `ru` (full) are expected to be 100%; the
 five placeholder locales are intentionally partial and rely on the English fallback. A locale is never
-required to be complete to ship — partial is better than English-only, and fallback guarantees no key
+required to be complete to ship - partial is better than English-only, and fallback guarantees no key
 is ever missing at runtime.
 
 ## Adding or completing a locale (contribution path)
 
-1. Edit `scripts/lib/i18n/messages/<locale>.json` — add the keys you can translate (any `en` key is
+1. Edit `scripts/lib/i18n/messages/<locale>.json` - add the keys you can translate (any `en` key is
    fair game; you do not need 100%).
 2. Set `_meta.coverage` to `"complete"` once every `en` key is present, else leave `"placeholder"`.
 3. Add a translator-credit line to `NOTICE` under the attributions section (name/handle + locale).
@@ -56,6 +56,6 @@ is ever missing at runtime.
 
 ## Boundaries
 
-`--help` + common errors + skill prompt headers only — not full skill bodies (deferred per demand),
+`--help` + common errors + skill prompt headers only - not full skill bodies (deferred per demand),
 not RTL terminal rendering (a terminal concern), not voice/conversational localization. English is
 always the final fallback, so the CLI is never broken by a partial translation.

package/reference/codex-tools.md

@@ -3,7 +3,7 @@
 Last verified: 2026-04-24
 
 When a GDD skill references a Claude Code tool name, the Codex runtime
-translates to the equivalent below. Skills do NOT need to branch — the tool
+translates to the equivalent below. Skills do NOT need to branch - the tool
 name in prose is authoritative; Codex resolves via this map.
 
 ## Tool-name mapping
@@ -49,5 +49,5 @@ All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Codex.
 
 ---
 
-Last verified: 2026-04-24 — tool surface re-checked against Codex CLI docs
+Last verified: 2026-04-24 - tool surface re-checked against Codex CLI docs
 current to this date. Revisit whenever Codex ships a tool-vocabulary change.

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