@hegemonart/get-design-done 1.27.7 → 1.28.5

package/reference/architecture-vocabulary.md

@@ -0,0 +1,102 @@
+---
+name: architecture-vocabulary
+type: principles
+version: 1.0.0
+phase: 28.5
+tags: [architecture, ousterhout, module, interface, depth, seam, adapter, leverage, locality]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) via Ousterhout, *A Philosophy of Software Design* — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Architecture Vocabulary
+
+A shared vocabulary for architectural reasoning across GDD skills. Same words mean the same things across `zoom-out`, `debug`, `analyze-dependencies`, `map`, `quality-gate`, and the planning skills — so agents and humans do not re-litigate "what did you mean by *module*" every conversation. Drawn from John Ousterhout's *A Philosophy of Software Design* via mattpocock's `improve-codebase-architecture/LANGUAGE.md`. GDD design-engineering analogs are surfaced where applicable — a UI component is a module, a design-token API is an interface, a token theme is an adapter.
+
+This file is the canonical reference; skills cite it instead of re-defining terms inline.
+
+## Module
+
+A unit of code that hides implementation behind an interface. The module's value to its caller is everything inside that the caller no longer has to think about.
+
+- A React component is a module — props are the interface, internal state and effects are the implementation.
+- A skill is a module — frontmatter + workflow are the interface, the SKILL.md body is the implementation.
+- See `./design-system-guidance.md` for the design-system-level analog: a component is a module; the token contract is its interface.
+
+## Interface
+
+What a module exposes to callers — function signatures, props, return types, error contracts, side-effect promises. The interface is what callers depend on; everything else they must NOT depend on. Small, stable interfaces are the goal.
+
+- `function fetchUser(id: string): Promise<User>` is the interface. How `fetchUser` calls the database is implementation.
+- A React component's `props` plus its rendered DOM contract is the interface; useState, useEffect, internal helpers are not.
+- See `./component-authoring.md` (6-principle quality standard, esp. "Minimal API" and "Composability") for the component-library-level analog.
+
+## Implementation
+
+What the module hides — the code that does the work. Callers must not depend on it. Implementation is free to change as long as the interface holds.
+
+- Switching `fetchUser` from REST to GraphQL without changing the call site = implementation change without interface change. Healthy.
+- Renaming a private helper inside a React component does not break callers. Healthy.
+- Exposing a class's "private" field that callers started reading turns implementation into de-facto interface. Unhealthy — fix by either formalizing the field as interface or stopping the leak.
+
+## Depth
+
+A module is **deep** when the interface is simple and the implementation hides genuine complexity. A module is **shallow** when the interface is as complex as the implementation — the wrapper adds no leverage and just shuffles the caller's mental load sideways.
+
+- `Array.sort()` is deep — one method name hides ~50 lines of comparison-sort logic plus stable-ordering guarantees.
+- `class Wrapper { getX() { return this.x; } }` is shallow — the wrapper adds no leverage; the caller has to know about `Wrapper` AND `x`.
+- Asymmetry in the caller's favor is the goal. Shallow modules cost the caller mental complexity without paying it back.
+- See `./component-authoring.md` "Minimal API" — a 1-prop `<Image src=... />` that handles preload, lazy load, srcset, blur placeholder, error fallback is the depth principle applied to component design.
+
+## Seam
+
+The boundary where two abstractions meet — where one module's interface is consumed by another. Seams are where you can replace one side without touching the other.
+
+- **Hypothetical seam.** Only one implementation exists behind the boundary. Nothing yet validates the abstraction is meaningful — the seam is a possibility statement.
+- **Real seam.** Two or more implementations exist; the boundary has been proved load-bearing by actual substitution. The seam is evidence.
+- "One adapter = hypothetical seam; two adapters = real seam." See `## Principles` below.
+- A `fetchUser` function backed only by Postgres is hypothetical; once a test double + a Postgres impl coexist, the seam is real.
+
+## Adapter
+
+A module that transforms one interface into another to enable substitution behind a seam. Adapters create seams; the count of distinct adapters approximates the seam's realism.
+
+- A Redux-to-Zustand adapter exposes Redux's `store.dispatch` while wrapping a Zustand store underneath — callers keep their Redux API; the implementation moved.
+- A design-token theme is an adapter: it transforms one token contract (`--color-bg`) into specific concrete values (`oklch(98% 0 0)` in light theme, `oklch(15% 0 0)` in dark).
+- An `acp-client` plus an `asp-client` are two adapters over the same "peer-CLI" seam — the second one proves the seam is meaningful (Phase 27).
+
+## Leverage
+
+The ratio of work-the-system-does to interface-the-caller-touches. High leverage = high depth = the caller buys a lot of work for a little API. Architectural choices that maximize leverage reduce future cost across all callers.
+
+- `<Image />` with a `src` prop that handles preload, lazy load, srcset generation, blur placeholder, error fallback — high leverage from a 1-prop API. Every caller benefits.
+- A 5-prop `<Button variant size leftIcon rightIcon onClick />` that only renders a styled `<button>` — low leverage; the caller is still doing most of the configuration work.
+- Leverage compounds. A high-leverage primitive used by 20 components multiplies the original investment 20×.
+
+## Locality
+
+Related changes happen in the same place; unrelated changes do not ripple. Spatial cohesion of the change footprint. Locality is what makes a codebase "easy to modify" — you can find the thing and change just the thing.
+
+- Healthy: adding a new chart type touches `chart-types/<new-type>.ts` only.
+- Broken: adding a new chart type touches `chart-types.ts` AND `chart-renderer.ts` AND `chart-config.ts` AND `chart-styles.css` AND `chart-icons.svg`. The system is forcing the author to remember 5 files for a 1-concept change.
+- Test it with the **deletion test** (see `## Principles`) — if removing the feature requires touching the same N files, locality is asymmetric and the abstraction is leaking.
+
+## Principles
+
+Three load-bearing rules that operationalize the vocabulary above. Each one is a question you can ask during review.
+
+- **Deletion test.** Can you delete the implementation and the interface still tells callers what they could do? If yes, the interface is well-defined and the module is properly encapsulated. If no, the interface is leaking implementation — callers are reaching past the abstraction. Apply this when reviewing a new module: imagine deleting the body; can a reader still describe the surface from the signature alone?
+- **Interface is the test surface.** Tests target the interface; implementation churn does not churn tests. If a refactor that preserves behavior breaks tests, the test was implementation-coupled — fix the test, not the refactor. This is also the diagnostic for whether you have a real interface at all: if you cannot test through it, the interface is too narrow or the implementation is leaking.
+- **One adapter = hypothetical seam; two adapters = real seam.** One substitution is a possibility statement; two substitutions are evidence the boundary is meaningful. Do not over-design seams without ≥2 implementations — the second one teaches you what the seam actually needs. This is YAGNI for boundaries: ship the first impl, extract the seam when the second one arrives.
+
+## How this applies to skill authoring
+
+Skills are modules. The frontmatter (`name`, `description`, `tags`) plus the workflow signature is the interface; the SKILL.md body is the implementation. A deep skill has a small, predictable interface (clear when to invoke, clear output shape) hiding genuine workflow value. A shallow skill is one whose body adds little beyond what the frontmatter already implies — those skills should be either deepened or deleted. The skill-authoring contract's 100-line cap is the depth principle applied to skills: if the implementation cannot fit in 100 lines, either the workflow is too broad (split it) or supporting domain content should move to `reference/*.md` (extract-then-link, D-10). See `./skill-authoring-contract.md` for the full spec.
+
+## Cross-references
+
+- Design-system-level analog — component-as-module, design-token-as-interface: see `./design-system-guidance.md`.
+- Component-library-level analog — the 6-principle quality standard (Minimal API, Composability, ...): see `./component-authoring.md`.
+- Skill-authoring application — extract-then-link, 100-line cap, refs-one-level-deep: see `./skill-authoring-contract.md`.
+- `CONTEXT.md` glossary format (project-scoped ubiquitous language alongside this vocabulary): see `./context-md-format.md`.
+- ADR format (heavier project-scoped decisions about architectural seams): see `./adr-format.md`.

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/cache-policy.md

@@ -0,0 +1,126 @@
+---
+name: cache-policy
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [cache, layer-a, layer-b, sha-256, ttl, warm-cache, cache-manager, anthropic-prompt-cache]
+last_updated: 2026-05-18
+---
+
+# Cache Policy (Layer A + Layer B)
+
+Extracted from `skills/cache-manager/SKILL.md` and `skills/warm-cache/SKILL.md` per Phase 28.5
+D-10 (extract-then-link, never delete content). The two skills keep their orchestration
+contracts and step-by-step flows; the deeper algorithmic and operational detail moves here
+so the SKILLs stay under the 100-line cap.
+
+The two layers (D-08):
+
+- **Layer A** — Anthropic's 5-min prompt cache (owned by `warm-cache`). Keyed on shared-preamble-first prompt prefix. No project-local state.
+- **Layer B** — explicit `.design/cache-manifest.json` (owned by `gdd-cache-manager`). Keyed on deterministic SHA-256 of `(agent-path, sorted-input-file-paths, input-content-hashes)`. Per-repo state.
+
+## Deterministic Input-Hash Algorithm (Layer B)
+
+The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.js` imports the same primitive via a shared helper):
+
+```js
+// Deterministic cache-key primitive (reference implementation)
+// hash = SHA-256(
+//   agent_path + "\n" +
+//   sorted(input_file_paths).join("\n") + "\n" +
+//   sorted(input_file_paths)
+//     .map(p => sha256(readFileSync(p, "utf8")))
+//     .join("\n")
+// )
+const crypto = require('crypto');
+const fs = require('fs');
+
+function sha256Hex(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+function computeInputHash(agentPath, inputFilePaths) {
+  const sortedPaths = [...inputFilePaths].sort();
+  const contentHashes = sortedPaths.map(p => {
+    try { return sha256Hex(fs.readFileSync(p, 'utf8')); }
+    catch { return 'MISSING'; }
+  });
+  const canonical = [
+    agentPath,
+    sortedPaths.join('\n'),
+    contentHashes.join('\n')
+  ].join('\n');
+  return sha256Hex(canonical);
+}
+```
+
+Notes for maintainers:
+
+- **Sorted-unique paths** — ordering must be stable; caller is expected to de-duplicate. If the same path appears twice the hash still matches as long as caller pre-dedupes before invoking.
+- **Missing file** — the string `MISSING` is used in place of the content hash so a missing dependency doesn't silently collide with an empty file (empty file's SHA-256 is `e3b0c44...`). Missing-file hashes naturally miss on the next read because the real file has a different content hash.
+- **Agent-path** — agents changing their own body (role, tools, output contract) invalidate all their cache entries automatically because the agent file's content is not hashed; but the `agent_path` string is concatenated. Upgrading agents between versions naturally busts the cache only when the path changes. Plan 10.1-04 (shared preamble extraction) is expected to slightly adjust agent bodies — consumers should treat the first post-10.1 run as a full cache miss, which is the intended behavior.
+
+## Manifest Shape (Layer B)
+
+See `./config-schema.md` §.design/cache-manifest.json Schema (Phase 10.1) for the authoritative schema. Keyed object, flat SHA-256 hex keys. Example:
+
+```json
+{
+  "a3f1e...": {
+    "agent": "design-verifier",
+    "result": "<base64-or-path>",
+    "written_at": "2026-04-18T12:00:00Z",
+    "ttl_seconds": 3600,
+    "expires_at": "2026-04-18T13:00:00Z"
+  }
+}
+```
+
+## TTL Semantics (Layer B)
+
+- Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10.
+- `expires_at` is computed at write time and stored; readers do not recompute.
+- Lazy cleanup: stale entries are not actively deleted on read (overhead for no benefit in normal operation). A separate reaper is optional and out of v1 scope.
+
+## Concrete Warm-Cache Command Examples (Layer A)
+
+Full invocation:
+
+```
+$ /gdd:warm-cache
+
+Warming Anthropic prompt cache for 14 agents (5 min TTL)...
+[1/14] design-verifier ... ok (0.3s)
+[2/14] design-planner ... ok (0.3s)
+[3/14] design-integration-checker ... ok (0.3s)
+...
+[14/14] design-reflector ... ok (0.3s)
+
+## Warm-cache complete
+- Agents warmed: 14
+- Skipped (no shared preamble import): 3  (agents/README.md not an agent; 2 agents not yet migrated to shared preamble)
+- Duration: 4.2s
+- Next 5 min: repeated spawns of these agents pay cached_input_per_1m rate
+```
+
+Filtered invocation:
+
+```
+$ /gdd:warm-cache --agents design-verifier,design-planner
+
+Warming Anthropic prompt cache for 2 agents (filtered from 14)...
+[1/2] design-verifier ... ok (0.3s)
+[2/2] design-planner ... ok (0.3s)
+
+## Warm-cache complete
+- Agents warmed: 2
+- Filtered out by --agents: 12
+- Duration: 0.7s
+```
+
+## Cost Model (Layer A)
+
+- Each no-op Haiku ping: ~50 input tokens (shared preamble + "No-op warm: acknowledge..." system+user) + ~5 output tokens ("ok").
+- At Haiku rates (`./model-prices.md`): `(50 / 1e6) * 1.00 + (5 / 1e6) * 5.00 = $0.00005 + $0.000025 = $0.000075` per agent.
+- 14 agents × $0.000075 = **$0.00105** total for a full warm-cache invocation.
+- Payback: a single subsequent Opus spawn with 40k cached input tokens saves `(40000/1e6) * (15.00 - 1.50) = $0.54`. Warm-cache pays for itself ~500× over on the first repeated planner spawn.

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.