@hegemonart/get-design-done 1.14.7 → 1.15.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). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.14.7"
+    "version": "1.15.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.",
-      "version": "1.14.7",
+      "version": "1.15.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.14.7",
+  "version": "1.15.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.",
   "author": {
     "name": "hegemonart",
@@ -52,7 +52,19 @@
     "schema-validation",
     "cost-optimization",
     "cache-aware",
-    "budget"
+    "budget",
+    "iconography",
+    "brand-voice",
+    "performance-budget",
+    "framer-motion",
+    "motion-design",
+    "micro-polish",
+    "surfaces",
+    "make-interfaces-feel-better",
+    "palette-catalog",
+    "style-vocabulary",
+    "industry-palettes",
+    "ui-style-vocabulary"
   ],
   "skills": ["./skills/"]
 }

package/CHANGELOG.md

@@ -4,6 +4,90 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.15.0] — 2026-04-24
+
+### Added — Design Knowledge Expansion: 10 foundational references + MIFB micro-polish + UUPM ingest
+
+This release closes the plugin's shallow-coverage gaps across iconography, performance, brand voice, visual hierarchy, Gestalt principles, design-system governance, and adds two new UUPM-sourced knowledge bases (palette catalog + style vocabulary). It also lands the complete MIT-licensed MIFB (make-interfaces-feel-better) micro-polish track.
+
+#### Impeccable removal
+
+All `impeccable-*` skill coupling removed from the plugin. References in `reference/checklists.md` and `reference/review-format.md` replaced with native GDD equivalents (`DESIGN-CONTEXT.md`, `/gdd:fast`, `design:design-critique`). Salvage archive at `.planning/research/impeccable-salvage/` for Phase 16.
+
+#### 10 new foundational reference files
+
+- **`reference/iconography.md`** — Optical sizing, stroke-weight rules, metaphor taxonomy (functional/status/nav/brand), dark-mode variants, icon animation guidelines, semantic vs. decorative labeling, touch-target pairing, catalog of 9 public icon libraries (Lucide, Phosphor, Heroicons, Radix Icons, Tabler, Iconoir, Remix, SF Symbols, Feather). Metaphor taxonomy absorbs UUPM `icons.csv` (MIT).
+- **`reference/performance.md`** — Core Web Vitals targets by project type (SaaS/marketing/e-commerce/docs/dashboards), LCP/INP/CLS/TTFB budgets, critical CSS, image budgets, animation frame budget (16.67ms), JS bundle budgets (<170KB gzipped), font budgets, Lighthouse CI hookup. React runtime section absorbs UUPM `react-performance.csv` (MIT).
+- **`reference/design-systems-catalog.md`** — Quick-reference index of 18 major design systems: Material 3, Apple HIG, Radix+WAI-ARIA, shadcn/ui, Polaris, Carbon, Fluent 2, Primer, Atlassian, Ant Design, Mantine, Chakra, Base Web, Nord, Spectrum, Lightning, Evergreen, Gestalt (Pinterest).
+- **`reference/brand-voice.md`** — 5 voice axes (Formal↔Casual, Serious↔Playful, Expert↔Approachable, Reverent↔Irreverent, Authoritative↔Collaborative), 12 Jungian archetypes + 6 design-register variants, tone-by-context table (8 contexts), 20+ industry-vertical context table. Industry-context absorbs UUPM `products.csv` + `ui-reasoning.csv` (MIT).
+- **`reference/visual-hierarchy-layout.md`** — Z-order/depth cues, whitespace principles, asymmetry/rhythm, compositional grids (4/8/12/16-col), figure-ground, reading-order patterns (F/Z/inverted-triangle), progressive disclosure. Landing-archetypes subsection absorbs UUPM `landing.csv` (24 patterns, MIT).
+- **`reference/gestalt.md`** — All 8 Gestalt principles (Proximity, Similarity, Continuity, Closure, Figure-Ground, Common Fate, Common Region, Prägnanz), each with definition, design application, scoring rubric, and CSS grep signatures. UUPM `ux-guidelines.csv` deduped across gestalt/heuristics/anti-patterns/priority-matrix (MIT).
+- **`reference/design-system-guidance.md`** — Token versioning/deprecation, multi-brand token architecture (base/semantic/component layers), platform translation (Style Dictionary/Tokens Studio/Terrazzo), governance/RFC model, documentation standard, maturity rubric levels 0–5.
+- **`reference/framer-motion-patterns.md`** — Spring vs. tween config, AnimatePresence (including `initial={false}` rule), layout animations, variants+staggering, gesture motion (`whileHover`, `whileTap` canonical 0.96), scroll-linked animations, `prefers-reduced-motion` compliance, 60fps GPU-safe property rules, MotionConfig, common pitfalls. UUPM `stacks/react.csv` framer rows absorbed (MIT).
+- **`reference/palette-catalog.md`** — 40+ industry-vertical color palettes with 12 semantic token roles each, all WCAG 4.5:1 body / 3:1 UI verified. Data sibling at `reference/data/palettes.csv`. UUPM `colors.csv` absorbed (MIT).
+- **`reference/style-vocabulary.md`** — 38+ named UI aesthetics (Glassmorphism, Brutalism, Neumorphism, Bento, Claymorphism, Aurora, AI-Native, Swiss Modernism 2.0, Vaporwave, Editorial Grid, HUD/Sci-Fi FUI, and more) with keywords, signature effects, best-for, avoid-for, era. Data sibling at `reference/data/styles.csv`. UUPM `styles.csv` absorbed (MIT).
+
+#### MIFB micro-polish track
+
+Source: [jakub.kr/writing/details-that-make-interfaces-feel-better](https://jakub.kr/writing/details-that-make-interfaces-feel-better) (MIT, Jakub Krehel)
+
+- **`reference/surfaces.md`** (new) — Concentric radius formula (`outerRadius = innerRadius + padding`), optical alignment offsets, 3-layer shadow system (exact `rgba` values), image outline rule (pure black/white opacity only), hit-area `::after` pseudo-element pattern.
+- **`reference/typography.md`** extended — `text-wrap: balance` (headings, ≤6 lines Chromium), `text-wrap: pretty` (body/captions), `-webkit-font-smoothing: antialiased` at `:root` only, `font-variant-numeric: tabular-nums` for dynamic numerals. UUPM `typography.csv` (57 pairings) absorbed into expanded pairings catalog (MIT). `reference/data/google-fonts.csv` registered as data sibling.
+- **`reference/motion.md`** extended — 6 new subsections: interruptible animations (transitions vs. keyframes decision table), split-and-stagger enter/exit pattern, contextual icon cross-fade (canonical `scale 0.25→1`, `opacity 0→1`, `blur 4→0`, `bounce: 0`), scale-on-press canonical `0.96`, `<AnimatePresence initial={false}>` rule, `will-change` GPU-compositable property table.
+- **`reference/anti-patterns.md`** — 4 new BAN entries: BAN-10 same-radius-nested, BAN-11 tinted image outline, BAN-12 `transition: all`, BAN-13 `will-change: all`. Each with grep signature and fix pointer.
+- **`reference/checklists.md`** — New "Micro-polish check" gate (14 items across typography/surfaces/motion). `scale(0.97)` mention reconciled to canonical `0.96`.
+
+#### ⚠️ BREAKING — 7th audit pillar: Micro-polish (weight redistribution)
+
+A new **Micro-polish** pillar (5%) has been added to `reference/audit-scoring.md`. Weight was redistributed from the Anti-Pattern Compliance pillar (10% → 5%). **Total remains 100%, but per-pillar weights changed.** Cross-cycle score comparisons that mix v1.14.x and v1.15.0 audit reports should account for this weight shift.
+
+#### Mapper extensions
+
+All four mapper agents (`motion-mapper`, `token-mapper`, `visual-hierarchy-mapper`, `a11y-mapper`) gain "Micro-polish findings" output sections with grep-driven detection of BAN-10/11/12/13 and MIFB rule violations.
+
+#### Agent integrations
+
+- `design-context-builder` — reads `brand-voice.md` for archetype resolution, `palette-catalog.md` for palette proposal, `style-vocabulary.md` for style-direction picker.
+- `design-auditor` — reads `iconography.md`, `performance.md`, `gestalt.md`, `framer-motion-patterns.md`, `surfaces.md`; includes 7th pillar micro_polish in output schema.
+- `design-executor` — reads `brand-voice.md` (type:copy), `design-system-guidance.md` (type:tokens), `framer-motion-patterns.md` (type:motion), `performance.md` (type:layout).
+- `design-pattern-mapper` — extended with `iconography-system` and `brand-voice` categories.
+- `design-verifier` — micro_polish added as supplemental dimension.
+
+#### Attribution
+
+- Jakub Krehel (MIT) — micro-polish rules in typography.md, surfaces.md, motion.md, anti-patterns.md BAN-10/11/12/13, checklists.md Micro-polish gate.
+- nextlevelbuilder/ui-ux-pro-max-skill v2.5.0 (MIT) — data snapshot ingested into iconography, performance, brand-voice, visual-hierarchy-layout, typography, framer-motion-patterns, palette-catalog, style-vocabulary, gestalt/heuristics/anti-patterns/priority-matrix dedup. **One-shot snapshot — no live re-sync contract.**
+
+#### UUPM deferrals (explicitly routed, not discarded)
+
+- `charts.csv` → Phase 19 `reference/data-visualization.md`
+- `app-interface.csv` → Phase 17 component-corpus authoring
+- `stacks/*.csv` (14 non-React) → future stack-playbook phase
+## [1.14.8] — 2026-04-24
+
+### Added — Phase 14.7 First-Run Proof Path
+
+A new user can now install the plugin, run one command, and see GDD inspect their own UI code in under five minutes — with a concrete "first fix" pointer on the way out.
+
+- **`/gdd:start` skill** (`skills/start/SKILL.md`) — leaf command with a locked 5-question interview (`reference/start-interview.md`) that collects pain hint, target-area confirmation, budget preference, framework/design-system confirmation, and visual-workflow selection. Writes only `.design/START-REPORT.md` and a temporary `.design/.start-context.json`; never mutates `STATE.md`, `config.json`, or source files.
+- **`detect-ui-root` helper** (`scripts/lib/detect-ui-root.cjs`) — deterministic priority-ordered detector that identifies the user's UI surface across `packages/ui/src/`, `apps/*/components/`, Next.js app-router `app/components/`, Vite `src/components/`, CRA `src/components/`, root `components/`, and Svelte/Remix `src/routes/`. Backend-only repos get a clean diagnostic and exit with zero `.design/` footprint.
+- **`start-findings-engine` helper** (`scripts/lib/start-findings-engine.cjs`) — read-only scanner with seven regex-based detectors (transition-all, will-change-all, tinted-image-outline, scale-on-press-drift, same-radius-nested, missing-reduced-motion-guard, non-root-font-smoothing), budget-bounded walk (fast / balanced / thorough), and a deterministic **safe-fix rubric** that picks exactly one `best_first_proof` per report.
+- **`design-start-writer` agent** (`agents/design-start-writer.md`) — Haiku-tier writer with `allowed-write-paths: [.design/START-REPORT.md]`. Output contract locks seven H2 sections (`What I inspected`, `Three findings`, `Best first proof`, `Suggested next command`, `Visual Proof Readiness`, `Full pipeline path`, `Connections / writeback optional`) plus one trailing machine-readable JSON block that future `/gdd:fast` / `/gdd:do` invocations can consume.
+- **First-run nudge** (`hooks/first-run-nudge.sh`) — SessionStart hook that surfaces one restrained line pointing at `/gdd:start` only when `.design/config.json` is absent, no dismissal flag exists, and no active pipeline stage is in progress. Per-install dismissal lives at `~/.claude/gdd-nudge-dismissed`. Silent-on-failure posture inherited from Phase 13.3.
+- **Regression fixtures** at `test-fixture/baselines/phase-14.7/` (context-input.json, expected-report-shape.md) and `test-fixture/src/ui-detection/` covering Next.js, Vite, CRA, Remix, two monorepo shapes, backend-only, and empty-repo paths.
+- **Plugin keywords** extended with `onboarding`, `first-run`, `demo`, `proof-path`.
+
+### Non-breaking
+
+Phase 15 target version unchanged (`v1.15.0`). `v1.14.6` remains reserved for Phase 14.6 (test-coverage-completion); this release does not block or reshape that phase.
+
+### Scope notes
+
+- The first-run report **recommends** commands; it never auto-applies fixes. `/gdd:fast` suggestions are printed as ready-to-run text.
+- `/gdd:do` is intentionally **not** surfaced as a suggested command in v1.14.8 (revisit at Phase 15 per Phase 14.7 D-05).
+
+---
+
 ## [1.14.7] — 2026-04-24
 
 ### Phase 14.6 — Test Coverage Completion (Phase 12 Wave C closeout)

package/README.md

@@ -76,6 +76,13 @@ You don't need to be a designer. The pipeline carries the design expertise so yo
 
 Built-in quality gates catch real problems: Handoff Faithfulness scoring on Claude Design bundles, contrast audits across the full palette × surface matrix, anti-pattern detection from the NNG catalog, dark-mode architecture verification, and motion-system consistency checks.
 
+### v1.15.0 Highlights — Design Knowledge Expansion
+
+- **10 new foundational references** — `iconography.md`, `performance.md`, `brand-voice.md`, `visual-hierarchy-layout.md`, `gestalt.md`, `design-system-guidance.md`, `design-systems-catalog.md`, `framer-motion-patterns.md`, `palette-catalog.md`, `style-vocabulary.md`. Agents now have authoritative answers on icon sizing, Web Vitals budgets, brand voice axes, Gestalt principles, DS governance, and 40+ industry-vertical color palettes.
+- **MIFB micro-polish track** — MIT content from [Jakub Krehel](https://jakub.kr/writing/details-that-make-interfaces-feel-better): new `reference/surfaces.md` (concentric radius, 3-layer shadow), `text-wrap: balance/pretty`, canonical press scale `0.96`, `AnimatePresence initial={false}`, `bounce: 0` icon cross-fade, and 4 new BAN entries. All four mapper agents gain "Micro-polish findings" detection. New 7th audit pillar: **Micro-polish** (5%).
+- **UUPM data ingest** — One-shot MIT snapshot from [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) v2.5.0: icon metaphor taxonomy, React perf heuristics, 20+ industry verticals, 24 landing-page archetypes, 57 font pairings, 40+ WCAG-verified palettes, 38+ UI aesthetic styles — all rewritten in GDD voice.
+- **⚠️ Breaking** — 7th audit pillar changes Anti-Pattern Compliance weight (10%→5%). Cross-cycle score comparisons spanning v1.14.x and v1.15.0 should account for this weight shift.
+
 ### v1.14.0 Highlights
 
 - **AI-native canvas tools** — paper.design (MCP canvas read/write, screenshot verification) and pencil.dev (git-tracked `.pen` spec files, no MCP required) complete a full canvas→code→verify→canvas round-trip.
@@ -101,6 +108,16 @@ That's it. The installer writes a `get-design-done` marketplace entry and enable
 
 On first Claude Code launch after install, a `SessionStart` bootstrap hook provisions the companion reference library `~/.claude/libs/awesome-design-md` (idempotent — subsequent sessions run `git pull --ff-only`).
 
+### First run — `/gdd:start` *(v1.14.7+)*
+
+```
+/gdd:start
+```
+
+Run this once in any frontend repo. The skill asks five short questions, scans your `components/` directory (with framework-aware fallback for `src/components/`, `app/components/`, `packages/ui/`, `apps/*/components/`), and writes `.design/START-REPORT.md` with three concrete findings — each with file:line evidence — plus one `best_first_proof` and a single suggested next command. Takes ≤5 minutes, never touches source code, and never enters the pipeline state machine.
+
+A one-line SessionStart nudge surfaces `/gdd:start` in fresh repos; run `/gdd:start --dismiss-nudge` to silence it per install.
+
 ### Non-interactive install (CI, Docker, scripts)
 
 ```bash
@@ -525,6 +542,7 @@ All commands use the `/gdd:` namespace.
 
 | Command | What it does |
 |---------|--------------|
+| `/gdd:start [--budget] [--skip-interview] [--dismiss-nudge]` | First-Run Proof Path — scans UI code, emits `.design/START-REPORT.md`, never enters pipeline state |
 | `/gdd:new-project [--name]` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
 | `/gdd:new-cycle [<goal>]` | Start new design cycle |
 | `/gdd:complete-cycle [<note>]` | Archive cycle to `.design/archive/cycle-N/` |

package/SKILL.md

@@ -45,6 +45,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `pause [context]` | `get-design-done:gdd-pause` | Write session handoff to `.design/HANDOFF.md` |
 | `resume` | `get-design-done:gdd-resume` | Restore session context from `.design/HANDOFF.md` and route to next step |
 | **Lifecycle** | | |
+| `start [--budget <t>] [--skip-interview] [--dismiss-nudge]` | `get-design-done:start` | First-Run Proof Path — scans UI code, returns one concrete first fix. No STATE.md writes. |
 | `new-project [--name <n>]` | `get-design-done:gdd-new-project` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
 | `new-cycle [<goal>]` | `get-design-done:gdd-new-cycle` | Start a new design cycle; writes `.design/CYCLES.md` entry |
 | `complete-cycle [<note>]` | `get-design-done:gdd-complete-cycle` | Archive cycle artifacts to `.design/archive/cycle-N/`; reset STATE.md |
@@ -205,6 +206,7 @@ If `$ARGUMENTS` is a stage or command name — invoke it directly, no state chec
 /gdd:pause              → Skill("get-design-done:gdd-pause")
 /gdd:resume          → Skill("get-design-done:gdd-resume")
 # --- Lifecycle ---
+/gdd:start           → Skill("get-design-done:start")          # leaf command, no STATE.md
 /gdd:new-project     → Skill("get-design-done:gdd-new-project")
 /gdd:new-cycle       → Skill("get-design-done:gdd-new-cycle")
 /gdd:complete-cycle  → Skill("get-design-done:gdd-complete-cycle")

package/agents/a11y-mapper.md

@@ -109,6 +109,31 @@ scope: static-only
 
 ## Scope note
 Static scan only. Runtime contrast, focus-trap, and screen-reader behavior require a live audit (Phase 8).
+
+## Micro-polish a11y findings
+
+After the standard accessibility map, scan and report:
+
+1. **Interactive elements visually < 40×40 without hit-area extension**
+   - Grep: `<button`, `<a`, elements with `onClick` where width/height classes suggest small size (e.g., `w-4 h-4`, `w-5 h-5`, `w-6 h-6`) without `::after` pseudo-element or explicit padding expansion
+   - Fix: add `::after { content:''; position:absolute; inset:-10px }` to reach 40×40 minimum
+   - This pairs with existing WCAG touch-target check but adds the concrete `::after` fix pointer
+
+2. **Icon buttons without expanded click area**
+   - Grep: `<button[^>]*>` containing only an `<svg>` or icon component with small container size
+   - Flag if no `p-2` or larger padding that would expand the hit area
+   - Fix: add `p-2` (8px each side) to 24px icon → 40px total; or use `::after` pattern
+
+### Output format:
+```
+## Micro-polish a11y findings
+
+| Finding | File | Line | Element | Measured Size | Fix |
+|---------|------|------|---------|---------------|-----|
+| small-hit-area | ... | ... | IconButton (close) | 20×20px | Add p-2 padding or ::after inset:-10px |
+
+Total: N findings. (0 = clean)
+```
 ```
 
 ## Constraints

package/agents/design-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: design-auditor
-description: Retrospective 6-pillar audit (copy, visual hierarchy, color, typography, layout/spacing, experience) with 1–4 scores. Writes .design/DESIGN-AUDIT.md. SUPPLEMENTS the existing 7-category 0-10 system; does not replace it. Spawned by verify stage BEFORE design-verifier.
+description: Retrospective 7-pillar audit (copy, visual hierarchy, color, typography, layout/spacing, experience, micro-polish) with 1–4 scores. Writes .design/DESIGN-AUDIT.md. SUPPLEMENTS the existing 7-category 0-10 system; does not replace it. Spawned by verify stage BEFORE design-verifier.
 tools: Read, Write, Bash, Grep, Glob
 color: green
 model: inherit
@@ -20,7 +20,7 @@ writes:
 
 ## Role
 
-You are a retrospective qualitative audit agent. You conduct a 6-pillar structured audit of implemented design work and produce a scored `.design/DESIGN-AUDIT.md` report with a priority fix list.
+You are a retrospective qualitative audit agent. You conduct a 7-pillar structured audit of implemented design work and produce a scored `.design/DESIGN-AUDIT.md` report with a priority fix list.
 
 You are spawned by the verify stage **BEFORE** design-verifier. Your output — `.design/DESIGN-AUDIT.md` — is passed to design-verifier as additional required reading so the verifier can incorporate your qualitative findings into its gap analysis.
 
@@ -30,9 +30,9 @@ You run once per verify session. You do NOT remediate gaps, spawn other agents,
 
 **This audit SUPPLEMENTS the existing 7-category 0-10 scoring system in `reference/audit-scoring.md`. It does NOT replace it.**
 
-The existing system (7 categories: Accessibility, Visual Hierarchy, Typography, Color, Layout & Spacing, Anti-Pattern Compliance, Interaction & Motion — each scored 0–10 with weighted totals) continues to be the primary quantitative score used by design-verifier in its Phase 1 evaluation. This 6-pillar 1–4 audit provides a qualitative retrospective layer with different framing — focused on copy quality, visual storytelling, and experience completeness — that the verifier reads as supplementary signal.
+The existing system (7 categories: Accessibility, Visual Hierarchy, Typography, Color, Layout & Spacing, Anti-Pattern Compliance, Interaction & Motion — each scored 0–10 with weighted totals) continues to be the primary quantitative score used by design-verifier in its Phase 1 evaluation. This 7-pillar 1–4 audit provides a qualitative retrospective layer with different framing — focused on copy quality, visual storytelling, experience completeness, and micro-polish — that the verifier reads as supplementary signal.
 
-Do not compute a weighted 0–100 score. This audit produces a /24 total (6 pillars × 4 maximum) as a qualitative indicator, not a replacement metric.
+Do not compute a weighted 0–100 score. This audit produces a /28 total (7 pillars × 4 maximum) as a qualitative indicator, not a replacement metric.
 
 ## Required Reading
 
@@ -45,6 +45,13 @@ Minimum expected files:
 - `.design/DESIGN-PLAN.md` — planned tasks and acceptance criteria
 - `.design/tasks/` — what was actually done (glob all task files)
 - `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)
+- `reference/visual-hierarchy-layout.md` — Z-order, whitespace, grids, and reading-order patterns (use when auditing Pillar 2: Visual Hierarchy)
+- `reference/iconography.md` — icon sizing, metaphors, library catalog, touch targets, animation guidelines
+- `reference/performance.md` — Core Web Vitals budgets, JS/font/image budgets, React runtime performance
+- `reference/style-vocabulary.md` — UI aesthetic catalog; use when scoring Pillar 3 (Color) style-coherence sub-check and Pillar 2 (Visual Hierarchy) signature-effects verification
+- `reference/design-systems-catalog.md` — 18-system index for identifying pattern precedents and system alignment
 
 ---
 
@@ -124,6 +131,8 @@ grep -rEn "btn-primary" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | h
 
 **What this measures:** Palette harmony, semantic role consistency (red = danger only), avoidance of AI-default palettes, dark mode quality if applicable.
 
+**Style-vocabulary cross-check:** Before scoring, read the `D-0N` style decision from `.design/DESIGN-CONTEXT.md` (e.g., "Glassmorphism", "Neubrutalism", "Data Dense"). Look up that style name verbatim in `reference/style-vocabulary.md` — the Light/Dark column tells you whether dark mode is required, the Signature Effects column tells you what color techniques are canonical for the style, and the Avoid For column tells you whether this style is structurally mismatched to the product type. A palette that is internally consistent but inconsistent with the declared style (e.g., hard flat fills implemented for a Glassmorphism direction) is a style coherence defect and should reduce the score by 1 point. If no style was declared in the context file, note this gap in the audit findings.
+
 **Audit method:**
 
 ```bash
@@ -247,6 +256,49 @@ grep -rEn "confirm\b|Confirm\b|areYouSure|destructive|danger" src/ --include="*.
 
 ---
 
+### Pillar 7: Micro-Polish
+
+**What this measures:** Whether fine-grained implementation details conform to polish rules — correct press scales, transition specificity, hit-area sizing, tabular numerals, and typographic text-wrap. These are the details that separate "shipped" from "crafted".
+
+**Audit method:**
+
+Collect findings from the micro-polish sections of the mapper outputs (`.design/map/motion.md`, `.design/map/tokens.md`, `.design/map/visual-hierarchy.md`, `.design/map/a11y.md`). If those files are not yet available, run targeted grep passes:
+
+```bash
+# transition:all violations
+grep -rEn "transition:\s*all|transition-property:\s*all" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -10
+grep -rEn 'className="[^"]*\btransition\b[^-]' src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+
+# will-change:all violations
+grep -rEn "will-change:\s*all" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
+
+# Missing AnimatePresence initial={false}
+grep -rEn "<AnimatePresence" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "initial={false}" | head -10
+
+# scale-on-press outside canonical 0.96
+grep -rEn "whileTap.*scale.*0\.9[^6]|scale.*0\.9[0-4578]" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+
+# Missing tabular-nums on numeric elements
+grep -rEn "price|counter|timer|count|amount|balance|total" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "tabular-nums\|tabular_nums" | head -10
+
+# Heading text-wrap:balance
+grep -rEn "<h[1-3]" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "text-balance\|text-wrap.*balance" | head -10
+
+# Small hit-area elements
+grep -rEn "w-4 h-4|w-5 h-5|w-6 h-6" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+**Scoring guide:**
+
+| Score | Criteria |
+|-------|----------|
+| 4 | Zero BAN/MIFB violations; all interactive scales at 0.96; headings use text-balance; numeric elements use tabular-nums; hit areas ≥ 40×40px |
+| 3 | 1–3 minor violations (e.g., a missing text-balance on one heading, one off-scale press value); no hard BAN violations |
+| 2 | 4–8 violations; some transition:all or will-change:all present; tabular-nums missing on multiple numeric elements |
+| 1 | Systematic violations; transition:all everywhere; no text-wrap controls; small hit areas throughout; scale values inconsistent |
+
+---
+
 ## Execution Steps
 
 ### Step 1: Load Context
@@ -262,7 +314,7 @@ find src/ -name "*.tsx" -o -name "*.jsx" -o -name "*.css" -o -name "*.scss" 2>/d
 
 ### Step 3: Audit Each Pillar
 
-For each of the 6 pillars:
+For each of the 7 pillars:
 1. Run the audit method grep commands
 2. Review output against scoring guide
 3. Assign a score (1–4) with specific evidence
@@ -285,14 +337,14 @@ Write to `.design/DESIGN-AUDIT.md` using this structure:
 ```markdown
 ---
 audited: <ISO 8601 date>
-total_score: N/24
+total_score: N/28
 supplement_note: "Supplements 7-category 0-10 system in reference/audit-scoring.md — does not replace it"
 ---
 
 ## Design Audit — [Target Scope from DESIGN-CONTEXT.md]
 
 **Audited:** [ISO 8601 date]
-**Audit type:** Qualitative 6-pillar (1–4 per pillar) — SUPPLEMENTS existing 7-category 0-10 scoring
+**Audit type:** Qualitative 7-pillar (1–4 per pillar) — SUPPLEMENTS existing 7-category 0-10 scoring
 **Screenshot gap:** Code-only analysis (no Playwright-MCP or dev server screenshot capture). Visual findings are inferred from source code patterns. Scores for Pillar 2 (Visual Hierarchy) and Pillar 3 (Color) may understate or overstate issues that are only visible at runtime. Human visual inspection is recommended for these pillars.
 
 ---
@@ -307,8 +359,9 @@ supplement_note: "Supplements 7-category 0-10 system in reference/audit-scoring.
 | 4. Typography | [N]/4 | [one-line summary] |
 | 5. Layout & Spacing | [N]/4 | [one-line summary] |
 | 6. Experience Design | [N]/4 | [one-line summary] |
+| 7. Micro-Polish | [N]/4 | [one-line summary] |
 
-**Overall: [total]/24**
+**Overall: [total]/28**
 
 ---
 
@@ -348,6 +401,10 @@ Listed by impact. Top 3 fixes the verifier should weight heavily.
 
 [Evidence. State coverage analysis — loading/error/empty/disabled/confirm presence.]
 
+### Pillar 7: Micro-Polish ([score]/4)
+
+[Evidence. List BAN/MIFB violations found, cross-referenced from mapper micro-polish sections or direct grep hits. Note counts per category: transition:all, will-change:all, scale violations, missing tabular-nums, heading text-wrap, hit-area issues.]
+
 ---
 
 ## Screenshot Gap
@@ -363,6 +420,33 @@ This audit is **code-only**. No Playwright-MCP and no dev server screenshot capt
 
 ---
 
+## Motion Anti-Pattern Check
+
+When the codebase uses Framer Motion (detectable by `import.*framer-motion` in source files), perform this additional check after the 6-pillar audit and include findings in **Pillar 6: Experience Design** under a `### Motion (Framer Motion)` subsection.
+
+Read `reference/framer-motion-patterns.md` for the full rationale behind these rules. The two hard violations to surface:
+
+**Anti-pattern 1 — Non-transform animations:** Animating `width`, `height`, `margin`, `padding`, `left`, or `top` triggers layout recalculation on every frame and causes dropped frames. Only `transform` properties (`x`, `y`, `scale`, `rotate`, `skew`) and `opacity` are GPU-safe.
+
+```bash
+# Detect non-transform animation targets in Framer Motion usage
+grep -rEn "animate=\{.*\b(width|height|margin|padding|left|top|right|bottom)\b" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+**Anti-pattern 2 — Missing reduced-motion guard:** Framer Motion animations must respect `prefers-reduced-motion`. The compliant patterns are either `useReducedMotion()` hook per component, or `<MotionConfig reducedMotion="user">` at app root. Absence of either is an accessibility violation.
+
+```bash
+# Check for MotionConfig with reducedMotion at app root
+grep -rEn "reducedMotion|useReducedMotion" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+
+# Confirm framer-motion is in use
+grep -rEl "from ['\"]framer-motion['\"]" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | wc -l
+```
+
+If framer-motion is in use and neither `reducedMotion="user"` in `MotionConfig` nor `useReducedMotion` calls are found, flag this as a high-priority accessibility gap in the Priority Fix List.
+
+---
+
 ## Constraints
 
 **MUST NOT:**

package/agents/design-context-builder.md

@@ -341,6 +341,10 @@ The NOT is equally important:
 - "NOT another purple-gradient AI product"
 - "NOT enterprise blue and gray"
 
+**Palette proposal (palette-catalog.md):** Once the product type is known from Area 1 and the brand direction is established above, look up the matching row in `reference/palette-catalog.md`. Pre-populate `D-02` with the vertical's palette as the baseline. If the product spans two verticals, anchor on the primary revenue-model vertical and note the borrow from the secondary. Always cross-check the palette against the voice axis from `reference/brand-voice.md` — a mismatch (e.g., "authoritative navy" palette + "playful irreverent" voice) must be surfaced as a gray area.
+
+**Style direction (style-vocabulary.md):** Ask the user to confirm or adjust the inferred UI aesthetic style before writing the context file. Infer the style from the brand direction words captured above. Look up the inferred style name verbatim in `reference/style-vocabulary.md` to confirm it is coherent with the product type (Best For / Avoid For columns) and to surface the performance cost (Performance column) in the Constraints section. Record the confirmed style name verbatim in the context file as a `D-0N` decision so downstream agents can pattern-match it. Example: `D-04: [Style] "Glassmorphism Dark" — confirmed for gaming media player context; GPU cost noted in constraints.`
+
 ### Area 5 — Visual References (Refero-augmented)
 
 This area uses Refero MCP when available, with graceful fallback to local brand archetypes and finally WebFetch. Refero tool names may vary — verify via ToolSearch before calling.
@@ -572,6 +576,8 @@ C-04: [other constraints]
 - ${CLAUDE_PLUGIN_ROOT}/reference/audit-scoring.md
 - ${CLAUDE_PLUGIN_ROOT}/reference/motion.md
 - ${CLAUDE_PLUGIN_ROOT}/reference/heuristics.md
+- ${CLAUDE_PLUGIN_ROOT}/reference/iconography.md
+- ${CLAUDE_PLUGIN_ROOT}/reference/performance.md
 </canonical_refs>
 
 <baseline_audit>

package/agents/design-executor.md

@@ -220,7 +220,9 @@ Work through the accessibility checklist:
 
 ### Type: motion
 
-Read `reference/motion.md` before starting.
+Read `reference/motion.md` and `reference/framer-motion-patterns.md` before starting.
+
+`reference/framer-motion-patterns.md` contains Framer Motion-specific implementation patterns that complement the framework-agnostic rules in `reference/motion.md`. When the codebase uses Framer Motion (detectable by `framer-motion` imports), apply the patterns from that file: spring/tween configuration, `AnimatePresence` with `initial={false}`, layout animations, variants with `staggerChildren`, gesture props (`whileHover`, `whileTap` at scale 0.96), `useReducedMotion` or `MotionConfig reducedMotion="user"` for a11y, and the hard constraint that `bounce: 0` for all micro-interactions.
 
 Apply the 5-question framework to every animation/transition in scope:
 
@@ -238,6 +240,7 @@ Also: verify exit animations are 60–70% of enter duration.
 ### Type: copy
 
 Read `reference/anti-patterns.md` copy section before starting.
+Read `reference/brand-voice.md` — voice axes, archetype library, and tone-by-context table provide the authoritative copy standards for this task type.
 
 1. **Audit all user-visible text**: scan files in scope for button labels, error messages, empty states, tooltips, placeholder text.
 2. **Apply UX copy standards**:
@@ -266,7 +269,7 @@ Read `reference/heuristics.md` (if present) before starting. Apply NNG heuristic
 
 ### Type: tokens
 
-Read `reference/anti-patterns.md` and DESIGN-CONTEXT.md before starting.
+Read `reference/anti-patterns.md`, `reference/design-system-guidance.md`, and DESIGN-CONTEXT.md before starting. The design-system-guidance file provides the semantic-layer naming conventions, multi-brand token architecture, and component API conventions that govern how tokens should be named and structured.
 
 1. **Audit magic values**: grep all literal CSS values (px, rem, #hex, rgb(), etc.) across scope files.
 2. **Organize by role**: group values into categories — color, spacing, typography, radius, shadow, z-index.

package/agents/design-pattern-mapper.md

@@ -36,6 +36,7 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt pass
 - `.design/STATE.md` — current pipeline position and source roots
 - `.design/DESIGN-CONTEXT.md` — goals, decisions, must-haves, baseline audit, domain, scopes
 - `reference/audit-scoring.md` — maps task types to scoring categories
+- `reference/brand-voice.md` — voice axis defaults and industry context (use when classifying copy-system patterns and inferring brand register from existing UI text)
 
 **Invariant:** Read every file in the `<required_reading>` block before taking any other action.
 
@@ -186,6 +187,7 @@ _Dominant styling approach: [CSS Modules | Tailwind | styled-components | inline
 | `spacing-system` | Padding, margin, gap, spacing scale |
 | `typography-system` | Font size, weight, family, line-height |
 | `component-styling` | How components apply styles (CSS Modules, Tailwind, etc.) |
+| `iconography-system` | Icon library in use, stroke weight, sizing conventions, touch targets |
 
 **DO NOT use:** controller, service, middleware, CRUD, data flow, request-response, event-driven. Those are code-architecture terms and have no meaning in design pattern analysis.