@hegemonart/get-design-done 1.14.8 → 1.16.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.8"
+    "version": "1.16.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.8",
+      "version": "1.16.0",
       "author": {
         "name": "hegemonart"
       },
@@ -61,7 +61,9 @@
         "schema-validation",
         "cost-optimization",
         "cache-aware",
-        "budget"
+        "budget",
+        "component-specs",
+        "design-system-benchmarks"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.14.8",
+  "version": "1.16.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",
@@ -53,10 +53,20 @@
     "cost-optimization",
     "cache-aware",
     "budget",
-    "onboarding",
-    "first-run",
-    "demo",
-    "proof-path"
+    "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",
+    "component-specs",
+    "design-system-benchmarks"
   ],
   "skills": ["./skills/"]
 }

package/CHANGELOG.md

@@ -4,6 +4,103 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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
+
+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

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.
@@ -382,6 +389,29 @@ 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–5 — Feedback, Navigation, Data** (Phase 17): Toast · Alert · Progress · Skeleton · Badge · Chip · Breadcrumb · Pagination · Stepper · Table/Grid · Date Picker · File Upload · Rich Text · Virtualized List
+
+Each spec includes: WAI-ARIA keyboard contracts (verbatim), convergence analysis (NORM = ≥4 systems agree · DIVERGE = systems differ), grep signatures for CI detection, and a failing-example block.
+
+```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/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/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>
+```