@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/migrations/tailwind-v4.md

@@ -1,28 +1,28 @@
-# Tailwind CSS v3 → v4 — Migration Rule Library
+# Tailwind CSS v3 → v4 - Migration Rule Library
 
-This is a **proposal-only** rule library consumed by `agents/ds-migration-planner.md` and the pure `scripts/lib/migration/codemod-gen.cjs`. It encodes the concrete, mechanical changes between Tailwind CSS v3 and v4 so the planner can template codemods. GDD never auto-applies any rule below — every codemod is surfaced as a reviewable diff the USER inspects and runs.
+This is a **proposal-only** rule library consumed by `agents/ds-migration-planner.md` and the pure `scripts/lib/migration/codemod-gen.cjs`. It encodes the concrete, mechanical changes between Tailwind CSS v3 and v4 so the planner can template codemods. GDD never auto-applies any rule below - every codemod is surfaced as a reviewable diff the USER inspects and runs.
 
-A note the planner should carry into any plan it writes: v4 raised its browser baseline (it targets modern Safari / Chrome / Firefox and leans on native CSS cascade layers, `@property`, and `color-mix()`). A project that must support older browsers is **not** a clean migration target — the planner should surface that as a blocker rather than emitting codemods, since no class rename below can recover the dropped baseline.
+A note the planner should carry into any plan it writes: v4 raised its browser baseline (it targets modern Safari / Chrome / Firefox and leans on native CSS cascade layers, `@property`, and `color-mix()`). A project that must support older browsers is **not** a clean migration target - the planner should surface that as a blocker rather than emitting codemods, since no class rename below can recover the dropped baseline.
 
 ## Detection
 
-Detect Tailwind and the v3→v4 boundary from `package.json` **alone** — no file-content scanning is required for the gate. The planner reads `dependencies` + `devDependencies` and classifies:
+Detect Tailwind and the v3→v4 boundary from `package.json` **alone** - no file-content scanning is required for the gate. The planner reads `dependencies` + `devDependencies` and classifies:
 
-- **Tailwind present** — a `tailwindcss` key appears under `dependencies` or `devDependencies`. If absent, the project is out of scope and no rules apply.
+- **Tailwind present** - a `tailwindcss` key appears under `dependencies` or `devDependencies`. If absent, the project is out of scope and no rules apply.
 
-- **On v3** — the `tailwindcss` semver range resolves to `^3` / `~3` / `3.x`. Corroborating signals:
+- **On v3** - the `tailwindcss` semver range resolves to `^3` / `~3` / `3.x`. Corroborating signals:
   - a `tailwind.config.js` (or `.cjs` / `.mjs` / `.ts`) referenced by the build config, and
   - a PostCSS pipeline that lists the bare `tailwindcss` plugin (in v3 the PostCSS plugin ships *inside* the core package).
 
-- **On v4** — the `tailwindcss` range resolves to `^4` / `4.x`, **and/or** one of the dedicated build packages is present:
-  - `@tailwindcss/postcss` — the PostCSS plugin, which **moved out of core** into its own package in v4 (a high-confidence v4 marker), or
-  - `@tailwindcss/vite` — the first-party Vite plugin (used instead of PostCSS in Vite projects).
+- **On v4** - the `tailwindcss` range resolves to `^4` / `4.x`, **and/or** one of the dedicated build packages is present:
+  - `@tailwindcss/postcss` - the PostCSS plugin, which **moved out of core** into its own package in v4 (a high-confidence v4 marker), or
+  - `@tailwindcss/vite` - the first-party Vite plugin (used instead of PostCSS in Vite projects).
 
-- **Migration candidate** — `tailwindcss@^3` with **no** `@tailwindcss/postcss` and **no** `@tailwindcss/vite`. A `tailwind.config.js` that survives the version bump is the signal that the JS-config → CSS-first migration (TW4-02) has not yet run.
+- **Migration candidate** - `tailwindcss@^3` with **no** `@tailwindcss/postcss` and **no** `@tailwindcss/vite`. A `tailwind.config.js` that survives the version bump is the signal that the JS-config → CSS-first migration (TW4-02) has not yet run.
 
-- **Build-tool target** — a `vite` dependency steers the planner toward the `@tailwindcss/vite` install target; otherwise assume the `@tailwindcss/postcss` PostCSS target. Do **not** infer Tailwind from a lockfile alone — require the manifest entry so the gate stays deterministic.
+- **Build-tool target** - a `vite` dependency steers the planner toward the `@tailwindcss/vite` install target; otherwise assume the `@tailwindcss/postcss` PostCSS target. Do **not** infer Tailwind from a lockfile alone - require the manifest entry so the gate stays deterministic.
 
-Reading the semver range: treat a leading `^3` / `~3` / `3` / `3.x` as v3, and `^4` / `4` / `4.x` as v4. A wildcard (`*`) or git/`file:` specifier is **ambiguous** — the planner should fall back to the corroborating signals above (presence of `@tailwindcss/postcss`, a surviving `tailwind.config.js`) and, if still unresolved, mark detection as inconclusive rather than guessing. Detection is package.json-only by design; the per-class renames in the table are confirmed later against source by the codemod step, not by this gate.
+Reading the semver range: treat a leading `^3` / `~3` / `3` / `3.x` as v3, and `^4` / `4` / `4.x` as v4. A wildcard (`*`) or git/`file:` specifier is **ambiguous** - the planner should fall back to the corroborating signals above (presence of `@tailwindcss/postcss`, a surviving `tailwind.config.js`) and, if still unresolved, mark detection as inconclusive rather than guessing. Detection is package.json-only by design; the per-class renames in the table are confirmed later against source by the codemod step, not by this gate.
 
 ## Migration rules
 
@@ -33,7 +33,7 @@ Rule IDs are stable. `Kind ∈ rename-class | rename-prop | remove-component | t
 | TW4-01 | rename-prop | `@tailwind base; @tailwind components; @tailwind utilities;` → `@import "tailwindcss";` | The three v3 directives collapse into a single CSS import. Fully mechanical; affects the one entry CSS file. |
 | TW4-02 | token-rename | `tailwind.config.js` (JS `theme`) → `@theme { … }` (CSS-first) | Theme moves into CSS custom properties under `@theme`. The JS config is still loadable via an `@config "./tailwind.config.js";` bridge, but the native v4 target is CSS. Highest-effort rule in the set. |
 | TW4-03 | token-rename | `theme(colors.red.500)` in CSS → `var(--color-red-500)` | `@theme` tokens are emitted as real CSS variables, so `theme()` lookups and arbitrary values resolve to `var(--…)` references instead. |
-| TW4-04 | rename-class | `shadow-sm` → `shadow-xs` | Box-shadow scale shifted one step down. **High visual delta** — every `shadow-sm` renders visibly smaller after the bump. |
+| TW4-04 | rename-class | `shadow-sm` → `shadow-xs` | Box-shadow scale shifted one step down. **High visual delta** - every `shadow-sm` renders visibly smaller after the bump. |
 | TW4-05 | rename-class | `shadow` → `shadow-sm` | The bare `shadow` alias is removed; the old default maps to the new explicit `shadow-sm`. |
 | TW4-06 | rename-class | `drop-shadow` → `drop-shadow-sm` | Same bare-alias removal as TW4-05, applied across the `drop-shadow-*` filter scale. |
 | TW4-07 | rename-class | `blur-sm` → `blur-xs` | Blur scale shifted one step down, mirroring the shadow scale. |
@@ -47,27 +47,27 @@ Rule IDs are stable. `Kind ∈ rename-class | rename-prop | remove-component | t
 | TW4-15 | rename-class | `flex-shrink-0` / `flex-grow` → `shrink-0` / `grow` | The `flex-` prefix on shrink/grow was already deprecated in v3 and is removed in v4. Pure prefix strip, no value change. |
 | TW4-16 | new-default | default border / divide color `gray-200` → `currentColor` | v4 borders and dividers default to `currentColor`, not `gray-200`. To preserve the v3 look, set `@theme { --color-border: …; }` or add explicit `border-gray-200`. **High visual delta.** |
 | TW4-17 | rename-prop | `@layer utilities { … }` (custom utility) → `@utility name { … }` | Registering custom utilities now uses the `@utility` API; plain `@layer utilities` blocks no longer register sortable utilities. `@layer base` for resets still works. |
-| TW4-18 | rename-prop | `corePlugins` / `safelist` (JS config) → `@source inline(…)` + CSS theme | v4 has no `corePlugins` toggle and content detection is automatic; explicit safelisting moves to `@source inline(...)`. Flag for manual handling — not a 1:1 token swap. |
+| TW4-18 | rename-prop | `corePlugins` / `safelist` (JS config) → `@source inline(…)` + CSS theme | v4 has no `corePlugins` toggle and content detection is automatic; explicit safelisting moves to `@source inline(...)`. Flag for manual handling - not a 1:1 token swap. |
 
 ## Impact notes
 
-**High visual delta — require manual review and a screenshot diff before accepting:**
+**High visual delta - require manual review and a screenshot diff before accepting:**
 
 - **Scale shifts (TW4-04 through TW4-10).** Shadow, blur, and radius scales all shifted one step down. A blanket find/replace is correct *only if* the project used the default scale. Any project that overrode these in `tailwind.config.js` must reconcile against TW4-02 first, or the rename compounds with a custom scale and yields wrong sizes. Treat these seven rules as one coordinated set, not independent edits.
 - **Ring width + color (TW4-11, TW4-12).** The default ring went from 3px/blue to 1px/currentColor. Focus rings are an accessibility surface, so both the width (`ring-3`) and color (`ring-blue-500`) rewrites should be reviewed against focus-visible states rather than applied silently.
 - **Default border / divide color (TW4-16) and outline (TW4-13).** The `currentColor` border default and the `outline-none` → `outline-hidden` rename change visible chrome and focus behavior across the whole app. These are the two rules most likely to look "broken" immediately post-migration; verify against a representative page set.
 
-**Mechanical — low risk, still proposal-only:**
+**Mechanical - low risk, still proposal-only:**
 
-- **Import directive (TW4-01)** and **flex-prefix strip (TW4-15)** are deterministic textual swaps with no visual consequence — safe to batch, but still emitted as a reviewable diff.
-- **Opacity slash syntax (TW4-14)** is mechanical per-utility, but the codemod must pair the correct color literal with the opacity value — confirm it preserves the original color when expanding `bg-opacity-50` into `bg-<color>/50`.
+- **Import directive (TW4-01)** and **flex-prefix strip (TW4-15)** are deterministic textual swaps with no visual consequence - safe to batch, but still emitted as a reviewable diff.
+- **Opacity slash syntax (TW4-14)** is mechanical per-utility, but the codemod must pair the correct color literal with the opacity value - confirm it preserves the original color when expanding `bg-opacity-50` into `bg-<color>/50`.
 
-**Needs a human design decision — not auto-templatable:**
+**Needs a human design decision - not auto-templatable:**
 
 - **CSS-first theme (TW4-02), `theme()` rewrites (TW4-03), custom-utility migration (TW4-17), and config-feature removal (TW4-18)** depend on the project's actual theme shape and custom utilities. The planner should emit a scaffold (an `@theme` block skeleton plus an `@config` bridge note) and hand the remainder to the USER rather than attempting a full automatic translation. The `@config` directive is the recommended interim bridge so a project can adopt the v4 build packages *before* fully porting its JS theme.
 
 **Application order and idempotency (for `codemod-gen.cjs`):**
 
-- The shadow, blur, and radius scales each contain a **shift hazard**: renaming the bare alias up one step (e.g. TW4-05 `shadow` → `shadow-sm`) and shifting the named step down (TW4-04 `shadow-sm` → `shadow-xs`) target overlapping tokens. A naive two-pass run can double-apply — `shadow` becomes `shadow-sm` becomes `shadow-xs`. Templates must rename in a **single atomic pass** (match the original token, map to its final value) so each utility is rewritten exactly once. The same hazard applies to the `blur-*` (TW4-07/08) and `rounded-*` (TW4-09/10) pairs.
+- The shadow, blur, and radius scales each contain a **shift hazard**: renaming the bare alias up one step (e.g. TW4-05 `shadow` → `shadow-sm`) and shifting the named step down (TW4-04 `shadow-sm` → `shadow-xs`) target overlapping tokens. A naive two-pass run can double-apply - `shadow` becomes `shadow-sm` becomes `shadow-xs`. Templates must rename in a **single atomic pass** (match the original token, map to its final value) so each utility is rewritten exactly once. The same hazard applies to the `blur-*` (TW4-07/08) and `rounded-*` (TW4-09/10) pairs.
 - Run the entry-CSS rules (**TW4-01**, then the **TW4-02 / TW4-03 / TW4-17** theme scaffold) before the class renames, so the build is parseable under v4 before utility classes change. Class renames (TW4-04 through TW4-16) operate on template/markup files and are independent of each other once the single-pass rule above is respected.
-- Every generated codemod should be **idempotent** — re-running it on already-migrated source must be a no-op. The planner surfaces the full set as one reviewable changeset; the USER applies it, not GDD.
+- Every generated codemod should be **idempotent** - re-running it on already-migrated source must be a no-op. The planner surfaces the full set as one reviewable changeset; the USER applies it, not GDD.

package/reference/model-prices.md

@@ -1,6 +1,6 @@
-# Model Prices — Router
+# Model Prices - Router
 
-**Phase 26 D-08 router.** This file used to carry a single Anthropic-only price table. As of v1.26.0 it links to per-runtime sub-tables — one file per runtime under `reference/prices/`. Budget-enforcer + cost-aggregator load the sub-table for the active runtime (resolved via `scripts/lib/runtime-detect.cjs`) and tag every `events.jsonl` cost row with the runtime ID.
+**Phase 26 D-08 router.** This file used to carry a single Anthropic-only price table. As of v1.26.0 it links to per-runtime sub-tables - one file per runtime under `reference/prices/`. Budget-enforcer + cost-aggregator load the sub-table for the active runtime (resolved via `scripts/lib/runtime-detect.cjs`) and tag every `events.jsonl` cost row with the runtime ID.
 
 For the model→tier mapping (which model name corresponds to opus/sonnet/haiku per runtime), see `reference/runtime-models.md`.
 
@@ -45,7 +45,7 @@ When `cache_hit: true`, the formula re-runs with `cached_input_per_1m` in place
 
 When a cost lookup misses (model not present in the runtime's sub-table, or runtime sub-table is a stub), `scripts/lib/budget-enforcer.cjs` falls back to `reference/prices/claude.md` and emits a `cost_lookup_fallback` event. This keeps the pipeline running on stub runtimes while authority-watcher (Phase 13.2) flags drift for follow-up.
 
-If `claude.md` ALSO misses the model, the spawn proceeds with `cost_usd: null` and a `cost_lookup_failed` event — the existing fail-open contract from Phase 20-13.
+If `claude.md` ALSO misses the model, the spawn proceeds with `cost_usd: null` and a `cost_lookup_failed` event - the existing fail-open contract from Phase 20-13.
 
 ## Transitional fallback (v1.25 and earlier)
 

package/reference/model-tiers.md

@@ -1,41 +1,41 @@
-# Model Tiers — Selection Guide + Per-Agent Map
+# Model Tiers - Selection Guide + Per-Agent Map
 
-**Purpose:** Source of truth for the `default-tier: haiku|sonnet|opus` frontmatter field carried by every agent at `agents/*.md`. Tiers are one of three Anthropic model classes — priced in `reference/model-prices.md`.
+**Purpose:** Source of truth for the `default-tier: haiku|sonnet|opus` frontmatter field carried by every agent at `agents/*.md`. Tiers are one of three Anthropic model classes - priced in `reference/model-prices.md`.
 
-Phase 10.1 (OPT-06) locked the initial per-agent tier assignment. Phase 11's `design-reflector` (`agents/design-reflector.md`) proposes refinements from measured `.design/agent-metrics.json` data; no auto-apply — proposals flow through `/gdd:apply-reflections` and `/gdd:optimize`.
+Phase 10.1 (OPT-06) locked the initial per-agent tier assignment. Phase 11's `design-reflector` (`agents/design-reflector.md`) proposes refinements from measured `.design/agent-metrics.json` data; no auto-apply - proposals flow through `/gdd:apply-reflections` and `/gdd:optimize`.
 
 ---
 
 ## Tier Assignment Rules
 
-### haiku — Verifiers and checkers with deterministic rubrics
+### haiku - Verifiers and checkers with deterministic rubrics
 
 Pick `haiku` when the agent is:
 - Applying a fixed scoring rubric (`design-verifier` runs five deterministic passes with numeric category scores).
 - Producing a boolean + rationale answer (`design-plan-checker`, `design-context-checker`, `design-integration-checker` all return "gaps found" + structured list).
-- Performing a read-only state sync (`gdd-graph-refresh` mirrors graph state — no reasoning density beyond schema matching).
-- Running at high frequency where cost compounds (checkers run on every `/gdd:verify` pass — cost multiplies with iterations).
+- Performing a read-only state sync (`gdd-graph-refresh` mirrors graph state - no reasoning density beyond schema matching).
+- Running at high frequency where cost compounds (checkers run on every `/gdd:verify` pass - cost multiplies with iterations).
 
 Haiku's ~20x price advantage over Opus per 1M tokens (see `reference/model-prices.md`) makes it correct for deterministic-rubric work where the marginal quality gain of larger models is negligible.
 
-### sonnet — Researchers, mappers, doc-writers, executors, fixers
+### sonnet - Researchers, mappers, doc-writers, executors, fixers
 
 Pick `sonnet` when the agent is:
 - Doing open-ended pattern recognition on codebase data (`a11y-mapper`, `component-taxonomy-mapper`, `design-pattern-mapper`, `motion-mapper`, `token-mapper`, `visual-hierarchy-mapper`).
 - Synthesizing prose from structured input (`design-doc-writer`, `design-research-synthesizer`, `design-context-builder`).
 - Executing a concrete plan under supervision (`design-executor`, `design-fixer`, `design-figma-writer`).
-- Conducting targeted research under a time budget (`design-phase-researcher` — 2-minute web-search budget).
+- Conducting targeted research under a time budget (`design-phase-researcher` - 2-minute web-search budget).
 - Updating / extracting / maintaining project state (`gdd-intel-updater`, `gdd-learnings-extractor`, `design-auditor`).
 
-Sonnet balances reasoning density against cost. This is the default — if you're uncertain about an agent's role, it's probably sonnet.
+Sonnet balances reasoning density against cost. This is the default - if you're uncertain about an agent's role, it's probably sonnet.
 
-### opus — Planners, critics, advisors, strategic reflectors
+### opus - Planners, critics, advisors, strategic reflectors
 
 Pick `opus` when the agent is:
-- Proposing a plan that downstream executors will follow (`design-planner` — the plan becomes the contract for the whole design stage).
-- Critiquing or advising on ambiguity (`design-advisor`, `design-assumptions-analyzer` — these agents question the prompt itself).
+- Proposing a plan that downstream executors will follow (`design-planner` - the plan becomes the contract for the whole design stage).
+- Critiquing or advising on ambiguity (`design-advisor`, `design-assumptions-analyzer` - these agents question the prompt itself).
 - Facilitating interactive decision-gathering (`design-discussant`).
-- Cross-phase strategic reasoning (`design-reflector` — Phase 11 — proposes changes to the plugin itself from measured data).
+- Cross-phase strategic reasoning (`design-reflector` - Phase 11 - proposes changes to the plugin itself from measured data).
 
 Opus cost (~5x Sonnet, ~25x Haiku) is justified only when a single wrong decision cascades into many downstream agent spawns. Planners fit. Mappers don't.
 
@@ -46,16 +46,16 @@ Opus cost (~5x Sonnet, ~25x Haiku) is justified only when a single wrong decisio
 | Agent | Role class | default-tier | Rationale |
 |-------|------------|--------------|-----------|
 | design-verifier | Verifier | haiku | Runs a deterministic 5-pass scoring rubric; Haiku handles structured grading without quality loss. |
-| design-plan-checker | Checker | haiku | Checks the plan against a fixed schema — boolean + gap-list output. |
-| design-context-checker | Checker | haiku | Checks context completeness against a schema — boolean + gap-list output. |
-| design-integration-checker | Checker | haiku | Checks cross-artifact references — deterministic link-integrity work. |
-| gdd-graph-refresh | Refresh agent | haiku | Rebuilds graph at .design/graph/graph.json from intel slices — no reasoning density required. |
+| design-plan-checker | Checker | haiku | Checks the plan against a fixed schema - boolean + gap-list output. |
+| design-context-checker | Checker | haiku | Checks context completeness against a schema - boolean + gap-list output. |
+| design-integration-checker | Checker | haiku | Checks cross-artifact references - deterministic link-integrity work. |
+| gdd-graph-refresh | Refresh agent | haiku | Rebuilds graph at .design/graph/graph.json from intel slices - no reasoning density required. |
 | a11y-mapper | Mapper | sonnet | Open-ended a11y pattern recognition across many files; Sonnet's breadth matters. |
-| component-taxonomy-mapper | Mapper | sonnet | Classifies components by role — requires nuance Haiku lacks, not enough to warrant Opus. |
+| component-taxonomy-mapper | Mapper | sonnet | Classifies components by role - requires nuance Haiku lacks, not enough to warrant Opus. |
 | design-auditor | Worker | sonnet | Emits structured findings from code inspection; Sonnet balances depth with cost. |
-| design-context-builder | Builder | sonnet | Assembles DESIGN-CONTEXT.md from discover outputs — prose synthesis. |
+| design-context-builder | Builder | sonnet | Assembles DESIGN-CONTEXT.md from discover outputs - prose synthesis. |
 | design-doc-writer | Writer | sonnet | Produces polished prose documentation; Sonnet's style quality is sufficient. |
-| design-executor | Executor | sonnet | Follows an Opus-authored plan — executes rather than plans. |
+| design-executor | Executor | sonnet | Follows an Opus-authored plan - executes rather than plans. |
 | design-figma-writer | Writer | sonnet | Emits Figma-formatted output from existing spec. |
 | design-fixer | Fixer | sonnet | Applies targeted fixes to a localized artifact; structured input, structured diff output. |
 | design-pattern-mapper | Mapper | sonnet | Catalogs design patterns present in codebase. |
@@ -63,16 +63,16 @@ Opus cost (~5x Sonnet, ~25x Haiku) is justified only when a single wrong decisio
 | design-research-synthesizer | Synthesizer | sonnet | Collapses multiple research outputs into one; synthesis is Sonnet territory. |
 | gdd-intel-updater | Updater | sonnet | Refreshes .planning/intel/ files from current codebase. |
 | gdd-learnings-extractor | Extractor | sonnet | Pulls decisions + lessons + patterns from phase artifacts. |
-| motion-mapper | Mapper | sonnet | Inventories motion patterns — open-ended visual reasoning. |
-| token-mapper | Mapper | sonnet | Extracts design tokens from source — pattern recognition across files. |
-| visual-hierarchy-mapper | Mapper | sonnet | Maps visual hierarchy signals — breadth across many files. |
-| design-advisor | Advisor | opus | Questions prompts to surface ambiguity — wrong advice cascades. |
-| design-assumptions-analyzer | Critic | opus | Surfaces load-bearing assumptions before planning — one wrong assumption derails the phase. |
-| design-discussant | Facilitator | opus | Interactive decision gathering — user-facing, quality-critical. |
-| design-planner | Planner | opus | Authors DESIGN-PLAN.md — the contract every downstream agent follows. |
-| design-reflector | Strategic reflector | opus | Phase 11 — reads telemetry + proposes changes to the plugin itself. |
+| motion-mapper | Mapper | sonnet | Inventories motion patterns - open-ended visual reasoning. |
+| token-mapper | Mapper | sonnet | Extracts design tokens from source - pattern recognition across files. |
+| visual-hierarchy-mapper | Mapper | sonnet | Maps visual hierarchy signals - breadth across many files. |
+| design-advisor | Advisor | opus | Questions prompts to surface ambiguity - wrong advice cascades. |
+| design-assumptions-analyzer | Critic | opus | Surfaces essential assumptions before planning - one wrong assumption derails the phase. |
+| design-discussant | Facilitator | opus | Interactive decision gathering - user-facing, quality-critical. |
+| design-planner | Planner | opus | Authors DESIGN-PLAN.md - the contract every downstream agent follows. |
+| design-reflector | Strategic reflector | opus | Phase 11 - reads telemetry + proposes changes to the plugin itself. |
 
-**Row count:** 26 — matches the agent suite ls. Every row has a rationale; no blank rationales.
+**Row count:** 26 - matches the agent suite ls. Every row has a rationale; no blank rationales.
 
 ---
 
@@ -80,14 +80,14 @@ Opus cost (~5x Sonnet, ~25x Haiku) is justified only when a single wrong decisio
 
 When the budget-enforcer hook resolves which tier to spawn an agent at, it walks this precedence (D-04):
 
-1. **`.design/budget.json.tier_overrides[{agent_name}]`** — per-project configuration. Wins over frontmatter. Use this knob when the project has budget constraints that differ from the plugin defaults.
-2. **Agent frontmatter `default-tier`** (this file's per-agent map) — plugin default. Set at authoring time.
-3. **Hardcoded fallback `"sonnet"`** — belt-and-suspenders in `hooks/budget-enforcer.js` for agents that somehow lack the frontmatter field. Should never fire in practice after Phase 10.1.
+1. **`.design/budget.json.tier_overrides[{agent_name}]`** - per-project configuration. Wins over frontmatter. Use this knob when the project has budget constraints that differ from the plugin defaults.
+2. **Agent frontmatter `default-tier`** (this file's per-agent map) - plugin default. Set at authoring time.
+3. **Hardcoded fallback `"sonnet"`** - belt-and-suspenders in `hooks/budget-enforcer.js` for agents that somehow lack the frontmatter field. Should never fire in practice after Phase 10.1.
 
 Plus two modifiers that can override the above at spawn time:
 
 - **`auto_downgrade_on_cap: true`** (D-03): at 80% of `per_task_cap_usd`, the hook force-downgrades the tier to `haiku` for the remainder of the task, regardless of the precedence chain. Logged as `tier_downgraded: true` in `.design/telemetry/costs.jsonl`.
-- **Hard-cap block** (D-02): at 100% of `per_task_cap_usd` or `per_phase_cap_usd`, the hook blocks the spawn outright. Tier is irrelevant — nothing runs.
+- **Hard-cap block** (D-02): at 100% of `per_task_cap_usd` or `per_phase_cap_usd`, the hook blocks the spawn outright. Tier is irrelevant - nothing runs.
 
 ---
 
@@ -95,8 +95,8 @@ Plus two modifiers that can override the above at spawn time:
 
 The plugin ships with the Per-Agent Tier Map above as a well-reasoned baseline. **Do not hand-edit agent frontmatter `default-tier` fields without evidence.** Two legitimate paths to change a tier assignment:
 
-1. **Phase 11 reflector proposal.** `agents/design-reflector.md` reads `.design/agent-metrics.json` and surfaces cases where measured `gap_rate` or `deviation_rate` suggests a tier is too low (verifier missed gaps a Sonnet would catch) or too high (planner over-reasoned simple plans a Sonnet would handle). Proposals flow through `/gdd:apply-reflections` — user-reviewed, never auto-applied.
-2. **Budget constraint.** Project-level override via `.design/budget.json.tier_overrides` — does not require touching the frontmatter.
+1. **Phase 11 reflector proposal.** `agents/design-reflector.md` reads `.design/agent-metrics.json` and surfaces cases where measured `gap_rate` or `deviation_rate` suggests a tier is too low (verifier missed gaps a Sonnet would catch) or too high (planner over-reasoned simple plans a Sonnet would handle). Proposals flow through `/gdd:apply-reflections` - user-reviewed, never auto-applied.
+2. **Budget constraint.** Project-level override via `.design/budget.json.tier_overrides` - does not require touching the frontmatter.
 
 Signals that a tier move might be warranted (Phase 11 reflector's heuristics):
 - **Downgrade signal** (Sonnet → Haiku, or Opus → Sonnet): agent's `gap_rate < 10%` over ≥ 10 runs AND measured output length < 25% of `size_budget` ceiling → agent is over-provisioned.
@@ -108,11 +108,11 @@ Phase 11's reflector encodes these heuristics. This section documents the philos
 
 ## Integration Points
 
-- **`hooks/budget-enforcer.js`** (Plan 10.1-01 Task 04) — implements the precedence chain above. `resolveTier(agent, agentDefaultTier, overrides)` is the concrete function.
-- **`skills/router/SKILL.md`** (Plan 10.1-01 Task 03) — consults this file's tier map + `reference/model-prices.md` to produce `estimated_cost_usd` pre-spawn.
-- **`skills/optimize/SKILL.md`** (Plan 10.1-04) — advisory command; may suggest tier moves based on telemetry + this doc's heuristics.
-- **`agents/design-reflector.md`** (Phase 11, already merged) — may propose edits to this file + paired frontmatter updates. Proposals land in `.design/reflections/` for user review.
+- **`hooks/budget-enforcer.js`** (Plan 10.1-01 Task 04) - implements the precedence chain above. `resolveTier(agent, agentDefaultTier, overrides)` is the concrete function.
+- **`skills/router/SKILL.md`** (Plan 10.1-01 Task 03) - consults this file's tier map + `reference/model-prices.md` to produce `estimated_cost_usd` pre-spawn.
+- **`skills/optimize/SKILL.md`** (Plan 10.1-04) - advisory command; may suggest tier moves based on telemetry + this doc's heuristics.
+- **`agents/design-reflector.md`** (Phase 11, already merged) - may propose edits to this file + paired frontmatter updates. Proposals land in `.design/reflections/` for user review.
 
 ---
 
-*Maintained as part of Phase 10.1 (OPT-06). Edits to the Per-Agent Tier Map MUST be paired with matching frontmatter edits in `agents/*.md` — the two are the same fact stored twice (router cross-checks). A mismatch indicates drift; Phase 11 reflector detects and reports it.*
+*Maintained as part of Phase 10.1 (OPT-06). Edits to the Per-Agent Tier Map MUST be paired with matching frontmatter edits in `agents/*.md` - the two are the same fact stored twice (router cross-checks). A mismatch indicates drift; Phase 11 reflector detects and reports it.*

package/reference/motion-advanced.md

@@ -10,9 +10,9 @@
 
 Spring animations are governed by three parameters that model a physical spring:
 
-- **stiffness** — how tightly wound the spring is; higher = faster, snappier response
-- **damping** — friction applied to the oscillation; higher = settles faster with less bounce
-- **mass** — inertia of the object; higher = slower start and more overshoot
+- **stiffness** - how tightly wound the spring is; higher = faster, snappier response
+- **damping** - friction applied to the oscillation; higher = settles faster with less bounce
+- **mass** - inertia of the object; higher = slower start and more overshoot
 
 The damping ratio `ζ = damping / (2 * Math.sqrt(stiffness * mass))` determines behavior:
 
@@ -222,10 +222,10 @@ el.animate(
 
 ### The Four Steps
 
-1. **First** — record the element's current bounding rect (`getBoundingClientRect()`)
-2. **Last** — apply the DOM change, then record the new rect
-3. **Invert** — set a CSS transform that moves the element back to its "First" position
-4. **Play** — animate the transform to identity (`0, 0, scale(1)`)
+1. **First** - record the element's current bounding rect (`getBoundingClientRect()`)
+2. **Last** - apply the DOM change, then record the new rect
+3. **Invert** - set a CSS transform that moves the element back to its "First" position
+4. **Play** - animate the transform to identity (`0, 0, scale(1)`)
 
 ```ts
 function flip(el: HTMLElement, applyChange: () => void) {
@@ -577,7 +577,7 @@ function CompareSlider({ before, after }: { before: string; after: string }) {
 
 ## Blur-to-Mask Crossfades
 
-Use a short `filter: blur()` during state transitions to bridge the visual gap between two overlapping states — it softens the hard edge that appears when opacity alone creates a ghost.
+Use a short `filter: blur()` during state transitions to bridge the visual gap between two overlapping states - it softens the hard edge that appears when opacity alone creates a ghost.
 
 ```tsx
 <motion.div
@@ -591,10 +591,10 @@ Use a short `filter: blur()` during state transitions to bridge the visual gap b
 ```
 
 **Rules:**
-- Cap blur under 20px on non-animated elements — Safari allocates GPU memory per blurred layer, causing stutter at high values
+- Cap blur under 20px on non-animated elements - Safari allocates GPU memory per blurred layer, causing stutter at high values
 - Pair with `scale(0.97)` for press feedback; the scale signals physical depth while blur softens content churn
 - Use for: skeleton → content, loading → loaded image, optimistic update → confirmed state
-- Do NOT use for layout shifts — blur does not mask reflow artifacts
+- Do NOT use for layout shifts - blur does not mask reflow artifacts
 
 ---
 
@@ -710,7 +710,7 @@ Motion values are a **design decision**, not a technical default. They communica
 | Interruptible UI (toggles, toasts) | `bounce: 0`, transitions not keyframes | Must retarget without pop |
 | Height + opacity combos | Trial and error per library | `height: auto` is not animatable in CSS; each library handles it differently |
 
-**Do not mix** snappy dashboard animations with bouncy spring animations in the same product — the conflicting personalities create a sense that the UI was assembled from parts.
+**Do not mix** snappy dashboard animations with bouncy spring animations in the same product - the conflicting personalities create a sense that the UI was assembled from parts.
 
 ---
 
@@ -744,7 +744,7 @@ Fresh eyes catch what in-the-moment iteration misses. Animations feel correct wh
 
 ---
 
-## Disney's 12 Principles — UX Mapping
+## Disney's 12 Principles - UX Mapping
 
 Original source: Frank Thomas & Ollie Johnston, *The Illusion of Life: Disney Animation* (1981). The 12 principles were developed for hand-drawn character animation; the UX mappings below translate each to interface motion.
 
@@ -752,7 +752,7 @@ Original source: Frank Thomas & Ollie Johnston, *The Illusion of Life: Disney An
 
 ### 1. Squash and Stretch
 
-**Animation:** Objects deform under force — squash on impact, stretch during fast movement.
+**Animation:** Objects deform under force - squash on impact, stretch during fast movement.
 
 **UX mapping:** Scale feedback communicates physical weight and responsiveness.
 ```tsx
@@ -763,7 +763,7 @@ Original source: Frank Thomas & Ollie Johnston, *The Illusion of Life: Disney An
   transition={{ type: "spring", stiffness: 500, damping: 30 }}
 />
 ```
-**Rule:** Constrain squash/stretch to ≤5% deviation — more reads as glitchy, not physical.
+**Rule:** Constrain squash/stretch to ≤5% deviation - more reads as glitchy, not physical.
 
 ---
 
@@ -799,7 +799,7 @@ Original source: Frank Thomas & Ollie Johnston, *The Illusion of Life: Disney An
 
 **Animation:** Straight-ahead: draw each frame in sequence. Pose-to-pose: define key positions and interpolate.
 
-**UX mapping:** All CSS transitions and spring animations are pose-to-pose by definition — you define start and end states. This means:
+**UX mapping:** All CSS transitions and spring animations are pose-to-pose by definition - you define start and end states. This means:
 - Transitions retarget smoothly when interrupted (see CSS Transitions vs Keyframes section above)
 - The in-between frames are computed by the engine, not designed
 - Design the **poses** (states) carefully; the interpolation handles itself
@@ -872,7 +872,7 @@ transition: transform 0.2s cubic-bezier(0.4, 0, 1, 1);
 - Success state: checkmark draws itself after the confirmation color appears
 - Delete: item fades + the list count badge decrements with a small number-flip animation
 
-**Rule:** Secondary actions must complete before or simultaneously with the primary — never after. They reinforce, not extend.
+**Rule:** Secondary actions must complete before or simultaneously with the primary - never after. They reinforce, not extend.
 
 ---
 
@@ -915,17 +915,17 @@ transition: transform 0.2s cubic-bezier(0.4, 0, 1, 1);
 
 **Animation:** Characters have weight, depth, and obey perspective; they feel three-dimensional.
 
-**UX mapping:** UI elements should feel visually grounded — not floating. Shadows, depth layering, and transform-origin choices communicate which layer an element lives on.
-- Drawers and sheets slide from an edge — they feel physically attached
-- Modals emerge from center or from the triggering element — they float above the page
-- Tooltips appear near the cursor — they are attached to the pointer
+**UX mapping:** UI elements should feel visually grounded - not floating. Shadows, depth layering, and transform-origin choices communicate which layer an element lives on.
+- Drawers and sheets slide from an edge - they feel physically attached
+- Modals emerge from center or from the triggering element - they float above the page
+- Tooltips appear near the cursor - they are attached to the pointer
 - `transform-origin` must match where the element conceptually emerges from
 
 ---
 
 ### 12. Appeal
 
-**Animation:** Characters have a quality that makes the audience want to watch them — not necessarily cute, but interesting.
+**Animation:** Characters have a quality that makes the audience want to watch them - not necessarily cute, but interesting.
 
 **UX mapping:** Animation has personality that is consistent with the product's brand.
 

package/reference/motion-easings.md

@@ -9,23 +9,23 @@ Canonical easing curve presets derived from React Native's `Easing` module, adap
 
 | Token | CSS `cubic-bezier` | Character | Settle (spring/bounce) |
 |---|---|---|---|
-| `--ease-linear` | `cubic-bezier(0,0,1,1)` | Constant rate | — |
-| `--ease-quad-in` | `cubic-bezier(0.55,0,1,1)` | Slow start | — |
-| `--ease-quad-out` | `cubic-bezier(0,0,0.45,1)` | Slow end | — |
-| `--ease-quad-in-out` | `cubic-bezier(0.455,0.03,0.515,0.955)` | Slow both | — |
-| `--ease-cubic-in` | `cubic-bezier(0.55,0.055,0.675,0.19)` | Aggressive start | — |
-| `--ease-cubic-out` | `cubic-bezier(0.215,0.61,0.355,1)` | Aggressive end | — |
-| `--ease-cubic-in-out` | `cubic-bezier(0.645,0.045,0.355,1)` | Strong S-curve | — |
-| `--ease-sin-in` | `cubic-bezier(0.47,0,0.745,0.715)` | Gentle start | — |
-| `--ease-sin-out` | `cubic-bezier(0.39,0.575,0.565,1)` | Gentle end | — |
-| `--ease-sin-in-out` | `cubic-bezier(0.445,0.05,0.55,0.95)` | Smooth S-curve | — |
-| `--ease-circle-in` | `cubic-bezier(0.6,0.04,0.98,0.335)` | Circular arc start | — |
-| `--ease-circle-out` | `cubic-bezier(0.075,0.82,0.165,1)` | Circular arc end | — |
-| `--ease-exp-in` | `cubic-bezier(0.95,0.05,0.795,0.035)` | Explosive start | — |
-| `--ease-exp-out` | `cubic-bezier(0.19,1,0.22,1)` | Explosive end | — |
+| `--ease-linear` | `cubic-bezier(0,0,1,1)` | Constant rate | - |
+| `--ease-quad-in` | `cubic-bezier(0.55,0,1,1)` | Slow start | - |
+| `--ease-quad-out` | `cubic-bezier(0,0,0.45,1)` | Slow end | - |
+| `--ease-quad-in-out` | `cubic-bezier(0.455,0.03,0.515,0.955)` | Slow both | - |
+| `--ease-cubic-in` | `cubic-bezier(0.55,0.055,0.675,0.19)` | Aggressive start | - |
+| `--ease-cubic-out` | `cubic-bezier(0.215,0.61,0.355,1)` | Aggressive end | - |
+| `--ease-cubic-in-out` | `cubic-bezier(0.645,0.045,0.355,1)` | Strong S-curve | - |
+| `--ease-sin-in` | `cubic-bezier(0.47,0,0.745,0.715)` | Gentle start | - |
+| `--ease-sin-out` | `cubic-bezier(0.39,0.575,0.565,1)` | Gentle end | - |
+| `--ease-sin-in-out` | `cubic-bezier(0.445,0.05,0.55,0.95)` | Smooth S-curve | - |
+| `--ease-circle-in` | `cubic-bezier(0.6,0.04,0.98,0.335)` | Circular arc start | - |
+| `--ease-circle-out` | `cubic-bezier(0.075,0.82,0.165,1)` | Circular arc end | - |
+| `--ease-exp-in` | `cubic-bezier(0.95,0.05,0.795,0.035)` | Explosive start | - |
+| `--ease-exp-out` | `cubic-bezier(0.19,1,0.22,1)` | Explosive end | - |
 | `--ease-elastic` | `linear(...)` baked | Overshoot + settle | ~500ms |
-| `--ease-back-in` | `cubic-bezier(0.6,-0.28,0.735,0.045)` | Anticipation | — |
-| `--ease-back-out` | `cubic-bezier(0.175,0.885,0.32,1.275)` | Overshoot | — |
+| `--ease-back-in` | `cubic-bezier(0.6,-0.28,0.735,0.045)` | Anticipation | - |
+| `--ease-back-out` | `cubic-bezier(0.175,0.885,0.32,1.275)` | Overshoot | - |
 | `--ease-bounce-out` | `linear(...)` baked | Bounces at end | ~420ms |
 
 ---
@@ -60,7 +60,7 @@ Easing.linear
 
 ### `quad`
 
-Quadratic — acceleration proportional to `t²`.
+Quadratic - acceleration proportional to `t²`.
 
 - **Human name:** Quad (ease-in-out)
 - **Character:** Subtle, polished. Most common choice for UI transitions.
@@ -85,7 +85,7 @@ Easing.inOut(Easing.quad)
 
 ### `cubic`
 
-Cubic — acceleration proportional to `t³`. More pronounced than quad.
+Cubic - acceleration proportional to `t³`. More pronounced than quad.
 
 - **Human name:** Cubic (ease-in-out)
 - **Character:** Snappy, decisive. Good for panels, drawers, menus.
@@ -109,7 +109,7 @@ Easing.inOut(Easing.cubic)
 
 ### `poly(n)`
 
-Generalised polynomial — `t^n`. Quad is `poly(2)`, cubic is `poly(3)`.
+Generalised polynomial - `t^n`. Quad is `poly(2)`, cubic is `poly(3)`.
 
 - **Human name:** Poly-n
 - **Character:** Tunable. Higher `n` = harder snap.
@@ -121,13 +121,13 @@ Easing.poly(5)   // quintic
 Easing.in(Easing.poly(4))
 ```
 
-No direct CSS equivalent — approximate with a `cubic-bezier` or bake to `linear()`.
+No direct CSS equivalent - approximate with a `cubic-bezier` or bake to `linear()`.
 
 ---
 
 ### `sin`
 
-Sinusoidal — easing shaped by the sine function. Smooth and natural.
+Sinusoidal - easing shaped by the sine function. Smooth and natural.
 
 - **Human name:** Sine
 - **Character:** Organic, gentle. Works well for ambient or breathing animations.
@@ -150,7 +150,7 @@ Easing.sin
 
 ### `circle`
 
-Circular arc — based on `sqrt(1 - t²)`. Sharp acceleration at the end of its range.
+Circular arc - based on `sqrt(1 - t²)`. Sharp acceleration at the end of its range.
 
 - **Human name:** Circ
 - **Character:** Abrupt, dramatic. Use sparingly for emphasis.
@@ -172,7 +172,7 @@ Easing.circle
 
 ### `exp`
 
-Exponential — `2^(10 * (t - 1))`. Starts near-zero, ends explosively.
+Exponential - `2^(10 * (t - 1))`. Starts near-zero, ends explosively.
 
 - **Human name:** Expo
 - **Character:** High-impact. Good for reveal animations, hero entrances.
@@ -226,7 +226,7 @@ Easing.out(Easing.elastic(1, 1))
 
 ### `back(s)`
 
-Anticipation curve — slightly retracts before moving forward (or overshoots then settles).
+Anticipation curve - slightly retracts before moving forward (or overshoots then settles).
 
 - **Human name:** Back
 - **Character:** Mechanical delight. Communicates intentionality.
@@ -250,7 +250,7 @@ Easing.out(Easing.back(2.5))   // stronger overshoot
 
 ### `bounce`
 
-Simulates a physical bounce — the value bounces off the endpoint.
+Simulates a physical bounce - the value bounces off the endpoint.
 
 - **Human name:** Bounce
 - **Character:** Playful, energetic. Use for game-like or informal UIs.
@@ -278,7 +278,7 @@ Easing.bounce
 
 ### `bezier(x1, y1, x2, y2)`
 
-Raw cubic Bézier — the same primitive that powers all CSS `cubic-bezier()` calls.
+Raw cubic Bézier - the same primitive that powers all CSS `cubic-bezier()` calls.
 
 - **Human name:** Custom Bézier
 - **Character:** Whatever you specify.
@@ -307,8 +307,8 @@ Given a base easing function `f(t)` where `t ∈ [0, 1]`:
 
 | Wrapper | Formula | Effect |
 |---|---|---|
-| `in(f)` | `f(t)` | Acceleration at start — slow → fast |
-| `out(f)` | `1 - f(1 - t)` | Deceleration at end — fast → slow |
+| `in(f)` | `f(t)` | Acceleration at start - slow → fast |
+| `out(f)` | `1 - f(1 - t)` | Deceleration at end - fast → slow |
 | `inOut(f)` | `t < 0.5 ? f(2t)/2 : 1 - f(2(1-t))/2` | Slow start and end |
 
 ### Examples
@@ -340,7 +340,7 @@ const easeInElastic = easeIn(elastic(1, 1));
 
 ---
 
-## CSS Custom Properties — Full Token Set
+## CSS Custom Properties - Full Token Set
 
 ```css
 :root {

package/reference/motion-interpolate.md

@@ -3,7 +3,7 @@
 
 # Motion Interpolation
 
-Interpolation is the mechanism that maps any changing value — progress, scroll position, pointer delta, elapsed time — into any animated output range. Every animation in a system can be decomposed into a single canonical form.
+Interpolation is the mechanism that maps any changing value - progress, scroll position, pointer delta, elapsed time - into any animated output range. Every animation in a system can be decomposed into a single canonical form.
 
 ---
 

package/reference/motion-spring.md

@@ -3,7 +3,7 @@
 
 # Motion Springs
 
-Spring animations model physical mass-spring-damper systems. Unlike tween animations, springs are driven by physics rather than duration — they respond to velocity and settle naturally, making them ideal for interactions that require a sense of weight.
+Spring animations model physical mass-spring-damper systems. Unlike tween animations, springs are driven by physics rather than duration - they respond to velocity and settle naturally, making them ideal for interactions that require a sense of weight.
 
 ---
 
@@ -13,7 +13,7 @@ Every spring is defined by three parameters:
 
 ### Stiffness (`k`)
 
-The spring constant — how strongly the spring pulls toward the target.
+The spring constant - how strongly the spring pulls toward the target.
 
 - **Low stiffness** (80–150): soft, gentle, slow to accelerate
 - **Medium stiffness** (150–300): standard UI feel
@@ -25,7 +25,7 @@ Higher stiffness = faster animation, more acceleration. Does not affect whether
 
 ### Damping (`c`)
 
-The friction coefficient — how quickly oscillation energy is removed.
+The friction coefficient - how quickly oscillation energy is removed.
 
 - **Low damping relative to stiffness**: spring oscillates (undershooted)
 - **Damping at critical value**: spring settles exactly without oscillation
@@ -95,7 +95,7 @@ stiffness: 180  |  damping: 12  |  mass: 1
 settle time: ~600ms  |  overshoots: yes (pronounced, 2–3 cycles)
 ```
 
-High energy, bouncy. Use for playful or expressive interactions — celebratory states, game-like UIs, avatar reactions. Not appropriate for productivity or enterprise UIs.
+High energy, bouncy. Use for playful or expressive interactions - celebratory states, game-like UIs, avatar reactions. Not appropriate for productivity or enterprise UIs.
 
 ```js
 // Framer Motion
@@ -133,7 +133,7 @@ stiffness: 280  |  damping: 60  |  mass: 1
 settle time: ~800ms  |  overshoots: no (overdamped)
 ```
 
-Overdamped spring — creeps gently to target with no oscillation. Feels heavy and deliberate. Good for large layout changes, full-screen transitions, onboarding sequences.
+Overdamped spring - creeps gently to target with no oscillation. Feels heavy and deliberate. Good for large layout changes, full-screen transitions, onboarding sequences.
 
 ```js
 // Framer Motion
@@ -203,17 +203,17 @@ The baked approximation loses velocity responsiveness (a real spring reacts to i
 
 ### Use spring when:
 
-- **Drag release / throw** — the animation should carry the momentum from the gesture. Springs naturally handle initial velocity; tweens cannot.
-- **Toggle state** — a checkbox, switch, or button that needs to feel responsive and alive. The `stiff` preset is standard here.
-- **Interactive hover / follow** — cursor-tracking, magnetic elements. Springs give a sense of physical weight.
-- **Interrupt-safe sequences** — if the user reverses a motion mid-way, springs handle the reversal gracefully by inheriting the current velocity.
+- **Drag release / throw** - the animation should carry the momentum from the gesture. Springs naturally handle initial velocity; tweens cannot.
+- **Toggle state** - a checkbox, switch, or button that needs to feel responsive and alive. The `stiff` preset is standard here.
+- **Interactive hover / follow** - cursor-tracking, magnetic elements. Springs give a sense of physical weight.
+- **Interrupt-safe sequences** - if the user reverses a motion mid-way, springs handle the reversal gracefully by inheriting the current velocity.
 
 ### Use tween (eased duration) when:
 
-- **Navigation transitions** — page or route changes should complete in a fixed, predictable time. A spring may not settle in time if interrupted.
-- **Data-driven state changes** — tab switches, accordion open/close, tooltip appear. A 200–300ms cubic-out tween is predictable and familiar.
-- **Reduced motion** — when `prefers-reduced-motion` is active, replace all springs with short (150ms) linear or ease-out tweens. Springs are inherently bouncy; motion-sensitive users should never see oscillation.
-- **Synchronized choreography** — when multiple elements must start and end together (e.g., a staggered list entrance), tweens with explicit durations are easier to coordinate.
+- **Navigation transitions** - page or route changes should complete in a fixed, predictable time. A spring may not settle in time if interrupted.
+- **Data-driven state changes** - tab switches, accordion open/close, tooltip appear. A 200–300ms cubic-out tween is predictable and familiar.
+- **Reduced motion** - when `prefers-reduced-motion` is active, replace all springs with short (150ms) linear or ease-out tweens. Springs are inherently bouncy; motion-sensitive users should never see oscillation.
+- **Synchronized choreography** - when multiple elements must start and end together (e.g., a staggered list entrance), tweens with explicit durations are easier to coordinate.
 
 ```css
 @media (prefers-reduced-motion: reduce) {