@hegemonart/get-design-done 1.15.0 → 1.18.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.15.0"
+    "version": "1.18.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.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), 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. Ships 35-component benchmark corpus with pipeline integration (auditor conformance, executor pre-flight, doc-writer scaffold, pattern-mapper convergence). Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary, 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.18.0",
       "author": {
         "name": "hegemonart"
       },
@@ -61,8 +61,12 @@
         "schema-validation",
         "cost-optimization",
         "cache-aware",
-        "budget"
+        "budget",
+        "component-specs",
+        "design-system-benchmarks",
+        "component-conformance",
+        "convergence-detector"
       ]
     }
   ]
-}
+}

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "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.",
+  "version": "1.18.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. Ships 35-component benchmark corpus (Waves 1–5) with pipeline integration: auditor conformance scoring, executor spec pre-flight, doc-writer scaffold, pattern-mapper convergence detector. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary (RN MIT easings/spring/interpolate + hyperframes transition taxonomy), 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",
     "url": "https://github.com/hegemonart"
@@ -64,7 +64,21 @@
     "palette-catalog",
     "style-vocabulary",
     "industry-palettes",
-    "ui-style-vocabulary"
+    "ui-style-vocabulary",
+    "variable-fonts",
+    "container-queries",
+    "view-transitions",
+    "motion-vocabulary",
+    "motion-easings",
+    "transition-taxonomy",
+    "gesture-mechanics",
+    "clip-path-animation",
+    "component-specs",
+    "design-system-benchmarks",
+    "component-conformance",
+    "convergence-detector"
   ],
-  "skills": ["./skills/"]
-}
+  "skills": [
+    "./skills/"
+  ]
+}

package/CHANGELOG.md

@@ -4,6 +4,128 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.18.0] — 2026-04-24
+
+### Added — Advanced Craft References + Motion Vocabulary
+
+**Wave A — Craft references (4 new files):**
+
+- `reference/variable-fonts-loading.md` — Variable font axes (wght/ital/opsz/slnt/GRAD/custom), `@font-face` range declarations, `font-display` trade-offs (swap/fallback/optional), WOFF2 subsetting with `unicode-range`, FOIT vs FOUT, fallback metric overrides (`size-adjust`, `ascent-override`, `descent-override`, `line-gap-override`), GRAD axis for dark-mode weight compensation without layout reflow, system font stacks per platform (REF-14)
+- `reference/image-optimization.md` — WebP/AVIF/JPEG XL choice matrix, `srcset`+`sizes` math by breakpoint, responsive art direction with `<picture>`, LQIP/BlurHash/ThumbHash placeholder strategies, lazy-loading + `decoding="async"` + `fetchpriority="high"`, CDN transform patterns (Cloudinary/imgix/Vercel Image), image budget enforcement (REF-15)
+- `reference/css-grid-layout.md` — CSS Grid template patterns (holy grail, bento, masonry), `subgrid`, container queries (`@container` + `container-type`), fluid typography with `clamp()` (utopia.fyi math), intrinsic sizing, logical properties, safe-area insets, `aspect-ratio`/`object-fit`, anchor positioning progressive enhancement (REF-16)
+- `reference/motion-advanced.md` — Spring physics, stagger patterns, scroll-driven animation (`animation-timeline`), FLIP, View Transitions API, route orchestration, gesture/drag mechanics (velocity threshold ≈0.11, boundary damping, pointer capture, multi-touch protection), clip-path animation patterns (hold-to-delete, scroll reveals, tab masks, comparison sliders), blur-to-mask crossfades (<20px Safari cap), CSS transitions vs keyframes for interruptible UI, WAAPI, Framer Motion hardware-accel gotcha (`x`/`y` shorthand vs GPU `transform` string), motion cohesion & personality, next-day slow-motion review process; Disney's 12 Principles UX mapping stub (fills at Phase 19.6 closeout) (REF-17)
+
+**Wave B — Motion vocabulary (RN MIT + hyperframes Apache-2.0):**
+
+- `reference/motion-easings.md` — 12 canonical curve presets (linear/quad/cubic/poly/sin/circle/exp/elastic/back/bounce/bezier + in/out/inOut wrappers) from React Native MIT upstream; `--ease-*` CSS custom property token catalog; 60fps settle-times for spring/bounce/elastic variants (MOT-01)
+- `reference/motion-interpolate.md` — Input→output range model + 4 extrapolation modes (extend/identity/clamp/wrap) from RN MIT; taxonomy of progress-linked/scroll-linked/gesture-linked/time-linked animations (MOT-02)
+- `reference/motion-spring.md` — Stiffness/damping/mass triad + 4 canonical presets (gentle/wobbly/stiff/slow) with 60fps settle-times; Framer Motion + React Spring syntax; CSS `linear()` approximation pattern (MOT-05)
+- `reference/motion-transition-taxonomy.md` — 8 controlled transition families from hyperframes Apache-2.0: 3d, blur, cover, destruction, dissolve, distortion, grid, light — each with definition, canonical examples, when-to-use heuristics (MOT-03)
+- `reference/external/NOTICE.hyperframes` — Apache-2.0 attribution for hyperframes transition taxonomy
+
+**Wave B — Output contract + tooling:**
+
+- `reference/output-contracts/motion-map.schema.json` — JSON schema requiring each animation binding to declare easing (canonical or custom+justification), transition family (optional), duration class (instant/quick/standard/slow/narrative), and trigger type (user-gesture/state-change/scroll-progress/time/loop) (MOT-04)
+- `scripts/lib/parse-contract.cjs` — Shared validation helper: extracts JSON block from agent markdown output, validates against motion-map contract, returns structured data or actionable error
+- `scripts/lib/easings.cjs` — Closed-form easing math helper (RN MIT): all 12 presets + in/out/inOut HOFs, cubic-bezier Newton-Raphson solver
+- `scripts/lib/spring.cjs` — Spring simulation helper (RN MIT): PRESETS, criticalDamping(), settleTime(), step()
+- `scripts/tests/test-motion-provenance.sh` — Provenance test: asserts RN-MIT attribution in all motion-vocabulary files; asserts no Remotion/ path citations
+
+**Agent integrations:**
+
+- `agents/motion-mapper.md` — Reads motion-advanced + easings + interpolate + transition-taxonomy + spring; emits structured JSON block (conforming to motion-map schema) before prose; advanced scan patterns for gesture/drag, clip-path, FLIP, View Transitions, scroll-driven, WAAPI
+- `agents/design-executor.md` — type:typography reads `variable-fonts-loading.md`; type:layout reads `css-grid-layout.md` + `image-optimization.md`; type:motion reads `motion-advanced.md` + `motion-easings.md` + `motion-spring.md`
+- `agents/design-auditor.md` — Required Reading extended with 4 Phase 18 references; gesture/clip-path/blur-crossfade patterns scored as "advanced craft" signal (positive) in Pillar 7
+- `agents/token-mapper.md` — Micro-polish finding #5: easing token consolidation (raw `cubic-bezier()` → `--ease-*` canonical tokens)
+- `reference/motion.md` — Cross-links added pointing to all 4 Phase 18 motion references
+- `reference/registry.json` — 9 new entries: REF-14 through REF-17 + MOT-01 through MOT-05
+
+**Phase 18 keywords added to package.json:** `variable-fonts`, `container-queries`, `view-transitions`, `motion-vocabulary`, `motion-easings`, `transition-taxonomy`, `gesture-mechanics`, `clip-path-animation`
+
+---
+
+## [1.17.0] — 2026-04-24
+
+### Added — Component Benchmark Corpus: Waves 3–5 (20 specs) + Pipeline Integration
+
+Completes the 35-spec component benchmark corpus and wires it into the design pipeline so agents actively consume per-component benchmarks during audit, execution, documentation, and pattern analysis.
+
+#### Wave 3 — Feedback (6 specs)
+
+- **`reference/components/toast.md`** — transient notification (4–8s auto-dismiss, configurable); `role="status"` (info/success) vs `role="alert"` (warning/error); entry/exit slide+fade animation; optional action; stacking with 8px gap (max 3 visible); UUPM app-interface dashboard/settings-save context (MIT attribution).
+- **`reference/components/alert.md`** — inline persistent message; info/success/warning/error variants; `role="alert"` (assertive) vs `role="status"` (polite); icon reinforces variant — never color as sole differentiator (WCAG 1.4.1).
+- **`reference/components/progress.md`** — linear + circular variants; determinate (`aria-valuenow`) vs indeterminate (`aria-valuetext`); `role="progressbar"`; `aria-label` required; 4px minimum track height.
+- **`reference/components/skeleton.md`** — content-layout mirror; shimmer (left-to-right gradient, 1.5s loop); `aria-hidden="true"` on skeleton elements; `aria-busy="true"` + `aria-label` on container; 60–90% width variation.
+- **`reference/components/badge.md`** — count/dot/icon variants; `99+` overflow pattern; decorative (no keyboard interaction); count surfaced via `aria-label` on parent element.
+- **`reference/components/chip.md`** — filter/input/suggestion/display variants; independent `aria-label` on remove button; `aria-pressed` on toggle; `role="option"` in listbox context; UUPM app-interface filter/tag-input context (MIT attribution).
+
+#### Wave 4 — Navigation & Data (9 specs)
+
+- **`reference/components/menu.md`** — `role="menu"` + `role="menuitem"`; arrow-key navigation; click-only open (no hover trigger); sub-menus on ArrowRight; focus returns to trigger on close.
+- **`reference/components/navbar.md`** — `role="banner"` + `role="navigation"` + `aria-label="Primary"`; skip-to-main link; `aria-current="page"`; hamburger `aria-expanded`; UUPM dashboard/settings/profile context (MIT attribution).
+- **`reference/components/sidebar.md`** — `aria-label="Secondary"`; icon+label vs icon-only collapsed; `aria-expanded` on collapsible sections; UUPM settings-nav + dashboard-nav variants (MIT attribution).
+- **`reference/components/breadcrumbs.md`** — `role="navigation"` + `aria-label="Breadcrumb"`; `aria-current="page"` on last item; `aria-hidden` on separators; truncate middle not ends.
+- **`reference/components/pagination.md`** — `aria-label="Pagination"`; `aria-current="page"` on active page; per-page `<select>` with visible label; UUPM list-view context (MIT attribution).
+- **`reference/components/table.md`** — `scope="col"` on all `<th>`; `aria-sort` on sortable headers; `aria-selected` on rows; `role="grid"` vs `role="table"`; virtualise >200 rows; UUPM list/detail + master-detail + dashboard context (MIT attribution).
+- **`reference/components/list.md`** — display (`<ul>/<li>`) vs interactive (`role="listbox"` + `role="option"`); `aria-multiselectable`; virtualise >100 items; UUPM list/detail left-panel context (MIT attribution).
+- **`reference/components/tree.md`** — `role="tree"` + `role="treeitem"` + `role="group"`; `aria-expanded`; `aria-level`; `aria-busy` on lazy-load nodes; full WAI-ARIA APG keyboard contract.
+- **`reference/components/command-palette.md`** — `role="dialog"` + `aria-modal`; focus trap; `role="combobox"` + `aria-controls` → `role="listbox"`; Cmd/Ctrl+K trigger; UUPM global-search context (MIT attribution).
+
+#### Wave 5 — Advanced (5 specs)
+
+- **`reference/components/date-picker.md`** — input + range variants; calendar `role="dialog"`; day cells `role="gridcell"` + `role="button"`; full arrow-key navigation; native `<input type="date">` mobile fallback.
+- **`reference/components/slider.md`** — single + range; `role="slider"` + `aria-valuenow/min/max/valuetext`; 44px thumb touch target via `::before` trick; Page Up/Down ±10%.
+- **`reference/components/file-upload.md`** — drop-zone + picker; `<input type="file">` never `display:none` (keyboard/AT fallback); `aria-label="Remove [filename]"` on remove buttons; upload errors via `aria-live="assertive"`.
+- **`reference/components/rich-text-editor.md`** — `contenteditable` + `role="textbox"` + `aria-multiline="true"`; toolbar `role="toolbar"`; toggle buttons `aria-pressed`; placeholder via CSS `::before`; mention trigger pattern.
+- **`reference/components/stepper.md`** — `role="list"` (not `role="tablist"`); `aria-current="step"` on active step; UUPM wizard/onboarding/checkout flow context (MIT attribution).
+
+#### Pipeline Integration
+
+- **`agents/design-auditor.md`** — new **Component Conformance** addendum: discovers specs, runs grep signatures against codebase, scores state/variant/a11y coverage per component, emits conformance table as informational addendum (does not change /28 pillar score).
+- **`agents/design-executor.md`** — **Benchmark Spec Pre-Flight** for `type:components` tasks: reads matching `reference/components/<name>.md`, applies anatomy/states/a11y contract before building — no re-discovering ARIA roles or keyboard patterns already benchmarked.
+- **`agents/design-doc-writer.md`** — **Component Spec Scaffold**: pre-fills DESIGN-STYLE doc structure from benchmark spec's Purpose/Anatomy/Variants/States when a spec exists; includes "Benchmarked against" citation; falls back to from-scratch generation gracefully.
+- **`agents/design-pattern-mapper.md`** — **Component Convergence Detector**: writes `.design/map/component-convergence.md` with matched/absent component table and per-component convergence %; runs after pattern extraction.
+
+---
+
+## [1.16.0] — 2026-04-24
+
+### Added — Component Benchmark Corpus: Tooling + Waves 1–2 (15 specs)
+
+This release builds the infrastructure to harvest per-component design knowledge from 18 design systems and ships 15 canonical component specs at `reference/components/`. Every spec follows a locked shape — Purpose · Anatomy · Variants · States · Sizing · Typography · Keyboard & a11y · Motion · Do/Don't · Anti-patterns · Citations · Grep signatures — making the corpus greppable, diffable, and agent-consumable.
+
+#### Tooling
+
+- **`agents/component-benchmark-harvester.md`** — given a component name, harvests per-source excerpts from 18 design systems (see `connections/design-corpora.md`), consumes Phase 15 impeccable salvage, emits raw harvest to `.planning/benchmarks/raw/<component>.md` with source-attributed excerpts and convergence pre-analysis.
+- **`agents/component-benchmark-synthesizer.md`** — reads the raw harvest and emits a canonical `reference/components/<name>.md` using the locked TEMPLATE.md shape. Convergence analysis is explicit: NORM (≥4 systems agree) vs. DIVERGE (systems disagree with rationale).
+- **`skills/benchmark/SKILL.md`** — new `/gdd:benchmark` command with 4 modes: `<component>` (single), `--wave <N>` (full wave), `--list` (coverage table), `--refresh <component>` (re-harvest on design-system version bump).
+- **`connections/design-corpora.md`** — 18-system catalog with canonical URLs, licensing/attribution notes, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+- **`reference/components/TEMPLATE.md`** — locked 12-section spec shape. All future component specs must conform.
+- **`reference/components/README.md`** — corpus index with category tables (Wave 1–5) and coverage summary.
+
+#### Wave 1 — Inputs (8 specs)
+
+- **`reference/components/button.md`** — primary/secondary/ghost/destructive/icon-only variants, 96% press scale norm, WAI-ARIA button keyboard contract, `transition:all` BAN, non-descriptive-label anti-pattern.
+- **`reference/components/input.md`** — text/search/password/number, placeholder-as-label anti-pattern, floating vs. static label trade-off (static preferred), `aria-describedby` error linking, WAI-ARIA textbox contract.
+- **`reference/components/select-combobox.md`** — native vs. custom decision tree, WAI-ARIA listbox + combobox contracts (verbatim), `aria-activedescendant` pattern, multi-select approaches, virtualised list note, async empty state.
+- **`reference/components/checkbox.md`** — binary/indeterminate states, `fieldset`+`legend` group requirement, `.indeterminate` JS property, WAI-ARIA checkbox contract.
+- **`reference/components/radio.md`** — arrow-key auto-advance behavior, Tab-as-group-unit pattern, single-radio anti-pattern, WAI-ARIA radiogroup contract.
+- **`reference/components/switch.md`** — switch vs. checkbox semantic distinction (`role="switch"` not `role="checkbox"`), spring thumb animation, pill track (`border-radius: 9999px`), immediate-action rule.
+- **`reference/components/link.md`** — link vs. button semantic boundary, underline requirement for inline links (WCAG 1.4.1), external-link disclosure, `rel="noopener noreferrer"`, non-descriptive link text anti-pattern.
+- **`reference/components/label.md`** — four association methods ranked (`<label for>` → `aria-labelledby` → `aria-label` → `<legend>`), `.sr-only` CSS pattern, legend-for-groups rule, placeholder failure analysis.
+
+#### Wave 2 — Containers (7 specs)
+
+- **`reference/components/card.md`** — stretched-link pattern for nested interactivity, `<article>` vs `<div>` semantics, elevated/outlined/clickable variants, `aria-busy` skeleton state.
+- **`reference/components/modal-dialog.md`** — focus trap, Escape contract, portal rendering, `aria-modal`+`aria-labelledby` requirement, `role="alertdialog"` for confirmations, scroll-lock, focus return on close.
+- **`reference/components/drawer.md`** — focus trap (same as modal), swipe-to-close for bottom sheet, side direction routing, nav drawer vs. content drawer role distinction, slide-in motion.
+- **`reference/components/popover.md`** — Floating UI positioning (flip+shift+arrow middlewares), non-modal vs. modal distinction, `aria-expanded`+`aria-controls` trigger contract, `role="tooltip"` on interactive content anti-pattern.
+- **`reference/components/tooltip.md`** — no-interactive-content rule, hover+focus trigger (not hover-only), Escape dismiss, 300ms delay, `aria-describedby` contract, tooltip vs. popover boundary.
+- **`reference/components/accordion.md`** — `h2`–`h6` header requirement, `aria-expanded`-on-trigger rule, `grid-template-rows` CSS height animation trick, `role="region"` landmark note (skip if >6 items).
+- **`reference/components/tabs.md`** — roving tabindex pattern, arrow-key navigation (not Tab), automatic vs. manual activation modes, tablist label requirement, `hidden` on inactive panels.
+
+---
+
 ## [1.15.0] — 2026-04-24
 
 ### Added — Design Knowledge Expansion: 10 foundational references + MIFB micro-polish + UUPM ingest

package/README.md

@@ -76,6 +76,14 @@ 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.18.0 Highlights — Advanced Craft References + Motion Vocabulary
+
+- **4 advanced craft references** — `variable-fonts-loading.md` (variable axes, font-display trade-offs, WOFF2 subsetting, fallback metric overrides, GRAD axis for dark mode), `image-optimization.md` (WebP/AVIF/JPEG XL matrix, srcset math, LQIP/BlurHash, CDN transforms, image budgets), `css-grid-layout.md` (subgrid, container queries, fluid `clamp()` typography, logical properties, safe areas, anchor positioning), `motion-advanced.md` (spring physics, FLIP, View Transitions API, gesture/drag mechanics, clip-path animations, blur crossfades, Framer Motion hardware-accel gotcha, motion cohesion, next-day review).
+- **Motion vocabulary (RN MIT upstream)** — `motion-easings.md` (12 canonical curve presets, `--ease-*` token catalog), `motion-interpolate.md` (input→output range + 4 extrapolation modes: extend/identity/clamp/wrap), `motion-spring.md` (gentle/wobbly/stiff/slow presets with 60fps settle-times). Optional math helpers at `scripts/lib/easings.cjs` and `scripts/lib/spring.cjs`.
+- **Transition taxonomy (hyperframes Apache-2.0)** — `motion-transition-taxonomy.md` names 8 controlled families (3d, blur, cover, destruction, dissolve, distortion, grid, light) so motion-mapper output diffs cleanly cycle-over-cycle.
+- **Structured motion-map output** — `motion-mapper` now emits a JSON block at the top of `.design/map/motion.md` conforming to `reference/output-contracts/motion-map.schema.json`. Every animation binding declares easing (canonical or custom+justification), transition family, duration class, and trigger type. `scripts/lib/parse-contract.cjs` validates and returns structured data or actionable error.
+- **Agent wiring** — `token-mapper` gains easing consolidation (raw `cubic-bezier()` → `--ease-*` token recommendations); `design-executor` reads craft references per task type; `design-auditor` scores gesture patterns and clip-path animations as advanced-craft signal (positive, not a penalty).
+
 ### 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.
@@ -389,6 +397,39 @@ After each design cycle, `/gdd:reflect` reads `.design/learnings/`, `.design/tel
 
 ---
 
+## Component Benchmark Corpus
+
+Per-component design specifications harvested from 18 major design systems and synthesized into a locked, agent-consumable format. Every spec is ≤350 lines, greppable, diff-friendly, and cross-linked to `reference/anti-patterns.md`.
+
+**Wave 1 — Inputs (v1.16.0)**: Button · Input · Select/Combobox · Checkbox · Radio · Switch · Link · Label
+
+**Wave 2 — Containers (v1.16.0)**: Card · Modal/Dialog · Drawer/Sheet · Popover · Tooltip · Accordion · Tabs
+
+**Wave 3 — Feedback (v1.17.0)**: Toast · Alert · Progress · Skeleton · Badge · Chip
+
+**Wave 4 — Navigation & Data (v1.17.0)**: Menu · Navbar · Sidebar · Breadcrumbs · Pagination · Table · List · Tree · Command-palette
+
+**Wave 5 — Advanced (v1.17.0)**: Date-picker · Slider · File-upload · Rich-text editor · Stepper
+
+**Total: 35 specs** across 5 waves. Each spec: WAI-ARIA keyboard contracts (verbatim), NORM/DIVERGE convergence analysis, grep signatures for `design-auditor` conformance scoring, and a failing-example block.
+
+**Pipeline integration (v1.17.0):**
+- `design-auditor` — detects component implementations via grep signatures, scores conformance against specs, emits Component Conformance addendum
+- `design-executor` — reads matching spec as pre-flight contract for `type:components` tasks
+- `design-doc-writer` — scaffolds handoff docs from spec anatomy/variants when a benchmark spec exists
+- `design-pattern-mapper` — writes `.design/map/component-convergence.md` (matched/absent components + convergence %)
+
+```bash
+/gdd:benchmark button                  # harvest + synthesize a single spec
+/gdd:benchmark --wave 1                # run all Wave 1 specs
+/gdd:benchmark --list                  # coverage table
+/gdd:benchmark --refresh modal-dialog  # re-harvest after design-system update
+```
+
+Sources: `connections/design-corpora.md` — Material 3, Apple HIG, Radix, WAI-ARIA APG, shadcn/ui, Polaris, Carbon, Fluent 2, Primer, Atlassian, Ant Design, Mantine, Chakra, Base Web, Nord, Spectrum, Lightning, Gestalt (Pinterest).
+
+---
+
 ## Authority Watcher
 
 Subscribe to a curated whitelist of design-authority sources, diff it against a snapshot, and feed only genuinely new, classified entries into the Self-Improvement reflector. Authority monitoring — not trend watching.

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark]"
 user-invocable: true
 ---
 
@@ -85,6 +85,8 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `extract-learnings [--cycle <slug>]` | `get-design-done:extract-learnings` | Extract decisions, lessons, patterns, and surprises from a completed cycle → `.design/cycles/<slug>/LEARNINGS.md` |
 | `skill-manifest [--refresh]` | `get-design-done:skill-manifest` | List or refresh the local skill manifest used by the router for discovery |
 | `watch-authorities [--refresh] [--since <date>] [--feed <name>] [--schedule <cadence>]` | `get-design-done:gdd-watch-authorities` | Run design-authority-watcher — fetch curated feeds, diff snapshot, classify new entries → `.design/authority-report.md` (consumed by `/gdd:reflect`) |
+| `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |
+| `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |
 
 ## Handoff Routing
 
@@ -203,6 +205,7 @@ If `$ARGUMENTS` is a stage or command name — invoke it directly, no state chec
 /gdd:reflect            → Skill("get-design-done:gdd-reflect")
 /gdd:apply-reflections  → Skill("get-design-done:gdd-apply-reflections")
 /gdd:watch-authorities  → Skill("get-design-done:gdd-watch-authorities")
+/gdd:benchmark          → Skill("get-design-done:gdd-benchmark")
 /gdd:pause              → Skill("get-design-done:gdd-pause")
 /gdd:resume          → Skill("get-design-done:gdd-resume")
 # --- Lifecycle ---

package/agents/component-benchmark-harvester.md

@@ -0,0 +1,112 @@
+---
+name: component-benchmark-harvester
+description: Given a component name, harvests design-system excerpts from 18 sources (design-corpora.md) and emits raw, source-attributed output to .planning/benchmarks/raw/<component>.md. Spawned by /gdd:benchmark.
+tools: Read, Write, WebFetch, Bash, Grep, Glob
+color: yellow
+default-tier: sonnet
+tier-rationale: "Network fetch + multi-source synthesis is open-ended; Haiku misses cross-system nuance, Opus overkill for structured harvesting."
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 120
+reads-only: false
+writes:
+  - ".planning/benchmarks/raw/"
+---
+
+@reference/shared-preamble.md
+
+# component-benchmark-harvester
+
+## Role
+
+You are the harvesting agent for the component benchmark corpus. Given a component name
+(e.g. "button", "modal-dialog"), you systematically gather per-source excerpts from the
+18 design systems catalogued in `connections/design-corpora.md` and emit a consolidated
+raw harvest file at `.planning/benchmarks/raw/<component>.md`.
+
+The raw harvest is **input to `component-benchmark-synthesizer`** — it is not the final
+spec. Focus on breadth and attribution; the synthesizer does convergence analysis.
+
+## Required Reading
+
+The orchestrating skill supplies a `<required_reading>` block in the prompt. Read every
+listed file before acting. Minimum expected inputs:
+
+- `connections/design-corpora.md` — system catalog with URLs, licenses, fallback chain
+- `.planning/research/impeccable-salvage/` — any files relevant to the target component
+
+## Step 1 — Check impeccable salvage
+
+Before any network fetch, `Grep` the impeccable salvage directory for the component name
+(case-insensitive). Extract any relevant prose as the first source in the raw file.
+
+## Step 2 — Fetch each design system
+
+For each of the 18 systems in `design-corpora.md`:
+
+1. Attempt `WebFetch` on `<canonical-url>/<component-slug>` (try common slug variants:
+   kebab-case, camelCase, plain name).
+2. On fetch failure, try the fallback chain: archive.org → Refero MCP → Pinterest MCP.
+3. Extract the relevant sections: anatomy, variants, states, a11y/keyboard, do/don't.
+4. Note which fallback tier was used (if any).
+
+**Prioritise signal over volume.** One precise quoted sentence beats three paraphrased
+paragraphs. For WAI-ARIA APG keyboard contracts, quote verbatim.
+
+## Step 3 — Write raw harvest file
+
+Write `.planning/benchmarks/raw/<component>.md` with this structure:
+
+```markdown
+# <Component Name> — Raw Benchmark Harvest
+
+Harvested: <ISO date>
+Target: reference/components/<component>.md
+
+## Convergence Notes (pre-synthesis)
+
+_Fill in patterns you noticed while harvesting — what ≥4 systems agree on._
+
+## Sources
+
+### <System Name>
+> Source: [<System Name>](<url>) — <license> — accessed <date>
+> Source tier: canonical | archive.org | refero | pinterest
+
+**Anatomy:** …
+**Variants:** …
+**States:** …
+**Keyboard & a11y:** …
+**Do/Don't:** …
+
+### <next system>
+…
+```
+
+One `###` section per source. Omit a source only if the fallback chain is fully
+exhausted — document the failure with `**Status: unreachable**`.
+
+## Step 4 — Convergence pre-analysis
+
+After all sources, add a `## Convergence Notes (pre-synthesis)` summary identifying:
+- What the majority of systems (≥4) agree on → mark `NORM`
+- Where systems meaningfully diverge → mark `DIVERGE` with a brief note
+
+This pre-analysis seeds the synthesizer's convergence analysis.
+
+## Output Contract
+
+- File: `.planning/benchmarks/raw/<component>.md`
+- One `###` block per harvested source (≥4 blocks minimum for a useful spec)
+- WAI-ARIA APG keyboard contracts quoted verbatim
+- Convergence pre-analysis section present
+
+## Completion Marker
+
+End your response with:
+
+```
+## HARVEST COMPLETE
+Component: <name>
+Sources harvested: <N>
+Raw file: .planning/benchmarks/raw/<component>.md
+```

package/agents/component-benchmark-synthesizer.md

@@ -0,0 +1,88 @@
+---
+name: component-benchmark-synthesizer
+description: Reads a raw harvest file from .planning/benchmarks/raw/<component>.md and emits a canonical component spec at reference/components/<name>.md using the locked TEMPLATE.md shape. Spawned by /gdd:benchmark after harvesting.
+tools: Read, Write, Grep, Glob
+color: green
+default-tier: sonnet
+tier-rationale: "Synthesis across ≥4 sources with explicit convergence analysis requires multi-step reasoning; Haiku loses cross-source nuance, Opus overkill for structured template fill."
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 90
+reads-only: false
+writes:
+  - "reference/components/"
+---
+
+@reference/shared-preamble.md
+
+# component-benchmark-synthesizer
+
+## Role
+
+You are the synthesis agent for the component benchmark corpus. You read a raw harvest
+file at `.planning/benchmarks/raw/<component>.md` (produced by `component-benchmark-harvester`)
+and emit a canonical component spec at `reference/components/<name>.md`, following
+`reference/components/TEMPLATE.md` exactly.
+
+Your primary intellectual task is **convergence analysis**: determine what the design
+systems agree on (norms) vs. where they meaningfully diverge (trade-offs), and encode
+that signal in the spec so future agents know what is non-negotiable.
+
+## Required Reading
+
+The orchestrating skill supplies a `<required_reading>` block in the prompt. Read every
+listed file before acting. Minimum expected inputs:
+
+- `.planning/benchmarks/raw/<component>.md` — the raw harvest to synthesize
+- `reference/components/TEMPLATE.md` — the locked spec shape you must follow
+- `reference/anti-patterns.md` — for cross-linking anti-pattern entries
+
+## Convergence Analysis Rules
+
+After reading all source sections from the raw file:
+
+1. **Count agreement** — if ≥4 of the 18 systems agree on a property (anatomy element,
+   state name, keyboard key, constraint), mark it `**Norm** (≥N/18 systems agree)`.
+2. **Flag divergence** — if systems meaningfully disagree on a property, mark it
+   `**Diverge** — <brief note on what differs and why>`.
+3. **Do not invent** — if fewer than 2 sources mention a property, omit it from the spec
+   rather than guessing. The corpus is additive; gaps will be filled when more sources
+   are harvested.
+
+## Output Rules
+
+- Strictly follow `reference/components/TEMPLATE.md` — every section must be present,
+  in order, even if sparse.
+- **Max 350 lines** — dense, diff-friendly, greppable. Extract verbose prose to
+  `reference/` cross-links rather than embedding it.
+- **WAI-ARIA keyboard contract** — quote verbatim from WAI-ARIA APG source. Mark the
+  source attribution inline.
+- **Failing-example block** — each spec must include a `## Failing Example` section
+  showing what a broken implementation looks like (missing a11y attribute, wrong role,
+  broken keyboard handler). Include at least one grep detection pattern:
+  ```
+  # Grep: detect common failure
+  grep -r "pattern" src/
+  ```
+- **Benchmark citations** — every claim carries an inline citation: `(Material 3, Polaris)`
+  or `(WAI-ARIA APG §4.2)`.
+
+## Output Path
+
+Write the final spec to `reference/components/<name>.md` (kebab-case, matching the
+component slug used in harvesting).
+
+Update `reference/components/README.md`:
+- Find the correct category section (Inputs / Containers / Feedback / Navigation / Advanced)
+- Add a one-line entry: `| [Name](name.md) | <one-line purpose> | <anatomy snippet> |`
+
+## Completion Marker
+
+End your response with:
+
+```
+## SYNTHESIS COMPLETE
+Component: <name>
+Spec: reference/components/<name>.md
+Lines: <N>
+Systems cited: <N>
+```

package/agents/design-auditor.md

@@ -6,7 +6,8 @@ color: green
 model: inherit
 default-tier: sonnet
 tier-rationale: "Emits structured findings from code inspection; Sonnet balances depth with cost"
-size_budget: XL
+size_budget: XXL
+size_budget_rationale: "Phase 17 added Component Conformance addendum (+54 lines for spec-grep detection + conformance scoring algorithm)"
 parallel-safe: always
 typical-duration-seconds: 45
 reads-only: false
@@ -52,6 +53,10 @@ Minimum expected files:
 - `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
+- `reference/variable-fonts-loading.md` (if present) — variable font axes, font-display trade-offs, fallback metric overrides; use when auditing Pillar 4 (Typography)
+- `reference/image-optimization.md` (if present) — format matrix, srcset/sizes, LQIP/BlurHash, CDN transforms, image budgets; use when auditing Pillar 5 (Layout & Spacing) for image-heavy UIs
+- `reference/css-grid-layout.md` (if present) — subgrid, container queries, fluid clamp() typography, logical properties; use when auditing Pillar 5 (Layout & Spacing)
+- `reference/motion-advanced.md` (if present) — advanced motion patterns; score gesture/drag mechanics, clip-path animations, blur crossfades as "advanced craft" signal (positive, not a penalty) in Pillar 7 (Micro-Polish)
 
 ---
 
@@ -447,6 +452,60 @@ If framer-motion is in use and neither `reducedMotion="user"` in `MotionConfig`
 
 ---
 
+## Component Conformance Addendum
+
+After the 7-pillar scoring is complete, run this addendum to detect component implementations and score their conformance against `reference/components/` benchmark specs. Findings appear in `.design/DESIGN-AUDIT.md` as an informational section after the pillar scores — they do not affect the /28 total.
+
+### Step 1: Discover available specs
+
+```bash
+ls reference/components/*.md | grep -v TEMPLATE | grep -v README
+```
+
+### Step 2: Detect implementations in codebase
+
+For each spec, run its **Grep Signatures** against the source root (from `STATE.md source_roots`, default `src/`). A component is "detected" if ≥1 grep signature pattern matches. Examples:
+
+```bash
+# Check for Button implementation
+grep -rn "role=\"button\"\|<button\b\|Button\b" src/ --include="*.tsx" --include="*.jsx" | head -5
+
+# Check for Toast implementation
+grep -rn "role=\"status\"\|role=\"alert\"\|toast\|Toast\b" src/ --include="*.tsx" --include="*.jsx" | head -5
+```
+
+### Step 3: Score conformance per detected component
+
+For each detected component, check:
+- **States covered**: count how many States from the spec are implemented (look for aria states, visual states)
+- **Variants covered**: count how many spec Variants exist in the codebase
+- **A11y contract**: spot-check 2–3 WAI-ARIA items from the Keyboard & Accessibility section
+
+Score = (implemented items) / (total spec items checked) × 100. Round to nearest 10%.
+
+### Step 4: Emit in DESIGN-AUDIT.md
+
+Add after the Priority Fix List:
+
+```markdown
+## Component Conformance
+
+> Informational addendum — does not affect /28 pillar score.
+> Specs from `reference/components/` benchmarked against codebase.
+
+| Component | Detected | Conformance | Key Gaps |
+|-----------|----------|-------------|----------|
+| Button | ✓ | 80% | Missing `aria-busy` on loading state |
+| Toast | ✓ | 60% | Missing `role="alert"` on error variant |
+| Table | ✗ | — | No implementation found |
+
+**Summary**: N/M specs detected in codebase; average conformance X%.
+```
+
+If `reference/components/` does not exist or contains no specs, skip this section entirely (graceful degradation).
+
+---
+
 ## Constraints
 
 **MUST NOT:**

package/agents/design-doc-writer.md

@@ -61,6 +61,27 @@ The orchestrating stage (style command) supplies a `<required_reading>` block in
 
 ---
 
+## Component Spec Scaffold
+
+Before Step 1, check whether a benchmark spec exists for this component:
+
+```bash
+# component_name is title-cased (e.g., "Button") → convert to kebab-case for file lookup
+# e.g., "CommandPalette" → "command-palette", "RichTextEditor" → "rich-text-editor"
+ls reference/components/<kebab-name>.md 2>/dev/null
+```
+
+**If the spec exists**, read its **Purpose**, **Anatomy**, **Variants**, and **States** sections. Use them to:
+1. Pre-fill the DESIGN-STYLE doc's structure with the benchmark section headers and variant table
+2. Pull the "Benchmark Citations" entry from the spec and include: `> Benchmarked against: [systems list]`
+3. Fill in project-specific values from DESIGN-CONTEXT.md on top of the scaffold (brand tokens, chosen variants, etc.)
+
+**If no spec exists**, generate the DESIGN-STYLE doc from scratch as before — no change to existing behaviour.
+
+This step runs for both `pipeline_complete: true` and `pipeline_complete: false` modes.
+
+---
+
 ## Work
 
 ### Common Step 1 — Extract Design Tokens from Source File