@hegemonart/get-design-done 1.44.0 → 1.45.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.44.0"
+    "version": "1.45.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.44.0",
+      "version": "1.45.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.44.0",
+  "version": "1.45.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",

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.45.0] - 2026-06-02
+
+### Phase 45 - Canonical Domain Reference Index
+
+GDD has 38+ reference docs with flat indexing - agents loaded fragments by name and missed the rest, or
+loaded all 5 motion files and wasted tokens. Phase 45 ships 7 navigation entry-points over the existing
+content (it indexes, never re-authors). Planned and executed via the GSD pipeline (parallel research +
+parallel authoring subagents). No new runtime dependency, no new egress.
+
+### Breaking changes
+
+- **Two CI gates now guard the domain indexes.** `npm run check:domain-links` fails if any cross-link in
+  the 7 entry-points points at a missing file or anchor; `npm run check:no-duplication` fails if an index
+  copies large blocks from the fragment it should only link. Contributors editing the 7
+  `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` entries must keep
+  links resolving and keep entries link-only.
+
+### Added
+
+- **7 domain-index entry-points** at `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md`,
+  each <=300 lines: a mission, a "use this when" index of the subordinate fragments, 3-5 rules-of-thumb, and
+  cross-domain see-also links. `motion.md` and `typography.md` were transformed in place; the other five are new.
+- **Registry `domain-index` kind**: `reference/registry.schema.json` gains the type; the 7 entries register
+  as `domain-index` so skills can query indexes first and drill into detail second.
+- **`scripts/check-domain-cross-links.cjs`** + **`scripts/check-no-duplication.cjs`** (maintainer-only) + the
+  two CI steps.
+- **Consumer migration**: `motion-mapper` now loads `motion.md` (the index) and drills into a fragment only
+  when classifying against it (an 89% token cut versus loading all four motion fragments up front);
+  `design-auditor` and `design-executor` lead their reference reading with the domain indexes. Token-load
+  baseline at `test/fixtures/baselines/phase-45/token-load.json`.
+
+### Notes
+
+- 6-manifest lockstep at **v1.45.0** + `OFF_CADENCE_VERSIONS.add('1.45.0')` + 37 `manifests-version.txt`
+  baselines forward-propagated 1.44.0 -> 1.45.0. Tarball golden 869 -> 874 (+5 new shipped `reference/*.md`;
+  the two CI scripts are maintainer-only, not shipped).
+- SC#9 (Phase 41 rule `references[]` migration to canonical entries) is deferred to a follow-up; the rule
+  links to `anti-patterns.md` still resolve, so the migration is a nice-to-have rather than a blocker.
+
+---
+
 ## [1.44.0] - 2026-06-02
 
 ### Phase 44 - Harness Capability Matrix

package/README.md

@@ -249,6 +249,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Harness capability matrix (v1.44.0).** The full per-harness support matrix (skill discovery, command syntax, MCP, install path, status) lives in **[`HARNESSES.md`](HARNESSES.md)** at the repo root, generated from `scripts/lib/manifest/harnesses.json` (the single source of truth; CI drift-gates it). Each harness carries an honest status (`tested` / `experimental` / `untested`) and a `last_verified` stamp; a freshness gate warns at 60 days and fails at 180 for `tested` harnesses, surfaced in `/gdd:health`. The 14-harness count above is the same SoT the matrix reads, so it cannot drift. The five deep-dive reference files (`reference/codex-tools.md`, `reference/gemini-tools.md`, `reference/peer-cli-capabilities.md`, `reference/peer-protocols.md`, `reference/runtime-models.md`) remain as appendices linked from the matrix. **No new runtime dependency.**
 
+**Domain reference index (v1.45.0).** The 38+ reference docs are now navigated through 7 canonical entry-points - `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` - each indexing its subordinate fragments with a "use this when" pointer plus a handful of rules-of-thumb. Design skills load the relevant domain index first and drill into a fragment only when needed (motion-mapper dropped roughly 89% of its up-front reference tokens this way). The indexes link, never copy: `check:domain-links` fails CI on a broken cross-link and `check:no-duplication` fails on large copy-paste. The detailed fragments stay in place as the drill-in targets. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/agents/design-auditor.md

@@ -45,6 +45,7 @@ Minimum expected files:
 - `.design/DESIGN-CONTEXT.md` - goals, brand direction, design decisions (D-XX)
 - `.design/DESIGN-PLAN.md` - planned tasks and acceptance criteria
 - `.design/tasks/` - what was actually done (glob all task files)
+- **Domain-index navigation (Phase 45):** the 7 entry-points `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` index every fragment below. For a pillar, load the relevant domain index first, then drill into the specific fragments it lists only as the pillar needs them - this is the cheap navigation layer over the detailed fragments.
 - `reference/audit-scoring.md` - existing 7-category scoring rubric (understand, do not duplicate)
 - `reference/brand-voice.md` - voice axes, archetype library, and tone-by-context table (use when auditing Pillar 1: Copy)
 - `reference/gestalt.md` - 8 Gestalt principles with scoring rubrics (use when auditing Pillar 2: Visual Hierarchy)

package/agents/design-executor.md

@@ -34,7 +34,7 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt. Rea
 - `.design/STATE.md` - pipeline state (decisions, blockers, must-haves)
 - `.design/DESIGN-PLAN.md` - full task list (your task is identified by task_id)
 - `.design/DESIGN-CONTEXT.md` - brand decisions, constraints, locked choices
-- The reference file(s) relevant to the task type (e.g., `reference/typography.md` for a typography task)
+- The reference file(s) relevant to the task type (e.g., `reference/typography.md` for a typography task). The 7 domain-index entry-points `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` (Phase 45) are the navigation start: load the index, drill into the fragments it lists only as the task needs them.
 
 **Invariant:** read all listed files FIRST, before making any changes.
 

package/agents/motion-mapper.md

@@ -24,11 +24,15 @@ You inventory motion and animation patterns. Zero session memory. You do not mod
 ## Required Reading
 
 - `.design/STATE.md`
-- `reference/motion.md` (if present)
-- `reference/motion-advanced.md` (if present) - advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
-- `reference/motion-easings.md` (if present) - 12 canonical easing presets; classify each detected easing against this catalog
-- `reference/motion-transition-taxonomy.md` (if present) - 8 transition families; classify page/route transitions against this taxonomy
-- `reference/motion-spring.md` (if present) - spring presets; classify spring configs against gentle/wobbly/stiff/slow
+- `reference/motion.md` (if present) - **the motion domain-index (Phase 45): start here.** It indexes the
+  motion fragments below with a "use this when" pointer for each. Load a specific fragment ONLY when you
+  reach the classification step that needs it (drill-in), not all of them up front - this is the bulk of
+  the token saving (the index is ~1.7k tokens vs ~15k for all four fragments).
+- Drill-in fragments (load on demand, per the index in `motion.md`):
+  - `reference/motion-advanced.md` - advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
+  - `reference/motion-easings.md` - 12 canonical easing presets; classify each detected easing against this catalog
+  - `reference/motion-transition-taxonomy.md` - 8 transition families; classify page/route transitions against this taxonomy
+  - `reference/motion-spring.md` - spring presets; classify spring configs against gentle/wobbly/stiff/slow
 - Any files supplied by the orchestrator
 
 ## Scan Strategy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.44.0",
+  "version": "1.45.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",
@@ -69,6 +69,8 @@
     "build:harnesses:check": "node scripts/generate-harnesses-md.cjs --check",
     "check:harness-freshness": "node scripts/check-harness-freshness.cjs",
     "verify:harness": "node scripts/verify-harness.cjs",
+    "check:domain-links": "node scripts/check-domain-cross-links.cjs",
+    "check:no-duplication": "node scripts/check-no-duplication.cjs",
     "sync:rule-catalogue": "node scripts/sync-rule-catalogue.cjs --check",
     "validate:manifest": "node scripts/validate-manifest.cjs --check",
     "validate:schemas": "node --experimental-strip-types scripts/validate-schemas.ts",

package/reference/color.md

@@ -0,0 +1,34 @@
+# Color - Palette, Contrast, and Aesthetic Direction
+
+Color governs how palettes are constructed, how semantic color roles are assigned, how
+contrast compliance is verified, and how the aesthetic style direction is confirmed.
+Read `color-theory.md` when building a new palette from scratch. Read `palette-catalog.md`
+when adopting an industry-vertical baseline. Read `contrast-advanced.md` for APCA
+thresholds on thin or colored text. Read `style-vocabulary.md` to confirm whether an
+aesthetic style's color requirements fit the product type. Does not cover type sizing for
+legibility (see `typography.md`) or dark-mode implementation steps beyond OKLCH token
+generation (see `color-theory.md`).
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| [`./color-theory.md`](./color-theory.md) | constructing a palette, choosing a color space, building OKLCH harmonies, animating color, auditing under color-blindness simulation |
+| [`./palette-catalog.md`](./palette-catalog.md) | adopting a pre-built industry-vertical palette as a baseline token set (40+ verticals, WCAG-verified) |
+| [`./contrast-advanced.md`](./contrast-advanced.md) | computing text/UI contrast beyond WCAG 2.1 AA - especially for thin, large, or colored text where WCAG 2.1 misranks |
+| [`./style-vocabulary.md`](./style-vocabulary.md) | confirming a UI aesthetic direction: does the style require dark mode, what are its signature color effects, which product types should avoid it |
+
+## Rules of Thumb
+
+1. Author new palette tokens in OKLCH, not HSL or hex. OKLCH ΔL/ΔC/Δh steps are perceptually uniform - equal numeric jumps produce equal perceived brightness jumps. HSL's lightness channel is not perceptual.
+2. Never rely on color alone to convey state (error, warning, success). Always pair with an icon, label, or pattern - WCAG 1.4.1.
+3. For the APCA dual-target pattern: meet WCAG 2.1 AA (4.5:1 for body text) AND check Lc 60 (APCA) for thin weights and colored backgrounds. The two systems can disagree on the same pair.
+4. Check every palette under deutan (most common), protan, and tritan simulations before shipping. The color-blindness palettes in `color-theory.md` provide pre-vetted swap sets.
+
+## See Also
+
+- Typography legibility at small sizes: [`./typography.md`](./typography.md)
+- OKLCH interpolation in color animations: [`./motion.md`](./motion.md)
+- Spatial depth via shadow and elevation: [`./spatial.md`](./spatial.md)
+- Healthcare: critical-value flags not color-only: [`./domains/healthcare-patterns.md`](./domains/healthcare-patterns.md)
+- Finance: gain/loss color rules: [`./domains/finance-patterns.md`](./domains/finance-patterns.md)

package/reference/interaction.md

@@ -0,0 +1,48 @@
+# Interaction - Domain Index
+
+This domain covers how users trigger, navigate, and recover from actions: accessibility requirements, component API quality, form patterns, information architecture, onboarding, and the emotional layer.
+
+<!-- Phase 45 domain-index: loads this file instead of individual interaction fragments -->
+
+---
+
+## Mission
+
+Interaction is the broadest design domain. It governs every point where a user acts on the interface and the interface responds. Load only the specific fragment for the task at hand using the index below. Does not cover visual placement of interactive elements (see `spatial.md`) or copy for UI elements (see `ux-writing.md`).
+
+---
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| `./accessibility.md` | WCAG 2.1 AA thresholds, keyboard navigation, focus management, ARIA roles. Required for every interactive surface without exception. |
+| `./component-authoring.md` | Designing or reviewing component APIs: P-01 Minimal API through P-06 Edge Honesty, composability, defaults, animation-as-state |
+| `./form-patterns.md` | Forms are in scope: label position, validation timing, autofill tokens, password UX, CAPTCHA ethics |
+| `./information-architecture.md` | Navigation structure is in scope: hub-and-spoke, faceted nav, card sort benchmarks, wayfinding |
+| `./onboarding-progressive-disclosure.md` | First-run experience is in scope: empty-state patterns, product tours, checklist onboarding, Aha-moment mapping |
+| `./emotional-design.md` | Holistic quality overlay after pillar scoring: Norman visceral/behavioral/reflective three-level lens |
+| `./components/README.md` | Auditing a specific component against benchmark: entry to 38 spec files (accordion through tree) |
+
+---
+
+## Rules of Thumb
+
+1. Accessibility is not a final checklist - build it in from the start. Every interactive component begins with the WAI-ARIA contract from `accessibility.md`, not a retrofit after design is complete.
+2. P-01 Minimal API from `component-authoring.md`: a component's API surface is its test surface. Every prop that can be removed should be removed.
+3. Form label position: top-aligned is the default for all but settings-page scan forms. Placeholder-as-label is a WCAG 1.3.5 failure on any form with more than 3 fields.
+4. Empty-state onboarding outperforms product tours by completion rate for creation tools. Only use a tour when unfamiliar terminology requires context, and cap it at 5 steps.
+5. The emotional design lens applies after technical and usability requirements are met. Visceral quality (appearance) and behavioral quality (task flow) both need to be solid before reflective quality (brand meaning) is addressed.
+
+---
+
+## Cross-Domain See Also
+
+- Gesture animation and animation-as-state: `reference/motion.md`
+- Spatial grouping informs IA mental models: `reference/spatial.md`
+- Touch target sizing differs by platform: `reference/responsive.md`
+- Error message copy and empty-state copy: `reference/ux-writing.md`
+- Healthcare form patterns (PHI isolation): `reference/domains/healthcare-patterns.md`
+- Civic one-thing-per-page forms: `reference/domains/civic-patterns.md`
+- Typography: `reference/typography.md`
+- Color: `reference/color.md`

package/reference/motion.md

@@ -1,6 +1,27 @@
-# Motion & Animation Framework
+# Motion - Animation Domain Index
 
-Based on Emil Kowalski's design engineering philosophy. Apply these rules in order - do not skip to "how should this animate" before answering "should this animate."
+Based on Emil Kowalski's design engineering philosophy. Apply these rules in order. Do not skip to "how should this animate" before answering "should this animate."
+
+<!-- Phase 45 domain-index: loads this file instead of individual motion fragments -->
+
+---
+
+## Mission
+
+Motion governs animation decisions across the UI: whether to animate, duration budgets, easing choices, spring physics, transition taxonomy, and interpolation. Read this file first for the decision framework and core rules, then drill into the specialist fragment below. Does not cover CSS layout transitions (see `spatial.md`) or OS-level reduced-motion policy (see `responsive.md`).
+
+---
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| `./motion-easings.md` | Choosing or auditing easing curve values: 12 canonical `--ease-*` presets, cubic-bezier equivalents, 60fps settle-times |
+| `./motion-spring.md` | Interaction is draggable or needs physics feel: gentle/wobbly/stiff/slow presets, Framer Motion and React Spring syntax |
+| `./motion-transition-taxonomy.md` | Classifying page or route transitions: 8 families (3d, blur, cover, destruction, dissolve, distortion, grid, light) |
+| `./motion-interpolate.md` | Mapping input-to-output ranges: progress/scroll/gesture/time-linked animations, 4 extrapolation modes |
+| `./motion-advanced.md` | Advanced platform APIs: FLIP, scroll-driven, View Transitions, gesture/drag, clip-path, WAAPI |
+| `./framer-motion-patterns.md` | Codebase uses Framer Motion: spring/tween config, AnimatePresence, variants, gestures, a11y, bounce:0 rule |
 
 ---
 
@@ -12,7 +33,7 @@ Based on Emil Kowalski's design engineering philosophy. Apply these rules in ord
 |---|---|
 | 100+/day - keyboard shortcuts, command palette, list navigation | **No animation. Ever.** |
 | Tens/day - hover states, toggles, tab switching | Remove or keep to <80ms. No delay. |
-| Occasional - modals opening, drawers, toasts | Standard animation (150–300ms) |
+| Occasional - modals opening, drawers, toasts | Standard animation (150-300ms) |
 | Rare - onboarding, celebrations, first-time flows | Can add personality and delight |
 | Once - loading splash, page transitions | Full animation budget |
 
@@ -25,9 +46,9 @@ Valid animation purposes only. If it doesn't serve one of these, remove it.
 | Purpose | Example |
 |---|---|
 | **Spatial consistency** | Toast enters/exits same edge each time |
-| **State indication** | Button morphs to show loading → success |
+| **State indication** | Button morphs to show loading to success |
 | **Cause-effect explanation** | Item deletion - item flies to trash |
-| **Feedback** | Button scales 0.97 on press |
+| **Feedback** | Button scales on press |
 | **Prevent jarring changes** | Content appearing/disappearing needs transition |
 
 Invalid purposes: "It looks cool", "It feels modern", "Other apps do it."
@@ -42,44 +63,28 @@ Invalid purposes: "It looks cool", "It feels modern", "Other apps do it."
 | **Interactive/draggable** | Spring physics | Follows finger/cursor naturally |
 | **Bounce/elastic** | **Never** | Feels toy-like and dated |
 
-CSS:
-```css
-/* Enter */
-transition: transform 200ms cubic-bezier(0, 0, 0.2, 1); /* ease-out */
-
-/* Exit */
-transition: transform 150ms cubic-bezier(0.4, 0, 1, 1); /* ease-in */
-
-/* Transition */
-transition: all 200ms cubic-bezier(0.4, 0, 0.2, 1); /* ease-in-out */
-```
+See `reference/motion-easings.md` for the full `--ease-*` token catalog.
 
 ### Question 4: What Duration?
 
 | Animation type | Duration | Notes |
 |---|---|---|
-| Micro-interactions | 80–150ms | Hover, press, toggle |
-| Component enter/exit | 150–250ms | Modals, drawers, dropdowns |
-| Page transitions | 200–350ms | Route changes |
-| Complex/orchestrated | ≤400ms | Multi-step, staggered reveals |
+| Micro-interactions | 80-150ms | Hover, press, toggle |
+| Component enter/exit | 150-250ms | Modals, drawers, dropdowns |
+| Page transitions | 200-350ms | Route changes |
+| Complex/orchestrated | <=400ms | Multi-step, staggered reveals |
 | **Never exceed** | 400ms | Anything longer feels broken |
 
-**Exit faster than enter**: Exit animations should run at **60–70%** of the enter duration. Exiting elements should get out of the way fast.
-
-```
-Enter: 250ms
-Exit: 150ms (60% of 250)
-```
+**Exit faster than enter**: Exit animations should run at **60-70%** of the enter duration.
 
 ### Question 5: Only Animate `transform` and `opacity`
 
-**Only these properties animate on the GPU:**
 ```css
-/* SAFE */
+/* SAFE - GPU-accelerated */
 transform: translateX(), translateY(), scale(), rotate()
-opacity: 0 → 1
+opacity: 0 to 1
 
-/* DANGEROUS — triggers layout/paint */
+/* DANGEROUS - triggers layout/paint */
 width, height, top, left, margin, padding, font-size
 ```
 
@@ -89,319 +94,73 @@ Exception: `filter` (blur) is GPU-accelerated in modern browsers but battery-exp
 
 ## Stagger Rules
 
-When animating a list of items entering:
-- Stagger delay: **30–50ms** per item
-- Maximum stagger depth: **6–8 items** (items beyond that appear simultaneously)
-- Direction: top-to-bottom OR left-to-right - never random
-
-```css
-.item:nth-child(1) { animation-delay: 0ms; }
-.item:nth-child(2) { animation-delay: 40ms; }
-.item:nth-child(3) { animation-delay: 80ms; }
-/* etc. — cap at ~6 staggered items */
-```
+- Stagger delay: **30-50ms** per item
+- Maximum stagger depth: **6-8 items** (items beyond that appear simultaneously)
+- Direction: top-to-bottom OR left-to-right, never random
 
 ---
 
 ## Press Feedback
 
-Every clickable element must give visual feedback within **100ms** of interaction.
+Every clickable element must give visual feedback within **100ms** of interaction. The canonical scale value for press feedback is **`0.96`**.
+
+- Never use `scale(0.95)` - too large, feels unresponsive
+- Never use `scale(0.97)` or higher - imperceptible at high DPI
+- `0.96` is the correct value for standard interactive elements
 
 ```css
 button:active {
-  transform: scale(0.97); /* NOT 0.90 — too dramatic */
+  transform: scale(0.96);
   transition: transform 80ms ease-out;
 }
-
-/* On release */
-button:not(:active) {
-  transform: scale(1);
-  transition: transform 150ms ease-out;
-}
 ```
 
-Scale range: **0.95–0.98** for buttons. **0.97** is the safest default.
-Never scale below 0.90 - it looks broken.
-
 ---
 
 ## `prefers-reduced-motion`
 
-Always respect this. It's not optional.
+Always respect this. It is not optional.
 
 ```css
 @media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
+  *, *::before, *::after {
     animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
     transition-duration: 0.01ms !important;
     scroll-behavior: auto !important;
   }
 }
 ```
 
-Or in JavaScript:
-```js
-const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-if (!prefersReduced) {
-  // Run animation
-}
-```
-
----
-
-## What Never To Animate
-
-- Keyboard shortcuts and commands (too frequent)
-- Tab switching within a page
-- Filter/sort toggles on data tables
-- Expanding/collapsing sidebar navigation items during heavy use
-- Any interaction the user will perform 50+ times in a session
-
----
-
-## The Invisible Detail Rule
-
-The best animations are ones users cannot describe but notice when absent. Signs of this:
-- The interaction feels "snappy" or "responsive" without thinking about why
-- Removing the animation makes the UI feel broken
-- Users say "it feels premium" but can't point to any specific feature
-
-This is the goal. Not "look at this animation" - "why does this feel so good to use?"
-
 ---
 
-## Quick Animation Audit Checklist
+## Quick Audit Checklist
 
 - [ ] No animation on keyboard-triggered actions
-- [ ] All durations ≤ 400ms
+- [ ] All durations <=400ms
 - [ ] Exit < enter duration
 - [ ] Only `transform` and `opacity` for performance
 - [ ] `prefers-reduced-motion` implemented
-- [ ] Stagger ≤ 50ms per item, capped at 6–8 items
+- [ ] Stagger <=50ms per item, capped at 6-8 items
 - [ ] Press feedback on all interactive elements
 - [ ] No bounce/elastic easing anywhere
 - [ ] All animations have a defined purpose
 
 ---
 
-## Spring Physics
-
-Spring-based animation replaces duration-based tweening with physics parameters
-(stiffness, damping, mass). Output feels more organic and adapts to interruption.
-
-### React Spring
-
-```jsx
-import { useSpring, animated } from '@react-spring/web';
-
-const styles = useSpring({
-  from: { opacity: 0, transform: 'translateY(20px)' },
-  to:   { opacity: 1, transform: 'translateY(0px)' },
-  config: { tension: 170, friction: 26 }  // default preset
-});
-```
-
-React Spring presets:
-
-| Preset | tension | friction | Character |
-|--------|---------|----------|-----------|
-| default | 170 | 26 | balanced |
-| gentle | 120 | 14 | smooth, leisurely |
-| wobbly | 180 | 12 | playful bounce |
-| stiff | 210 | 20 | snappy |
-| slow | 280 | 60 | slow and deliberate |
-| molasses | 280 | 120 | very slow, no bounce |
-
-### Framer Motion
-
-```jsx
-<motion.div
-  animate={{ x: 100 }}
-  transition={{ type: "spring", stiffness: 100, damping: 15, mass: 1 }}
-/>
-```
-
-Parameter guidance:
-
-| Param | Range | Effect |
-|-------|-------|--------|
-| stiffness | 50–300 | higher = snappier arrival |
-| damping | 10–40 | higher = less oscillation |
-| mass | 0.5–2 | higher = more inertia, slower response |
-
-Rule of thumb: for UI micro-interactions use stiffness 150–250, damping 20–30, mass 1.
-
----
-
-## Scroll-Triggered Animations
-
-Use IntersectionObserver for scroll-reveal effects - it replaces scroll-event
-listeners with a throttled browser-native API.
-
-### Basic pattern
-
-```js
-const observer = new IntersectionObserver((entries) => {
-  entries.forEach(entry => {
-    if (entry.isIntersecting) {
-      entry.target.classList.add('in-view');
-      // Optional: disconnect after first trigger
-      // observer.unobserve(entry.target);
-    }
-  });
-}, {
-  threshold: 0.1,
-  rootMargin: '0px 0px -100px 0px'  // trigger 100px before entering viewport bottom
-});
-
-document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
-```
-
-### Threshold guidance
-
-| threshold | Meaning |
-|-----------|---------|
-| 0.0 | element enters viewport edge |
-| 0.1–0.25 | element partially visible (most common for reveals) |
-| 0.5 | element half-visible |
-| 1.0 | element fully visible |
-
-### Once vs repeat
-
-- **Once** - call `observer.unobserve(entry.target)` after first intersection.
-  Use for: hero reveals, one-shot entrance animations, stat counters.
-- **Repeat** - leave observer active. Use for: progress indicators, parallax effects,
-  sticky nav state changes.
-
-### Performance rules
-
-1. Animate only `transform` and `opacity` (GPU-accelerated). Avoid `top`, `left`, `width`, `height`.
-2. No debounce/throttle needed - IntersectionObserver is already throttled by the browser.
-3. For many elements, share a single observer instance and call `observe()` once per element.
-4. Prefer CSS transitions triggered by a class toggle over requestAnimationFrame loops.
-5. Use `will-change: transform, opacity` sparingly (only on elements that animate repeatedly).
-
----
-
-## MIFB Micro-Motion Extensions
-Source: jakubkrehel/make-interfaces-feel-better (MIT) - motion.md
-
-### Interruptible Animations
-
-Use CSS transitions for interactive elements because transitions retarget mid-animation - when a user moves their cursor away before a hover animation completes, the transition reverses smoothly from wherever it currently is. Keyframe animations restart from the beginning, creating a jarring jump.
-
-**Decision rule:**
-- Interactive states (hover, focus, active, pressed): always CSS transitions
-- Orchestrated sequences, entrance effects, data-driven animations: keyframe or JS animation
-
-```css
-/* Good — transition retargets smoothly */
-.button { transition: background-color 150ms ease-out; }
-
-/* Avoid for interactive — restarts on interruption */
-.button:hover { animation: hover-bg 150ms ease-out forwards; }
-```
-
-### Split-and-Stagger Enter/Exit
-
-For multi-element entrances (card grids, lists, feature sections):
-
-- Default stagger: 100ms between elements
-- Heading words: 80ms per word
-- Entrance transform: `opacity: 0 → 1` + `translateY(12px → 0)` + `blur(4px → 0)`
-- Entrance duration: 300ms, `ease-out`
-- Exit transform: `opacity: 1 → 0` + `translateY(0 → -12px)` (opposite direction, smaller offset)
-- Exit duration: 150ms (half the entrance duration - exits should be faster)
-
-The blur component adds a depth cue that makes entrances feel less flat. Keep blur modest (4px) - the goal is a subtle focus effect, not a visible blur.
-
-### Contextual Icon Animations - Cross-Fade Pattern
-
-When swapping two icons (e.g., play ↔ pause, chevron-up ↔ chevron-down, bookmark ↔ bookmarked), use this exact cross-fade spec:
-
-**Framer Motion spring (preferred):**
-- `scale: 0.25 → 1` (entering), `scale: 1 → 0.25` (exiting)
-- `opacity: 0 → 1` (entering), `opacity: 1 → 0` (exiting)
-- `filter: blur(4px) → blur(0)` (entering), `blur(0) → blur(4px)` (exiting)
-- `transition: { type: "spring", duration: 0.3, bounce: 0 }` - **bounce MUST be 0**
+## Rules of Thumb
 
-**CSS fallback (no Framer):**
-- Keep both icons in the DOM, one `position: absolute`
-- Use `cubic-bezier(0.2, 0, 0, 1)` easing
-- Duration: 200ms
-
-The scale + blur combination creates a focus-snap effect that feels intentional rather than mechanical. The `bounce: 0` hard constraint exists because any bounce on a 0.25-scale origin point makes icons appear to "pop" invasively.
-
-### Scale on Press - Canonical Value
-
-The canonical scale value for press feedback is **`0.96`**.
-
-Rules:
-- Never use `scale(0.95)` - too large, feels unresponsive
-- Never use `scale(0.97)` - too subtle at high DPI, not perceived as feedback
-- Never use `scale(0.98)` or higher - imperceptible
-- `0.96` is the ONLY correct value for standard interactive elements
-
-Tailwind: `active:scale-[0.96]`
-Framer: `whileTap={{ scale: 0.96 }}`
-
-For primary CTAs where maximum tactility is needed (purchase, send, confirm):
-use `0.96` with a shadow reduction: `box-shadow: none` during press.
-
-Deprecation note: earlier versions of `reference/checklists.md` referenced `scale(0.97)`. That entry has been reconciled. **0.96 is the canonical value.**
-
-### AnimatePresence initial={false}
-
-When `AnimatePresence` wraps UI that exists in the DOM before it enters the animation scope (e.g., a tab panel that renders its first tab immediately, a dropdown that's already open on first load), use `initial={false}`:
-
-```tsx
-<AnimatePresence initial={false}>
-  {isOpen && <motion.div key="panel" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}
-</AnimatePresence>
-```
-
-Without `initial={false}`, Framer will animate the FIRST render of children - meaning UI that's immediately visible on page load will "fade in" unnecessarily. This creates a flash/flicker that signals poor craftsmanship.
-
-**Rule:** Any `AnimatePresence` wrapping persistent UI should have `initial={false}`.
-
-### will-change - GPU Property Table
-
-Only add `will-change` when you observe first-frame stutter on lower-end hardware. Do NOT add it preemptively - it consumes GPU memory continuously for every element that has it.
-
-GPU-compositable properties (safe with will-change):
-| Property | will-change value |
-|----------|------------------|
-| transform (translate, scale, rotate) | `transform` |
-| opacity | `opacity` |
-| filter (blur, brightness, contrast) | `filter` |
-| clip-path | `clip-path` |
-
-Never use `will-change: all` or `will-change: contents` - this forces the entire element and its subtree onto a new compositor layer, thrashing memory.
-
-Remove `will-change` after the animation completes if applied dynamically:
-```js
-element.addEventListener('transitionend', () => element.style.willChange = 'auto')
-```
+1. Keyboard-initiated actions (command palette, list navigation, shortcuts) must have zero animation. They repeat hundreds of times daily and every ms is felt.
+2. Default to named spring presets (gentle/wobbly/stiff/slow) rather than raw stiffness/damping numbers; presets are tuned for 60fps settle-time and predictable feel.
+3. Always use `--ease-*` CSS custom property tokens rather than inline `cubic-bezier()` strings; tokens keep easing consistent and respect `prefers-reduced-motion`.
+4. OKLCH is the correct color space for animated color transitions; sRGB interpolation produces muddy mid-transition colors. See `reference/color-theory.md` for color interpolation in animation.
 
 ---
 
-## Advanced Patterns
-
-For spring physics, scroll-driven animation, FLIP, View Transitions API, gesture & drag mechanics, clip-path animation patterns, blur-to-mask crossfades, WAAPI, Framer Motion hardware-acceleration gotcha, motion cohesion & personality, and the next-day slow-motion review process, see:
-
-→ **`reference/motion-advanced.md`** (Phase 18)
-
-For the canonical easing catalog (`--ease-*` tokens, cubic-bezier equivalents, 60fps settle-times):
-
-→ **`reference/motion-easings.md`** (Phase 18)
-
-For spring parameter presets (gentle / wobbly / stiff / slow):
-
-→ **`reference/motion-spring.md`** (Phase 18)
-
-For transition family taxonomy (8 families: 3d / blur / cover / destruction / dissolve / distortion / grid / light):
+## Cross-Domain See Also
 
-→ **`reference/motion-transition-taxonomy.md`** (Phase 18)
+- Color animation uses OKLCH path: `reference/color.md`
+- Gesture semantics (velocity, pointer capture): `reference/interaction.md`
+- OS-level reduced-motion: `reference/responsive.md`
+- CSS layout transitions: `reference/spatial.md`
+- Typography: `reference/typography.md`
+- UX writing: `reference/ux-writing.md`

package/reference/registry.json

@@ -625,8 +625,9 @@
     {
       "name": "motion",
       "path": "reference/motion.md",
-      "type": "motion",
-      "description": "Motion vocabulary seed (extended in Phase 18)"
+      "type": "domain-index",
+      "description": "Phase 45 domain-index: motion navigation - indexes easings, spring, transition-taxonomy, interpolate, advanced, framer-motion-patterns.",
+      "phase": 45
     },
     {
       "name": "motion-advanced",
@@ -797,8 +798,9 @@
     {
       "name": "typography",
       "path": "reference/typography.md",
-      "type": "heuristic",
-      "description": "Typography-system heuristics used by visual-hierarchy-mapper"
+      "type": "domain-index",
+      "description": "Phase 45 domain-index: typography navigation - indexes type-scale heuristics, variable-fonts-loading, proportion-systems.",
+      "phase": 45
     },
     {
       "name": "user-research",
@@ -1049,6 +1051,41 @@
       "type": "meta-rules",
       "phase": 42,
       "description": "Phase 42 multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in source/skills/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
+    },
+    {
+      "name": "color",
+      "path": "reference/color.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: color + contrast navigation - color-theory, palette-catalog, contrast-advanced, style-vocabulary."
+    },
+    {
+      "name": "spatial",
+      "path": "reference/spatial.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: layout/spacing/composition - composition, proportion-systems, css-grid-layout, visual-hierarchy-layout, gestalt, image-optimization, data-visualization, surfaces."
+    },
+    {
+      "name": "interaction",
+      "path": "reference/interaction.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: interaction + a11y + components - accessibility, component-authoring, form-patterns, information-architecture, onboarding-progressive-disclosure, emotional-design, components/."
+    },
+    {
+      "name": "responsive",
+      "path": "reference/responsive.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: responsive + i18n + platforms - i18n, rtl-cjk-cultural, platforms, native-platforms, performance, css-grid-layout."
+    },
+    {
+      "name": "ux-writing",
+      "path": "reference/ux-writing.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: UX-writing + voice - brand-voice, style-vocabulary, anti-patterns."
     }
   ]
 }

package/reference/registry.schema.json

@@ -4,19 +4,41 @@
   "title": "Reference Registry",
   "description": "Typed index of every reference/*.md (and reference/*.json default) in the plugin. Enables agents to query by type instead of grep-hunting import strings. Round-trip enforced: every reference/*.md must appear in entries[], every entry must resolve to an existing file.",
   "type": "object",
-  "required": ["version", "generated_at", "entries"],
+  "required": [
+    "version",
+    "generated_at",
+    "entries"
+  ],
   "properties": {
-    "$schema": { "type": "string" },
-    "version": { "const": 1 },
-    "generated_at": { "type": "string", "format": "date-time" },
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
     "entries": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "path", "type"],
+        "required": [
+          "name",
+          "path",
+          "type"
+        ],
         "properties": {
-          "name": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-._]*$" },
-          "path": { "type": "string", "minLength": 1 },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9][a-z0-9-._]*$"
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
           "type": {
             "type": "string",
             "enum": [
@@ -41,13 +63,28 @@
               "typography",
               "layout",
               "performance",
-              "component-spec"
+              "component-spec",
+              "domain-index"
+            ]
+          },
+          "tier": {
+            "enum": [
+              "L0",
+              "L1",
+              "L2"
             ]
           },
-          "tier": { "enum": ["L0", "L1", "L2"] },
-          "phase": { "type": "number", "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5." },
-          "description": { "type": "string" },
-          "registered_at": { "type": "string", "format": "date-time" }
+          "phase": {
+            "type": "number",
+            "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5."
+          },
+          "description": {
+            "type": "string"
+          },
+          "registered_at": {
+            "type": "string",
+            "format": "date-time"
+          }
         },
         "additionalProperties": false
       }

package/reference/responsive.md

@@ -0,0 +1,74 @@
+# Responsive Design - Domain Index
+
+This is the domain entry-point for responsive design. Load this file when the
+interface will render in more than one locale, platform, or viewport condition.
+It covers i18n engineering primitives, RTL and CJK cultural adaptation,
+platform-specific conventions, native token bridging, and performance budgets.
+It does not cover the CSS Grid implementation of responsive layouts (see
+`reference/spatial.md` for container queries and `clamp()`); it does not cover
+copy tone for localized content (see `reference/ux-writing.md`).
+
+---
+
+## Fragment Index
+
+→ **`reference/i18n.md`** (Phase 28) - use when localizing text: expansion
+budgets (+30-40%), CSS logical props, `Intl.*` APIs, ICU MessageFormat,
+bidi isolation, Unicode normalization, multi-script font stacks
+
+→ **`reference/rtl-cjk-cultural.md`** (Phase 28) - use when targeting RTL
+locales or CJK audiences: layout mirroring rules, bidirectional text isolation,
+Arabic/Hebrew/Devanagari rendering, cultural color meanings and imagery norms
+
+→ **`reference/platforms.md`** (Phase 19) - use when targeting multiple
+platforms: iOS/Android/web/visionOS/watchOS nav patterns, safe area insets,
+gesture vocabularies, haptics, native typography conventions
+
+→ **`reference/native-platforms.md`** (Phase 34.1) - use when bridging design
+tokens to native code: canonical CSS token to SwiftUI Color / Compose Color /
+Flutter ThemeData mapping, precision contract for the round-trip
+
+→ **`reference/performance.md`** (Phase 19) - use for any production
+responsive build: Core Web Vitals budgets by project type, JS/font/image
+budgets, React runtime perf rules
+
+→ **`reference/css-grid-layout.md`** (Phase 18) - load the container-queries
+and `clamp()` sections only: fluid responsive components, safe-area insets,
+logical CSS props in Grid context
+
+---
+
+## Rules of Thumb
+
+**1. Size containers for the worst-case expansion locale.**
+Russian and Finnish strings expand +40% from an English baseline. Any text
+container designed at English width will overflow in those locales. Build for
+`EN base x 1.4` as the standard layout-budget rule; top-aligned labels absorb
+expansion without horizontal breakage.
+
+**2. CSS logical properties are the implementation primitive for RTL.**
+Never use `left`/`right` in a layout that will need to mirror. Replace
+`margin-left` with `margin-inline-start`, `padding-right` with
+`padding-inline-end`, and positioned `left` with `inset-inline-start`. The full
+mapping is in `reference/rtl-cjk-cultural.md`.
+
+**3. `prefers-reduced-motion` is a responsive property, not optional.**
+Any animation behind a media query must resolve to `transition: none` or
+`animation-duration: 0.01ms` when the user has set OS-level reduced-motion.
+The CSS reset pattern is in `reference/motion.md`.
+
+**4. Native token precision contract: no re-derivation in component code.**
+Color hex values bridge to native at 8-bit channel precision (no rounding).
+Dimension px values bridge as integer dp/pt. The token-bridge round-trip in
+`reference/native-platforms.md` is the source of truth - any re-derivation
+in component code will drift from the canonical value.
+
+---
+
+## Cross-Domain See Also
+
+- i18n text expansion affects type container sizing: `reference/typography.md`
+- Touch targets differ from pointer targets: `reference/interaction.md`
+- Layout shifts at breakpoints: `reference/spatial.md`
+- OS-level reduced-motion links to animation rules: `reference/motion.md`
+- Civic multi-language government forms: `reference/domains/civic-patterns.md`

package/reference/spatial.md

@@ -0,0 +1,38 @@
+# Spatial - Composition, Grid, and Perceptual Organization
+
+Spatial design governs how elements are placed, sized, and related in two-dimensional
+space: composition principles (rule of thirds, focal point, eye-flow), proportion
+derivation (baseline grid, spacing ladder), CSS implementation (Grid, container queries,
+clamp), visual hierarchy, Gestalt grouping, and data presentation. Read this file first,
+then load the specific fragment for the task at hand. Does not cover 3D depth signaling
+via color/shadow as a color decision (see `color.md`) or responsive layout shifts driven
+by locale/platform (see `responsive.md`).
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| [`./composition.md`](./composition.md) | choosing a compositional grid (rule of thirds, root rectangles, Fibonacci), placing a focal point, deciding eye-flow archetype (Z / F / Gutenberg) |
+| [`./proportion-systems.md`](./proportion-systems.md) | deriving the baseline grid unit, spacing ladder, icon sizing, corner radius from a single multiplier (4pt / 8pt / sqrt(2)) |
+| [`./css-grid-layout.md`](./css-grid-layout.md) | implementing CSS Grid templates, subgrid, container queries, `clamp()` fluid type, logical props, anchor positioning |
+| [`./visual-hierarchy-layout.md`](./visual-hierarchy-layout.md) | ordering elements by importance: Z-order, whitespace rules, shadow depth, 24 landing archetypes |
+| [`./gestalt.md`](./gestalt.md) | auditing perceptual grouping: proximity, similarity, continuity, closure, figure/ground - 8 principles with scoring rubrics |
+| [`./image-optimization.md`](./image-optimization.md) | images in layout: format matrix, srcset/sizes math, LQIP/BlurHash, CDN transforms, image budget |
+| [`./data-visualization.md`](./data-visualization.md) | charts/dashboards: 25-type chart-choice matrix, color-blind palettes, axis conventions, UUPM dashboard patterns |
+| [`./surfaces.md`](./surfaces.md) | surface treatments: concentric radius formula, optical alignment, 3-layer shadow system, hit area sizing |
+
+## Rules of Thumb
+
+1. Place primary CTAs on the rule-of-thirds power points (the 33%/67% intersections), not dead-center. Centered heroes are the intentional exception, not the default.
+2. Choose one baseline unit for the whole product (4pt, 8pt, or sqrt(2)) and author every spacing, sizing, and radius token as a multiple of it. No one-off values.
+3. CSS Grid container queries (`@container`) should replace media queries for component-level layout. Reserve media queries for page-level breakpoints only.
+4. Gestalt proximity rule: related controls 8px apart or less; unrelated groups 32px apart or more. The layout should communicate relationships before the user reads labels.
+5. Choose the chart type before the color palette. The wrong chart type cannot be rescued by a better palette. Use `data-visualization.md` chart-choice matrix first.
+
+## See Also
+
+- Shadow and elevation as color/depth signal: [`./color.md`](./color.md)
+- Type scale ties into spatial proportion grid: [`./typography.md`](./typography.md)
+- Responsive layout shifts at breakpoints: [`./responsive.md`](./responsive.md)
+- Gestalt grouping informs information architecture: [`./interaction.md`](./interaction.md)
+- Gaming: TV-safe area constraints: [`./domains/gaming-patterns.md`](./domains/gaming-patterns.md)

package/reference/typography.md

@@ -1,5 +1,34 @@
 # Typography - Scale, Pairing, and Hierarchy
 
+This file is the domain index for typography. It covers type-scale construction,
+weight hierarchy, font pairing, and micro-typography. Read `variable-fonts-loading.md`
+when web fonts are in scope. Read `proportion-systems.md` when the full UI grid is
+in scope. Does not cover text-contrast (see `color.md`) or locale text expansion
+(see `responsive.md`, which indexes [`./i18n.md`](./i18n.md) for the per-locale expansion budgets).
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| This file (below) | type scale ratios, sizing tokens, weight hierarchy, font pairings, micro-typography |
+| [`./variable-fonts-loading.md`](./variable-fonts-loading.md) | web fonts, `@font-face`, `font-display`, FOIT/FOUT, variable font axes, subsetting, fallback metrics |
+| [`./proportion-systems.md`](./proportion-systems.md) | 4pt/8pt/sqrt(2) baseline grid, spacing ladder, icon sizing, corner radius derivation |
+
+## Rules of Thumb
+
+1. A 1.25 (Major Third) or 1.333 (Perfect Fourth) ratio fits 95% of SaaS products; only reach for 1.618 when visual drama is the explicit brief.
+2. Never author `line-height` as a pixel value - always use a unitless multiplier (1.4-1.6 for body, 1.1-1.2 for headings); unitless values scale with user font-size overrides.
+3. Font weight on the web has only 7 meaningful stops (100-700 in 100-steps); any weight not in the font file rounds to the nearest available - check the variable font `wght` range before specifying 450 or 600.
+4. Baseline-grid lock: every spacing and sizing token should be a multiple of the chosen baseline unit; `padding: 12px` next to body at `16/24` on an 8pt grid is a silent proportion break.
+5. For localized UIs, size type containers for +40% expansion (Russian/Finnish worst-case); top-aligned labels are the only label position that absorbs expansion without layout breakage.
+
+## See Also
+
+- Text contrast and color-blindness checks: [`./color.md`](./color.md)
+- Text expansion in localized UIs: [`./responsive.md`](./responsive.md)
+- Proportion systems tie type to spatial grid: [`./spatial.md`](./spatial.md)
+- Finance number formatting (tabular-nums): [`./domains/finance-patterns.md`](./domains/finance-patterns.md)
+
 ---
 
 ## Type Scale Systems
@@ -35,7 +64,7 @@ Choose a ratio and base size. Common ratios:
 
 Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values in the scale.
 
-**See:** [`./proportion-systems.md`](./proportion-systems.md) §Modular Relationships for how the type scale ties to spacing / sizing / radius scales - when one ratio drives all four scales the whole UI gains a single rhythm rather than four independently-tuned progressions.
+**See:** [`./proportion-systems.md`](./proportion-systems.md) for how the type scale ties to spacing / sizing / radius scales.
 
 ---
 
@@ -43,11 +72,11 @@ Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values
 
 | Context | Line height | Notes |
 |---|---|---|
-| Body text | **1.5 – 1.75** | More generous = more readable |
-| Headings | **1.1 – 1.3** | Tight heading stacks look intentional |
+| Body text | **1.5 - 1.75** | More generous = more readable |
+| Headings | **1.1 - 1.3** | Tight heading stacks look intentional |
 | Captions / small text | **1.4** | Smaller text needs more breathing room |
-| Code blocks | **1.6 – 1.8** | Line scanning for code |
-| Display / hero | **0.9 – 1.1** | Can go very tight for dramatic effect |
+| Code blocks | **1.6 - 1.8** | Line scanning for code |
+| Display / hero | **0.9 - 1.1** | Can go very tight for dramatic effect |
 
 ---
 
@@ -55,9 +84,9 @@ Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values
 
 | Context | Characters per line | Notes |
 |---|---|---|
-| Desktop body | **65 – 75 chars** | Optimal reading comfort |
-| Mobile body | **35 – 55 chars** | Narrower viewport forces shorter |
-| Hero/display | **35 – 55 chars** | Headings should never wrap awkwardly |
+| Desktop body | **65 - 75 chars** | Optimal reading comfort |
+| Mobile body | **35 - 55 chars** | Narrower viewport forces shorter |
+| Hero/display | **35 - 55 chars** | Headings should never wrap awkwardly |
 | Data/tables | No limit | Tables have own structure |
 
 Enforce with `max-width`: `65ch` for body containers works with any font size.
@@ -68,13 +97,13 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 
 | Role | Weight | Notes |
 |---|---|---|
-| Display headings | **700 – 900** | Bold commands attention |
-| Page headings | **600 – 700** | Strong but not display-level |
-| Section headings | **500 – 600** | Distinguish from body |
+| Display headings | **700 - 900** | Bold commands attention |
+| Page headings | **600 - 700** | Strong but not display-level |
+| Section headings | **500 - 600** | Distinguish from body |
 | Body text | **400** | Regular - no emphasis weight |
 | UI labels | **500** | Slightly heavier than body |
 | Captions | **400** | Regular - size reduces emphasis |
-| Monospace code | **400 – 500** | |
+| Monospace code | **400 - 500** | |
 
 **Rule**: Never use `font-weight: 300` (light) on small text. It becomes illegible below 16px.
 
@@ -127,7 +156,7 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 
 **All caps body text** - reserved for: labels, badges, category markers, short UI labels only. Never for sentences or paragraphs.
 
-**Inconsistent tracking** - only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability. Random tracking changes across components signal lack of system.
+**Inconsistent tracking** - only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability.
 
 ---
 
@@ -136,8 +165,8 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 | Use case | letter-spacing |
 |---|---|
 | Body text | `0` (default) |
-| Uppercase labels / badges | `0.05em – 0.1em` |
-| Display headings | `−0.02em – 0.01em` |
+| Uppercase labels / badges | `0.05em - 0.1em` |
+| Display headings | `-0.02em - 0.01em` |
 | Monospace code | `0` or slight positive |
 
 ---
@@ -174,68 +203,19 @@ Test: Can you tell which element is a heading just from the weight/family, witho
 
 ## Brand Archetype Quick Guide
 
-Pick the archetype closest to the project brief; use the recommended pairing
-as a starting point (adjust for specific constraints).
-
 | Archetype | Character | Recommended Pairing |
 |-----------|-----------|---------------------|
 | SaaS / productivity | clear, neutral, utilitarian | Inter (UI) + Inter (body) - single family |
 | Consumer / editorial | warm, opinionated, expressive | Fraunces or GT Sectra (display) + Inter (body) |
 | Enterprise / finance | authoritative, conservative | IBM Plex Sans (UI) + IBM Plex Serif (body) |
 | Developer tools | technical, efficient | Geist (UI) + Geist Mono (code) |
-| Bold / expressive | high-energy, distinctive | Söhne or Mona Sans (display) + Inter (body) |
-
-**Selection heuristic:** If the brief uses words like "professional", "trustworthy", "clean" → SaaS or Enterprise. If "warm", "editorial", "narrative" → Consumer. If "bold", "energetic", "distinctive" → Bold. If "technical", "efficient", "fast" → Dev tools.
-
----
-
-## Variable Fonts
-
-Variable fonts expose typographic axes that can be animated or set per-context
-via `font-variation-settings`. Prefer variable fonts over static family fallbacks
-when available - one file covers all weights and widths.
-
-### Common axes
-
-| Axis | Range | Purpose |
-|------|-------|---------|
-| wght | 100–900 | Weight (Thin → Black) |
-| wdth | 50%–150% | Width (Condensed → Extended) |
-| ital | 0 / 1 | Italic toggle (discrete in most) |
-| opsz | font-size value | Optical size (auto-applies when `font-optical-sizing: auto`) |
-
-### @font-face format
-
-```css
-@font-face {
-  font-family: 'InterVariable';
-  src: url('/fonts/InterVariable.woff2') format('woff2-variations');
-  font-weight: 100 900;
-  font-style: normal;
-}
-```
-
-### Usage via font-variation-settings
-
-```css
-.heading { font-variation-settings: "wght" 700, "opsz" 32; }
-.body    { font-variation-settings: "wght" 400; }
-```
-
-### Fallback strategy
-
-Always include a non-variable fallback of the same family in the font stack:
-
-```css
-font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
-```
+| Bold / expressive | high-energy, distinctive | Sohne or Mona Sans (display) + Inter (body) |
 
-**See:** [`./i18n.md`](./i18n.md) §Multi-Script Font Stacks for when a multi-script project should ship weighted-static fonts rather than a single variable font (some scripts ship as static-only families; mixing scripts in a single variable file is rarely viable).
+**Selection heuristic:** If the brief uses words like "professional", "trustworthy", "clean" use SaaS or Enterprise. If "warm", "editorial", "narrative" use Consumer. If "bold", "energetic", "distinctive" use Bold. If "technical", "efficient", "fast" use Dev tools.
 
 ---
 
 ## Micro-Typography
-Source: jakubkrehel/make-interfaces-feel-better (MIT) - typography.md
 
 ### text-wrap
 
@@ -254,7 +234,7 @@ Apply antialiasing at root level only:
   -moz-osx-font-smoothing: grayscale;
 }
 ```
-Never apply per-element - this creates inconsistency within a single text block and is one of the most common micro-typography mistakes. The antialiased value makes text appear slightly thinner/lighter, which is generally preferred for UI type at modern screen densities.
+Never apply per-element - this creates inconsistency within a single text block.
 
 ### Tabular numerals
 
@@ -262,52 +242,4 @@ Use tabular-nums on any surface where numbers change dynamically or need to alig
 ```css
 .counter, .price, .timer, .table-cell { font-variant-numeric: tabular-nums; }
 ```
-Proportional numerals (the default) cause text to shift width when numbers change, creating a distracting jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums - test at your numeric composition before committing.
-
-## Font Pairings Catalog
-Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) - data/typography.csv
-
-57 professionally curated pairings grouped by use-case vertical. For font loading, see `reference/data/google-fonts.csv` for the full 1923-font reference.
-
-### SaaS / Productivity
-- **Inter + Inter** (mono weight hierarchy) - The "safe default" for app UIs. Use regular (400) for body, medium (500) for labels, semibold (600) for headings. Consistent x-height, excellent at small sizes.
-- **Inter + JetBrains Mono** - For dev tools and dashboards with code display. JetBrains Mono has excellent legibility at 12-14px.
-- **Geist Sans + Geist Mono** - Vercel's pair; clean, modern, designed together.
-- **Outfit + DM Mono** - Friendly SaaS feel with clear code fallback.
-
-### Consumer / Marketing
-- **Satoshi + Cabinet Grotesk** - High-energy, modern consumer feel.
-- **Plus Jakarta Sans + Syne** - Playful but legible; works for creative consumer apps.
-- **DM Sans + DM Serif Display** - Classic pairing; editorial headers, clean body.
-- **Nunito + Source Code Pro** - Approachable and friendly.
-
-### Finance / Enterprise
-- **IBM Plex Sans + IBM Plex Mono** - Authoritative, systematic, designed for data-heavy interfaces.
-- **Source Sans 3 + Source Code Pro** - Adobe's workhorse pair; widely trusted.
-- **Lato + Roboto Mono** - Clean, neutral enterprise pair.
-
-### Editorial / Publishing
-- **Playfair Display + Source Serif 4** - High contrast serif headers with readable body serif.
-- **Cormorant Garamond + Proza Libre** - Elegant luxury/editorial tone.
-- **Libre Baskerville + Libre Franklin** - Free-license editorial pair.
-- **EB Garamond + Lato** - Classic print feel with modern body.
-
-### Wellness / Health
-- **Nunito + Nunito Sans** - Soft, approachable, consistent x-height.
-- **Quicksand + Work Sans** - Rounded, friendly, healthcare-appropriate.
-- **Raleway + Open Sans** - Clean and welcoming.
-
-### Dev Tools
-- **JetBrains Mono + Inter** - Code-first, UI-second; natural for developer tools.
-- **Fira Code + Fira Sans** - Cohesive family; ligatures available.
-- **Cascadia Code + Segoe UI** - Microsoft's modern dev pair.
-
-### Luxury / Fashion
-- **Cormorant + Montserrat** - High contrast serif + geometric sans; classic luxury.
-- **Bodoni Moda + Jost** - Fashion editorial feel.
-- **Playfair Display + Raleway** - Elegant header + clean body.
-
-### Gaming / Entertainment
-- **Syne + DM Sans** - Bold, energetic headers; clean readable body.
-- **Bebas Neue + Open Sans** - Impact headlines; neutral body.
-- **Exo 2 + Roboto** - Futuristic but readable.
+Proportional numerals (the default) cause text to shift width when numbers change, creating jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums - test at your numeric composition before committing.

package/reference/ux-writing.md

@@ -0,0 +1,60 @@
+# UX Writing - Domain Index
+
+This is the domain entry-point for UX writing. Load this file when the task
+involves voice, tone, or the copy standards that govern text a user reads in
+the product: button labels, error messages, empty states, onboarding copy, and
+microcopy. It does not cover the engineering side of localization (see
+`reference/responsive.md` for string expansion budgets and `Intl.*` APIs); it
+does not cover label position in forms or information architecture (see
+`reference/interaction.md`).
+
+---
+
+## Fragment Index
+
+→ **`reference/brand-voice.md`** (Phase 24) - use when establishing or
+auditing tone: 6 voice axes (Formal-Casual, Serious-Playful, etc.), 12
+archetypes, tone-by-context matrix, industry-context palettes
+
+→ **`reference/style-vocabulary.md`** (Phase 24) - use when confirming an
+aesthetic direction has a compatible voice register: the `Avoid For` column
+cross-checks brand fit; `Best For` confirms product-type alignment
+
+→ **`reference/anti-patterns.md`** - use when auditing existing copy: the
+BAN/SLOP grep patterns surface copy violations (AI-tells, filler phrases)
+alongside visual ones
+
+---
+
+## Rules of Thumb
+
+**1. Voice axes are independent from archetypes.**
+Pick a position on each of the 6 axes first (Formal-Casual, Serious-Playful,
+Authoritative-Supportive, and so on), then layer an archetype on top. The
+archetype does not determine the axis position - they are orthogonal dimensions
+in `reference/brand-voice.md`.
+
+**2. Never use placeholder text as the sole label for a form field.**
+It disappears on focus, fails WCAG 1.3.5, and collapses under translation.
+Top-aligned labels are the only position that absorbs localization expansion
+without breaking layout.
+
+**3. Error messages follow a three-clause structure: what happened, why, what
+to do.**
+State the event in past tense, explain the cause in one clause, give a present
+tense imperative for recovery. No tech jargon. Never blame the user.
+
+**4. Shift toward supportive tone during error, empty-state, and onboarding
+moments.**
+Even a formally-voiced product should move on the axis toward supportive when
+the user is at risk of abandonment. The per-context tone matrix in
+`reference/brand-voice.md` provides the exact adjustment.
+
+---
+
+## Cross-Domain See Also
+
+- String expansion budgets constrain copy length: `reference/responsive.md`
+- Error copy paired with form patterns: `reference/interaction.md`
+- Empty-state copy pairs with onboarding pattern: `reference/interaction.md`
+- Style direction voice register cross-check: `reference/style-vocabulary.md`