@hegemonart/get-design-done 1.14.8 → 1.16.0

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.
 

package/agents/design-verifier.md

@@ -120,6 +120,11 @@ Anti-Patterns (weight 10%):
 Motion (weight 5%):
   Score: [N]/10
   Evidence: [easing values, reduced-motion presence, duration range]
+
+Micro-Polish (qualitative supplement — from DESIGN-AUDIT.md Pillar 7):
+  Score: [N]/4  (not weighted into the 0–100 total; reported as supplementary signal)
+  Violations flagged: [list BAN/MIFB hits from mapper micro-polish sections]
+  Notes: [brief summary — 0 violations = clean; list categories with hits]
 ```
 
 **Weighted total:**
@@ -128,6 +133,8 @@ Score = (Accessibility × 0.25) + (Visual Hierarchy × 0.20) + (Typography × 0.
       + (Color × 0.15) + (Layout × 0.10) + (Anti-Patterns × 0.10) + (Motion × 0.05)
 ```
 
+Note: Micro-Polish is a qualitative supplement (drawn from DESIGN-AUDIT.md Pillar 7) and is reported alongside the weighted total but does not alter the 0–100 score. If Pillar 7 score is 1 or 2 and violations are systemic, flag as a MINOR or MAJOR gap in Phase 5.
+
 **Delta vs baseline:**
 ```
 Before: [baseline_score from DESIGN-CONTEXT.md]/100
@@ -149,6 +156,8 @@ Before → After
   ─────────────────────────────────
   Total:    [baseline]/100 → [new]/100  ([+N] improvement)
   Grade:    [before grade] → [after grade]
+  ─────────────────────────────────
+  Micro-Polish (suppl.): [N]/4  — [N] violations  *(not weighted)*
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -383,6 +392,7 @@ If no `.pen` files: skip silently. Print: `pencil.dev spec diff: no .pen files
 
 Collect all failures from Phases 1–4:
 - Phase 1: category scores still below 7 (despite design pass)
+- Phase 1 (micro-polish supplement): Pillar 7 score of 1 or 2 with systemic violations → MINOR or MAJOR gap
 - Phase 2: `✗ FAIL` must-haves
 - Phase 3: NNG scores of 0 or 1 on any heuristic
 - Phase 4: visual UAT `no` responses
@@ -487,6 +497,7 @@ cosmetics: N
 | Anti-Patterns | [N]/10 | [N]/10 | [±N] | 10% | [N] |
 | Motion | [N]/10 | [N]/10 | [±N] | 5% | [N] |
 | **Total** | **[N]/100** | **[N]/100** | **[±N]** | | |
+| Micro-Polish *(suppl.)* | [N]/4 | [N]/4 | [±N] | — | *(not weighted)* |
 
 Grade: [before] → [after]
 

package/agents/motion-mapper.md

@@ -94,6 +94,51 @@ generated: [ISO 8601]
 ## Score
 Reduced-motion compliance: [Full | Partial | None]
 Motion consistency: [Consistent | Mixed | Chaotic]
+
+## Micro-motion findings
+
+After the standard motion inventory, emit a "Micro-motion findings" section with grep-driven hits:
+
+### Patterns to scan for:
+
+1. **transition:all violations**
+   - Grep: `transition:\s*all|transition-property:\s*all`
+   - Also Tailwind bare: `className="[^"]*\btransition\b[^-]` (transition class without modifier)
+   - Report: file:line, the exact declaration, fix pointer → replace with specific properties
+
+2. **will-change:all violations**
+   - Grep: `will-change:\s*all`
+   - Report: file:line, the declaration, fix pointer → `will-change: transform`
+
+3. **Keyframe-driven interactive elements**
+   - Grep: `animation:.*forwards|@keyframes.*\{` on elements that also have `:hover` or `:active` or `onClick`
+   - Report: these should use CSS transitions, not keyframe animations
+
+4. **Missing AnimatePresence initial={false}**
+   - Grep: `<AnimatePresence(?![^>]*initial=\{false\})` — AnimatePresence without initial={false}
+   - Report: file:line; check if the wrapped component is persistent UI (not route-level transitions)
+
+5. **Icon cross-fade with wrong bounce**
+   - Grep: `bounce:\s*[^0]` inside framer-motion spring config near icon-related components
+   - Report: bounce must be 0 for icon animations; non-zero bounce creates invasive pop effect
+
+6. **scale-on-press outside canonical range**
+   - Grep: `scale.*0\.9[578]|scale.*0\.9[0-4]|whileTap.*scale.*0\.9[578]`
+   - Report: file:line; canonical press scale is 0.96 — not 0.95, 0.97, 0.98
+
+### Output format for this section:
+```
+## Micro-motion findings
+
+| Finding | File | Line | Issue | Fix |
+|---------|------|------|-------|-----|
+| transition:all | src/components/Button.tsx | 23 | `transition: all 200ms` | Replace with `transition: background-color 200ms, color 200ms` |
+| ... | ... | ... | ... | ... |
+
+Total: N violations found. (0 = clean)
+```
+
+If no violations found, emit: `## Micro-motion findings — CLEAN (0 violations)`
 ```
 
 ## Constraints

package/agents/token-mapper.md

@@ -94,6 +94,42 @@ figma_augmented: [true|false]
 
 ## Observations
 - [Dominant color space, typography scale coherence, grid adherence]
+
+## Micro-polish token findings
+
+After the standard token inventory, scan and report:
+
+1. **Tinted image outlines**
+   - Grep: `outline-(slate|zinc|neutral|gray|stone|blue|red|green|yellow|purple|orange)-\d+` on `<img>` elements
+   - Grep CSS: `img\s*\{[^}]*outline:[^}]*#[0-9a-fA-F]{3,8}`
+   - Fix: `outline: 1px solid rgba(0,0,0,0.08)` or `rgba(255,255,255,0.08)` only
+
+2. **Shadow tokens drifting from 3-layer formula**
+   - Grep for `box-shadow` values that use a single layer or non-rgba values
+   - Flag: shadows that don't follow the 3-layer pattern (0 1px 2px / 0 4px 8px / 0 8px 16px)
+   - Report as informational (not hard violation) unless the design system has a shadow token system
+
+3. **Missing root-level font-smoothing**
+   - Grep: `-webkit-font-smoothing` and `-moz-osx-font-smoothing`
+   - If found NOT on `:root` or `body` → flag as per-element misapplication
+   - If not found at all → flag as missing root antialiasing
+
+4. **Missing tabular-nums on dynamic numerals**
+   - Grep for elements with className containing: `price`, `counter`, `timer`, `count`, `amount`, `balance`, `total`
+   - Check if they have `font-variant-numeric: tabular-nums` or Tailwind `tabular-nums` class
+   - Report missing instances
+
+### Output format:
+```
+## Micro-polish token findings
+
+| Finding | File | Line | Issue | Fix |
+|---------|------|------|-------|-----|
+| tinted-outline | ... | ... | `outline-slate-200` on img | Use `outline: 1px solid rgba(0,0,0,0.08)` |
+| missing-tabular-nums | ... | ... | `.price` element lacks tabular-nums | Add `font-variant-numeric: tabular-nums` |
+
+Total: N findings. (0 = clean)
+```
 ```
 
 ## Constraints

package/agents/visual-hierarchy-mapper.md

@@ -86,6 +86,35 @@ Scale coherence: [Well-defined | Flat | Inverted | Chaotic]
 
 ## Score
 Overall hierarchy health: [Well-defined | Flat | Inverted]
+
+## Micro-polish hierarchy findings
+
+After the standard visual hierarchy map, scan and report:
+
+1. **Same border-radius on nested surfaces**
+   - Grep (Tailwind): look for identical `rounded-*` class on a container AND its immediate child within a padded block
+   - Grep CSS: `border-radius:\s*[0-9]+` appearing on both parent and child in the same component
+   - Fix: apply concentric formula `innerRadius = outerRadius − padding`
+
+2. **Headings without text-wrap:balance**
+   - Grep: `<h[1-3]` elements or `.heading`, `.title` elements without `text-wrap: balance` or Tailwind `text-balance`
+   - Report: file:line; add `text-wrap: balance` to all headings
+
+3. **Missing text-wrap:pretty on body text**
+   - Grep: `<p>`, `.body`, `.description`, `.caption` without `text-wrap: pretty` or `text-pretty`
+   - This is an informational finding (enhancement, not violation)
+
+### Output format:
+```
+## Micro-polish hierarchy findings
+
+| Finding | Severity | File | Description | Fix |
+|---------|----------|------|-------------|-----|
+| same-radius-nested | HIGH | ... | Card (rounded-xl) + inner button (rounded-xl) at 16px padding | inner should be rounded-none (16-16=0) |
+| heading-no-balance | MED | ... | h2 missing text-wrap:balance | Add text-balance class |
+
+Total: N findings.
+```
 ```
 
 ## Constraints

package/connections/design-corpora.md

@@ -0,0 +1,158 @@
+# Design Corpora — Component Benchmark Sources
+
+This file is the canonical source list for `agents/component-benchmark-harvester.md`.
+It catalogs the 18 design systems used when harvesting per-component benchmarks,
+with licensing notes and a documented fallback chain.
+
+## Fallback Chain
+
+When a primary URL is unreachable, try in order:
+
+1. **Canonical URL** — documented per-system below
+2. **archive.org snapshot** — `https://web.archive.org/web/*/` + canonical URL
+3. **Refero MCP search** — `mcp__refero__search` with component name + system name
+4. **Pinterest MCP visual search** — `mcp__pinterest__search` with component name + system name
+
+Document which tier was used in the raw harvest file under `Source tier:`.
+
+---
+
+## Design Systems Catalog
+
+### 1. Material Design 3 (Google)
+- **Canonical**: https://m3.material.io/components
+- **License**: Apache 2.0 (docs: Creative Commons BY 4.0)
+- **Coverage**: Full component set with anatomy, variants, accessibility, theming tokens
+- **Notes**: Use `/components/<slug>` path. Best for density, motion, and adaptive layout guidance.
+
+### 2. Apple HIG
+- **Canonical**: https://developer.apple.com/design/human-interface-guidelines/
+- **License**: © Apple Inc. — educational fair use for benchmarking
+- **Coverage**: iOS, macOS, visionOS, watchOS; focus on a11y, gestures, platform norms
+- **Notes**: Crawl per-platform variant pages. Best for accessibility contracts and iOS-native patterns.
+
+### 3. Radix UI Primitives + WAI-ARIA APG
+- **Canonical (Radix)**: https://www.radix-ui.com/primitives/docs/components/
+- **Canonical (WAI-ARIA APG)**: https://www.w3.org/WAI/ARIA/apg/patterns/
+- **License**: MIT (Radix); W3C (WAI-ARIA APG — freely usable)
+- **Coverage**: Unstyled primitives + full ARIA keyboard contracts
+- **Notes**: WAI-ARIA APG keyboard contracts should be quoted verbatim. Radix wraps them with implementation detail.
+
+### 4. shadcn/ui
+- **Canonical**: https://ui.shadcn.com/docs/components/
+- **License**: MIT
+- **Coverage**: Radix-based, Tailwind-styled components; real-world usage patterns
+- **Notes**: Best for "what real teams ship" convergence signal alongside spec systems.
+
+### 5. Polaris (Shopify)
+- **Canonical**: https://polaris.shopify.com/components/
+- **License**: Creative Commons BY-NC-SA 4.0 (docs)
+- **Coverage**: E-commerce-optimised components; excellent do/don't examples
+- **Notes**: Polaris has unusually detailed do/don't guidance — mine it for anti-pattern blocks.
+
+### 6. Carbon Design System (IBM)
+- **Canonical**: https://carbondesignsystem.com/components/
+- **License**: Apache 2.0
+- **Coverage**: Enterprise UI; data-heavy components; full accessibility matrix
+- **Notes**: Best for data-dense table/form contexts and enterprise accessibility contracts.
+
+### 7. Fluent 2 (Microsoft)
+- **Canonical**: https://fluent2.microsoft.design/components/web/
+- **License**: MIT
+- **Coverage**: Windows / Microsoft 365 design language; dense information hierarchy
+- **Notes**: Good for focus-management patterns in complex workflows.
+
+### 8. Primer (GitHub)
+- **Canonical**: https://primer.style/components/
+- **License**: MIT
+- **Coverage**: Developer tools UI; markdown + code contexts; icon integration
+- **Notes**: Best for developer-tool and productivity-app component norms.
+
+### 9. Atlassian Design System
+- **Canonical**: https://atlassian.design/components/
+- **License**: Atlassian Design System License (educational fair use)
+- **Coverage**: Collaboration software; complex overlays; strong focus management
+- **Notes**: Excellent focus-trap and dialog accessibility guidance.
+
+### 10. Ant Design
+- **Canonical**: https://ant.design/components/
+- **License**: MIT
+- **Coverage**: Large enterprise component set; Asian market conventions
+- **Notes**: High component density; useful for form and data-table convergence.
+
+### 11. Mantine
+- **Canonical**: https://mantine.dev/
+- **License**: MIT
+- **Coverage**: Full-featured React library; excellent composability patterns
+- **Notes**: Good for controlled vs uncontrolled patterns and React-idiomatic API design.
+
+### 12. Chakra UI
+- **Canonical**: https://chakra-ui.com/docs/components/
+- **License**: MIT
+- **Coverage**: Accessible by default; strong theming; popular in SaaS
+- **Notes**: Good accessibility defaults baseline; useful for theming-token convergence.
+
+### 13. Base Web (Uber)
+- **Canonical**: https://baseweb.design/components/
+- **License**: MIT
+- **Coverage**: High-density, internationalization-aware components
+- **Notes**: Good for RTL, i18n, and high-density layout patterns.
+
+### 14. Nord Design System (Trivago)
+- **Canonical**: https://nordhealth.design/components/
+- **License**: MIT
+- **Coverage**: Healthcare / hospitality UI; strong accessibility focus
+- **Notes**: Smaller corpus; useful for healthcare context accessibility norms.
+
+### 15. Spectrum (Adobe)
+- **Canonical**: https://spectrum.adobe.com/page/component-list/
+- **License**: Apache 2.0
+- **Coverage**: Creative tools UI; multi-surface (web, mobile, desktop)
+- **Notes**: Best for creative-tool contexts and platform-adaptive component behavior.
+
+### 16. Lightning Design System (Salesforce)
+- **Canonical**: https://www.lightningdesignsystem.com/components/
+- **License**: BSD 3-Clause (Salesforce SLDS license)
+- **Coverage**: CRM / enterprise SaaS; dense forms; complex data grids
+- **Notes**: Good for enterprise form validation patterns and data-heavy contexts.
+
+### 17. Evergreen (Segment)
+- **Canonical**: https://evergreen.segment.com/components/
+- **License**: MIT
+- **Coverage**: Analytics / data SaaS; compact components
+- **Notes**: Small system; useful as a convergence signal for SaaS-optimised defaults.
+
+### 18. Gestalt (Pinterest)
+- **Canonical**: https://gestalt.pinterest.systems/
+- **License**: Apache 2.0
+- **Coverage**: Visual-content feed; strong image + card patterns
+- **Notes**: Best for card / masonry / visual-content component norms.
+
+---
+
+## Supplemental Source
+
+### Phase 15 Impeccable Salvage
+- **Path**: `.planning/research/impeccable-salvage/`
+- **License**: MIT (internal port)
+- **Notes**: Harvested design-knowledge prose from the pre-Phase-15 impeccable plugin.
+  The harvester should consume this directory for any component-relevant excerpts before
+  reaching out to external URLs.
+
+---
+
+## Attribution Convention
+
+Every excerpt written to `.planning/benchmarks/raw/<component>.md` must carry a
+source-attribution line in the format:
+
+```
+> Source: [System Name](<canonical-url>) — [license] — accessed <date>
+```
+
+For WAI-ARIA APG keyboard contracts quoted verbatim, use:
+
+```
+> Source: WAI-ARIA Authoring Practices Guide (<url>) — W3C — accessed <date>
+> Quoted verbatim per W3C document license.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.14.8",
+  "version": "1.16.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -54,7 +54,21 @@
     "self-improvement",
     "reflection",
     "tested",
-    "ci"
+    "ci",
+    "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": [
     "SKILL.md"