@hegemonart/get-design-done 1.27.7 → 1.28.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.27.7"
+    "version": "1.28.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.27.7",
+      "version": "1.28.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.27.7",
-  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming.",
+  "version": "1.28.0",
+  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"

package/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.28.0] — 2026-05-18
+
+### Phase 28 — Foundational References Tier 2 — Color, Composition, Proportion, i18n
+
+Closes 4 foundational-fundamentals gaps + 1 contrast layer surfaced by the 2026-05-01 huashu-design comparison audit + parallel i18n-coverage audit. Pure content + light agent wiring; no architectural change, no new pillar, no breaking consumer contract.
+
+#### New reference files (Wave A + B)
+
+- `reference/color-theory.md` (28-01) — color spaces (sRGB / HSL / OKLCH / LCH), 6 harmonies in OKLCH, simultaneous contrast, color-blindness palettes, color interpolation in animation (closes the sRGB muddy-mid-transition problem).
+- `reference/composition.md` (28-02) — rule of thirds, phi / sqrt(2) / sqrt(3) / sqrt(5) root rectangles, Fibonacci, focal-point construction, visual-weight calculus (size x contrast x isolation x complexity), optical-vs-mathematical centering, Z/F/Gutenberg eye-flow patterns.
+- `reference/proportion-systems.md` (28-03) — 4pt / 8pt / sqrt(2) baseline grids, baseline-grid lock, vertical rhythm, modular relationships across type + spacing + sizing + radius.
+- `reference/i18n.md` (28-04) — text expansion per locale, CSS logical properties, RTL mirroring + directional-icon flip catalog, bidi isolation, full `Intl.*` family (DateTimeFormat / NumberFormat / PluralRules / RelativeTimeFormat / ListFormat / Collator / Segmenter), ICU MessageFormat, Unicode hygiene, multi-script font stacks, WCAG i18n; spec source for design-verifier + explore probes.
+- `reference/contrast-advanced.md` (28-05) — APCA (WCAG 3 draft) Lc 75/60/45/30 thresholds, why 4.5:1 misranks thin/large/colored text (3 worked examples), dual-target pattern with WCAG 2.1 AA, Lc-to-WCAG conversion table. **Ships at v1.28.0 (D-02 — not deferred).**
+
+#### Consumer integration (Wave C — 28-06)
+
+- `agents/design-verifier.md` gains `### i18n probes` subsection with 2 probes: hardcoded-string scan (regex catalog matches react-intl / next-intl / i18next / vue-i18n patterns per D-10) + +40% text-overflow simulation (`scrollWidth > clientWidth` check per D-03). Findings tagged `i18n_readiness` (orthogonal lens, NOT a new pillar).
+- `skills/explore/SKILL.md` gains i18n-readiness probe under Step 2 — informational 3-state classification (`framework-managed` / `partial` / `none`) per D-04 + D-11. NO gate, NO blocking.
+- `reference/registry.json` gains 5 new entries (D-05) — round-trip schema enforced.
+- `reference/audit-scoring.md` gains 2 orthogonal lens-tags (D-07) — `composition_alignment` + `i18n_readiness`. NO new pillar, NO weight change.
+- 12 additive cross-link insertions across 10 existing reference files (D-06): `palette-catalog.md` Step 4 -> `color-theory.md`; `motion-interpolate.md` -> `color-theory.md`; `visual-hierarchy-layout.md` (Compositional Grids + Asymmetry) -> `composition.md`; `design-system-guidance.md` -> `proportion-systems.md`; `typography.md` (Type Scale Systems + Variable Fonts) -> `proportion-systems.md` + `i18n.md`; `rtl-cjk-cultural.md` (top-of-file) -> `i18n.md`; `form-patterns.md` -> `i18n.md`; `accessibility.md` (x2) -> `i18n.md` + `contrast-advanced.md`; `iconography.md` -> `composition.md`; `style-vocabulary.md` -> `proportion-systems.md`.
+
+#### Decisions locked
+
+- D-01 (rejection): No net-new audit pillar — orthogonal lens-tags only on existing pillars.
+- D-02: `contrast-advanced.md` ships at v1.28.0 (not deferred).
+- D-03: Verifier overflow probe uses `scrollWidth > clientWidth` after +40% text expansion (cheap synchronous DOM check, no headless-browser dependency).
+- D-04: Explore i18n probe is informational only — 3-state output (`framework-managed` / `partial` / `none`), no gate, no blocking.
+- D-05: 5 new `reference/registry.json` entries with phase=28.
+- D-06: All 12 cross-link insertions are additive (no removals, no rewordings of existing content).
+- D-07: 2 audit-scoring lens-tags (`composition_alignment` + `i18n_readiness`) — orthogonal to existing pillars, not new pillars.
+- D-08: 4-manifest lockstep at 1.28.0 — `package.json#version`, `.claude-plugin/plugin.json#version`, `.claude-plugin/marketplace.json#metadata.version`, `.claude-plugin/marketplace.json#plugins[0].version` all align. `OFF_CADENCE_VERSIONS.add('1.28.0')` added to `tests/semver-compare.test.cjs`.
+- D-09: Phase 20 baselines unchanged (no new agents/skills/hooks introduced in Phase 28).
+- D-10: Hardcoded-string scan covers react-intl / next-intl / i18next / vue-i18n call-site patterns; false-positive tightening is reflector carry-forward debt.
+- D-11: Explore probe is single-shot per run (no caching, no telemetry pinning).
+- D-12: ROADMAP scoped flip — 7 inline plan checkboxes (28-01..28-07) + 1 top-level overview entry. STRICTLY bounded to Phase 28; other phases' `[ ]` markers untouched.
+
+#### Tests added
+
+- `tests/phase-28-probes.test.cjs` — 21 tests (28-06): verifier i18n probes, explore i18n-readiness probe, 5 registry entries, cross-link integrity across 12 insertions, audit-scoring lens-tags.
+- `tests/phase-28-baseline.test.cjs` — 8 tests (28-07): 4-manifest alignment, baseline file presence, reference file presence, registry round-trip, cross-link integrity, verifier + explore probe markers, CHANGELOG block at top, OFF_CADENCE recognition. Version-agnostic (reads `package.json#version` dynamically — D-08 lesson).
+- `test-fixture/baselines/phase-28/` — 6 baseline text files: `reference-files-presence.txt`, `registry-diff.txt`, `cross-link-integrity.txt`, `verifier-probes-presence.txt`, `explore-probe-presence.txt`, `manifests-version.txt`.
+
+#### Out of scope (deferred or rejected)
+
+- 20 designer-school philosophies catalog (huashu-design license unresolved).
+- Brand asset acquisition protocol (5-10-2-8 curation rule — separate phase).
+- Color-management profiles (Display-P3 / Rec.2020 / BT.2100 — video/print only).
+- Generative color systems (Material You algorithm — already in `style-vocabulary.md`).
+- Net-new audit pillar (lens-tags instead, per D-07).
+- Translation-management workflows (Crowdin / Lokalise / Phrase — ops concern).
+- Locale-pack bundling / lazy-loading (production tuning concern).
+- Pseudolocalization tooling (+40% overflow at verifier layer covers same QA goal).
+- RTL typography subtleties beyond mirroring (Arabic kashida, vertical CJK — `rtl-cjk-cultural.md` already touches).
+
+#### Carry-forward debt
+
+- Verifier hardcoded-string scan false-positive rate (D-10) — reflector measures over first N runs; tightens regex per Phase 11 self-improvement loop.
+- APCA spec ratification — currently WCAG 3 draft; if it advances to candidate-recommendation, `contrast-advanced.md` becomes more authoritative.
+- ICU MessageFormat 2.0 status — currently Stage 3 / draft at TC39; if it lands, `i18n.md` ICU section may add 2.0 examples in a follow-up.
+- `Intl.Segmenter` browser-support drift — Safari shipped late; polyfill/fallback note may need adding to `i18n.md` Unicode Hygiene section.
+
+---
+
 ## [1.27.7] — 2026-05-18
 
 ### Added

package/agents/design-verifier.md

@@ -161,6 +161,23 @@ Before → After
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+### i18n probes
+
+Two additive probes (Phase 28, D-03 — orthogonal `i18n_readiness` lens-tag, NOT a new pillar). Full spec: `./reference/i18n.md` §Verifier Integration Spec; severity rules: `./reference/audit-scoring.md` §Lens-Tags.
+
+**Probe 1 — Hardcoded-string scan.** Regex catalog (D-10 patterns):
+
+```txt
+react-intl:  <FormattedMessage\s+id="[^"]+"
+next-intl:   \bt\(\s*['"][a-zA-Z][\w.]*['"]
+i18next:     \bt\(\s*['"][a-zA-Z][\w.]*['"]\s*,\s*\{
+vue-i18n:    \$t\(\s*['"][a-zA-Z][\w.]*['"]
+```
+
+Allow-list seed (skip): `console\.(log|error|warn|info|debug)`, dev-only `/* */` comments, `data-testid=`, `className=`, `import … from` paths. Severity: `MINOR` per file; `MAJOR` if violating files > 10. Output: `i18n_readiness: <N> hardcoded strings in <M> files`.
+
+**Probe 2 — +40% text-overflow simulation.** Worst-case LTR expansion (RU/FI/PL family — `./reference/i18n.md` §Text Expansion). Per text node `T`: pad `T.textContent` to `length × 1.4`, measure `T.parentElement.scrollWidth > clientWidth`, restore original. Prefer Preview MCP screenshot-diff when available; fall back to in-process DOM measurement headless. Severity `MINOR` per finding; `MAJOR` if overflowing components > 10. Output: `i18n_readiness: <N> components overflow at +40% expansion`.
+
 ---
 
 ## Phase 2 — Must-Have Check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.27.7",
+  "version": "1.28.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/accessibility.md

@@ -25,6 +25,8 @@ Common pitfalls:
 
 Tools: Use browser DevTools > Accessibility tab, or pass hex values through contrast calculation.
 
+**See also:** [`./contrast-advanced.md`](./contrast-advanced.md) — APCA (WCAG 3 draft) for perceptual contrast when WCAG 2.1 4.5:1 misranks thin/large/colored text. Recommended dual-target pattern: enforce WCAG 2.1 AA as a floor + APCA Lc-thresholds (75 / 60 / 45 / 30) for perceptual accuracy.
+
 ### Touch Target Size
 
 | Platform | Minimum tap target |
@@ -75,6 +77,8 @@ Recommended focus ring: **3px solid**, `2px offset`, brand primary or `#2563eb`.
 - Images have descriptive `alt=""` for meaningful images; `alt=""` for decorative.
 - Icon-only buttons have `aria-label`: `<button aria-label="Close dialog">×</button>`.
 
+**See:** [`./i18n.md`](./i18n.md) §WCAG i18n for SC 3.1.1 (`<html lang>`) and SC 3.1.2 (`<span lang="…">` language-of-parts) patterns — screen readers select voice/pronunciation packs from these attributes; a missing or wrong `lang` value forces the user to hear French announced in an English accent.
+
 ### Color Must Not Be The Only Differentiator
 
 Error states: red color + error icon + text message (not just red border).

package/reference/audit-scoring.md

@@ -234,3 +234,17 @@ Check for (see `reference/checklists.md` Micro-Polish Check gate):
 - No `transition: all` (BAN-12)
 - No `will-change: all` (BAN-13)
 - `prefers-reduced-motion` respected
+
+---
+
+## Lens-Tags (Orthogonal)
+
+Tags auditors attach to findings under existing pillars to record cross-cutting dimensions without changing the pillar structure or weights. Same orthogonal pattern as Phase 19.6 `emotion_levels` and `authoring_principles`. Adding a lens-tag does NOT change pillar weights, scoring math, or audit output format — it is a label on an existing finding.
+
+### `composition_alignment`
+
+Attach to findings under the Visual Hierarchy pillar that relate to compositional fundamentals (rule of thirds, golden ratio, root rectangles, focal-point construction, visual-weight calculus, optical-vs-mathematical centering, eye-flow patterns). See [`./composition.md`](./composition.md) for the rubric. Does NOT change the pillar weight or score; it is an orthogonal tag on the existing finding.
+
+### `i18n_readiness`
+
+Attach to findings under the Accessibility pillar (for WCAG 3.1.1 / 3.1.2 violations) or under the Anti-Pattern Compliance pillar (for hardcoded-string / overflow-at-+40% defects). Emitted by the `agents/design-verifier.md` §i18n probes section (Phase 28-06). See [`./i18n.md`](./i18n.md) §WCAG i18n + §Verifier Integration Spec. Does NOT change pillar weights or scores.

package/reference/color-theory.md

@@ -0,0 +1,279 @@
+---
+name: color-theory
+type: palette
+version: 1.0.0
+phase: 28
+tags: [color, oklch, harmonies, accessibility, motion]
+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.
+
+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 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.
+
+### 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.
+
+### OKLCH
+
+OKLCH is the modern authoring default: three channels (`L` 0–1 perceptual lightness, `C` 0–~0.4 chroma, `h` 0–360°), built on the Oklab perceptual color space (Ottosson, 2020). Three properties make it the right choice for design tokens:
+
+1. **Perceptual uniformity in L.** `oklch(0.6 0 0)` and `oklch(0.6 0.2 240)` have the same perceived lightness, regardless of hue. "Hold lightness constant while shifting hue" finally means what it says.
+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.
+
+### 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.
+
+### 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:
+
+```css
+/* The same color, four spaces. Author in OKLCH; output sRGB for fallback. */
+.primary-srgb { color: rgb(26 86 219); }                 /* device coordinates */
+.primary-hsl  { color: hsl(222 81% 48%); }               /* hue/sat/light, non-perceptual L */
+.primary-oklch { color: oklch(0.488 0.215 263.5); }      /* perceptual L, predictable C and h */
+.primary-lch  { color: lch(38 71 290); }                 /* legacy perceptual, blue-rotation kink */
+```
+
+```css
+/* Token-system pattern — author OKLCH, ship sRGB fallback in the same declaration. */
+:root {
+  --color-primary: #1A56DB;                              /* sRGB fallback */
+  --color-primary: oklch(0.488 0.215 263.5);             /* OKLCH wins where supported */
+}
+```
+
+---
+
+## 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.
+
+### Complementary
+
+Two hues separated by 180°. Maximum hue contrast, used for accent pairs and dual-action layouts.
+
+Formula: `h + 180°`, hold `L` and `C` constant.
+
+```css
+/* Base from FinTech row of ./palette-catalog.md (primary navy + complementary amber accent). */
+:root {
+  --primary:        oklch(0.488 0.215 263.5);   /* navy */
+  --complementary:  oklch(0.488 0.215 83.5);    /* amber, +180° */
+}
+```
+
+### Analogous
+
+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.
+
+```css
+/* Base from Healthcare row of ./palette-catalog.md (clinical green + neighbors). */
+:root {
+  --analog-a: oklch(0.65 0.15 132);   /* yellow-green */
+  --analog-b: oklch(0.65 0.15 162);   /* green (anchor) */
+  --analog-c: oklch(0.65 0.15 192);   /* teal */
+}
+```
+
+### Triadic
+
+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.
+
+```css
+/* Base anchored on the SaaS/B2B row periwinkle of ./palette-catalog.md. */
+:root {
+  --triad-a: oklch(0.6 0.18 280);     /* periwinkle */
+  --triad-b: oklch(0.6 0.18 40);      /* warm coral, +120° */
+  --triad-c: oklch(0.6 0.18 160);     /* fresh green, +240° */
+}
+```
+
+### Split-complement
+
+A base hue plus the two hues flanking its complement (180° ± 30°). Retains complementary tension without the dual-action visual collision; the workhorse harmony for dashboards and content-heavy product surfaces.
+
+Formula: `[h, h + 150°, h + 210°]`, hold `L` and `C` constant.
+
+```css
+/* Base from the Developer Tools row of ./palette-catalog.md (near-black + warm pair). */
+:root {
+  --split-base: oklch(0.6 0.16 260);  /* cool blue */
+  --split-a:    oklch(0.6 0.16 50);   /* warm amber,  base + 150° */
+  --split-b:    oklch(0.6 0.16 110);  /* lime green, base + 210° */
+}
+```
+
+### 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.
+
+Formula: `[h, h + 60°, h + 180°, h + 240°]`, hold `L` and `C` constant.
+
+```css
+/* Base anchored on the Gaming/Entertainment row of ./palette-catalog.md (violet primary). */
+:root {
+  --tetra-a: oklch(0.55 0.2 300);     /* violet (dominant) */
+  --tetra-b: oklch(0.55 0.12 0);      /* red-magenta, +60° (accent, reduced chroma) */
+  --tetra-c: oklch(0.55 0.12 120);    /* green, +180° (accent) */
+  --tetra-d: oklch(0.55 0.12 180);    /* teal, +240° (accent) */
+}
+```
+
+### Monochromatic
+
+One hue, varied only in `L` and/or `C`. Reads as a single material expressed across light and dark surfaces. The natural pattern for elevation systems and dense data displays.
+
+Formula: hold `h` constant; vary `L` across `0.95 → 0.15` for a 9-step scale; optionally taper `C` near the L extremes (high `C` collapses to neutral as `L → 1` or `L → 0`).
+
+```css
+/* Base from the Luxury/Fashion row of ./palette-catalog.md (near-black scale). */
+:root {
+  --mono-50:  oklch(0.97 0.005 270);
+  --mono-200: oklch(0.88 0.02  270);
+  --mono-400: oklch(0.7  0.04  270);
+  --mono-600: oklch(0.5  0.06  270);
+  --mono-800: oklch(0.3  0.05  270);
+  --mono-950: oklch(0.15 0.02  270);
+}
+```
+
+### When to use which
+
+- **Single brand voice, calm:** monochromatic or analogous.
+- **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.
+- **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.
+
+```css
+/* Same foreground token, two surrounds. The same token reads as a different color. */
+.fg-on-light {
+  background: oklch(0.97 0.01 270);                 /* near-white surround */
+  color:      oklch(0.6  0.15 30);                  /* warm coral — appears darker and richer */
+}
+.fg-on-dark {
+  background: oklch(0.18 0.02 270);                 /* near-black surround */
+  color:      oklch(0.6  0.15 30);                  /* same OKLCH — appears lighter and more luminous */
+}
+```
+
+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-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.
+- **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.
+
+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).
+
+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. */
+:root {
+  --cb-blue:    oklch(0.55 0.13 240);   /* Wong "blue"           — #0072B2 */
+  --cb-orange:  oklch(0.74 0.15  60);   /* Wong "orange"         — #E69F00 */
+  --cb-green:   oklch(0.58 0.13 160);   /* Wong "bluish green"   — #009E73 */
+}
+```
+
+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.
+
+```css
+/* BAD — default interpolation space is sRGB. Red → green midpoint is muddy gray. */
+.bad {
+  background: red;
+  transition: background-color 600ms ease;
+}
+.bad:hover { background: green; }
+```
+
+```css
+/* GOOD — explicit OKLCH interpolation. Red → green midpoint stays chromatic. */
+.good {
+  background: oklch(0.6 0.22 25);                   /* red in OKLCH */
+  transition: background-color 600ms ease;          /* honored when --start/--end are OKLCH */
+}
+.good:hover { background: oklch(0.6 0.22 145); }    /* green in OKLCH, same L and C */
+```
+
+```css
+/* GOOD — explicit interpolation space via color-mix(in oklch, …). */
+.fade {
+  background: color-mix(in oklch, oklch(0.6 0.22 25) 50%, oklch(0.6 0.22 145));
+  /* The 50% midpoint is a clean chromatic yellow-green, not gray. */
+}
+```
+
+```css
+/* GOOD — CSS Color Module 4 explicit interpolation hint on a gradient. */
+.bar {
+  background: linear-gradient(in oklch to right, oklch(0.6 0.22 25), oklch(0.6 0.22 145));
+}
+```
+
+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.
+
+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.
+
+---
+
+## 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).
+
+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.