@hegemonart/get-design-done 1.14.7 → 1.15.0

package/agents/design-start-writer.md

@@ -0,0 +1,221 @@
+---
+name: design-start-writer
+description: "Writes .design/START-REPORT.md — 7 fixed sections plus a machine-readable JSON block. Consumes the findings-engine output, interview answers, and detection result from .design/.start-context.json. Never writes STATE.md. Parameter-free: reads the context JSON path from the prompt and emits the report."
+tools: Read, Write, Grep, Glob
+color: green
+
+model: haiku
+default-tier: haiku
+tier-rationale: "Formatting + light synthesis over a bounded ~3KB input; Haiku is the correct tier per Phase 10.1 D-14 (Haiku = writers/formatters with fixed schemas)."
+
+parallel-safe: always
+typical-duration-seconds: 10
+reads-only: false
+writes:
+  - ".design/START-REPORT.md"
+
+allowed-read-paths:
+  - ".design/.start-context.json"
+  - ".design/START-REPORT.md"
+allowed-write-paths:
+  - ".design/START-REPORT.md"
+---
+
+## Role
+
+Write `.design/START-REPORT.md` for `/gdd:start`. The report is the single artifact the user sees after a first-run scan. It must feel like GDD understood the project, not like it printed a generic checklist. One best_first_proof, one suggested next command, no ambiguity.
+
+---
+
+## Required Reading
+
+- `.design/.start-context.json` — produced by `skills/start/SKILL.md` before spawning this agent. Contains detection result, interview answers, and the findings-engine output.
+
+## Inputs
+
+```json
+{
+  "schema_version": "1.0",
+  "detected": {
+    "kind": "next-app-router | src-components | monorepo-ui-pkg | ...",
+    "path": "relative/path/to/components",
+    "framework": "next | vite | cra | ...",
+    "design_system": "tailwind | css-modules | ...",
+    "confidence": 0.85
+  },
+  "interview": {
+    "pain": "free text or empty",
+    "target_area": "relative/path",
+    "budget": "fast | balanced | thorough",
+    "framework_confirmed": true,
+    "design_system_confirmed": true,
+    "figma_workflow": "figma | canvas | neither | skip"
+  },
+  "scan": {
+    "findings": [{"id":"F1","category":"transition-all","title":"...","file":"...","line":123,"severity":"minor","evidence":"...","visibleDelta":true,"blastRadius":"single-file"}],
+    "bestFirstProofId": "F1",
+    "partial": false,
+    "inspected": {"files": 42, "root": "..."}
+  },
+  "generated_at": "2026-04-24T01:00:00Z"
+}
+```
+
+---
+
+## Output contract
+
+Write `.design/START-REPORT.md` exactly matching this shape. **All seven H2 sections must be present, in this order, even if empty.** The JSON block at the very end is mandatory.
+
+```markdown
+# GDD First-Run Report
+
+> Generated <generated_at> by `/gdd:start`. This report does not start a pipeline cycle — it is a 0→1 proof path. Run the suggested next command to continue.
+
+## What I inspected
+
+- **UI root:** `<detected.path>` (`<detected.kind>`, confidence `<detected.confidence>`)
+- **Framework:** `<detected.framework>` — <one-sentence confirmation or override note>
+- **Design system:** `<detected.design_system>` — <one-sentence note>
+- **Files scanned:** `<scan.inspected.files>`
+- **Pain hint:** <`interview.pain` or "none given">
+- **Budget:** `<interview.budget>` <"(timed out — partial scan)" if `scan.partial`>
+
+## Three findings
+
+<For each finding F1..F3, emit:>
+
+### <Fn> — <title>
+
+**Severity:** `<severity>` · **Evidence:** `<file>:<line>` · **Blast radius:** `<blastRadius>`
+
+<one-sentence plain-English rationale pointing at the evidence line>
+
+**Fix sketch:** <one-sentence concrete fix — e.g., "Replace `transition` with `transition-transform` on the wrapper.">
+
+<End per-finding block>
+
+## Best first proof
+
+**Pick:** `<bestFirstProofId>` — <re-state the finding title>
+
+<one paragraph: why this one. Cite the rubric condition that tipped the pick — single-file, non-ambiguous, visible delta, no token migration, low blast radius. If `bestFirstProofId` is null, write: "No finding qualified for a single-command fix under the safe-fix rubric — the report recommends the pipeline entry point below instead.">
+
+## Suggested next command
+
+```bash
+<exact command — one of:>
+/gdd:fast "<concrete description of the single fix>"
+/gdd:brief
+/gdd:scan
+```
+
+<one-line rationale: why this command and not the others.>
+
+## Visual Proof Readiness
+
+| Surface | Status | Unlock |
+|---------|--------|--------|
+| Preview MCP | <ok \| unconfigured \| unavailable> | <`/gdd:connections preview` or "already configured"> |
+| Storybook | <…> | <…> |
+| Figma | <…> | <`/gdd:connections figma` or "already configured"> |
+| Canvas (.canvas) | <…> | <…> |
+
+<one-line note if `interview.figma_workflow` picked a specific surface — nudge toward that one first.>
+
+## Full pipeline path
+
+If you want more than a single fix, the full pipeline would do this on this project: `/gdd:brief` to capture the design problem, `/gdd:explore` to inventory your components and interview for context, `/gdd:plan` to decompose the work, `/gdd:design` to execute, and `/gdd:verify` to score the result. The pipeline writes `.design/STATE.md` and runs across a real design cycle.
+
+## Connections / writeback optional
+
+If you want to push design decisions back into Figma, paper.design, pencil.dev, or a Claude Design handoff bundle, run `/gdd:connections` to wire up the surfaces. Writeback is never required — the pipeline runs code-first by default.
+
+---
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "<ISO-8601>",
+  "detected": {...copy verbatim from context...},
+  "findings": [...copy findings array with id, title, file, line, severity, category, blast_radius...],
+  "best_first_proof": "<bestFirstProofId or null>",
+  "suggested_command": { "kind": "fast|brief|scan", "text": "<exact command>" },
+  "visual_proof_readiness": { "preview": "...", "storybook": "...", "figma": "...", "canvas": "..." }
+}
+```
+```
+
+---
+
+## Section-by-section rules
+
+### What I inspected
+
+- Always list the six bullets. Mark "(timed out — partial scan)" only when `scan.partial === true`.
+- Never invent fields — only surface what is in the context JSON.
+
+### Three findings
+
+- Emit up to three entries. If fewer than three findings exist, emit what exists and add one italic note below: `> Only <N> finding raised — the engine did not hit its cap.`
+- Every finding block includes the evidence file:line. No finding may omit file:line.
+- Fix sketch is one concrete sentence — not a general principle, not a tutorial.
+
+### Best first proof
+
+- Reference `bestFirstProofId` exactly. If it is null, write the fallback paragraph.
+- Cite which rubric conditions the winning finding satisfies.
+
+### Suggested next command
+
+- If `bestFirstProofId` is non-null → emit `/gdd:fast "<task>"` where `<task>` is a one-line description tied to the finding's fix sketch.
+- If `bestFirstProofId` is null AND there are findings → emit `/gdd:brief` with rationale "the findings need a design decision the rubric cannot make for you."
+- If no findings at all → emit `/gdd:scan` with rationale "this codebase looks healthy at first glance — a full audit confirms."
+
+### Visual Proof Readiness
+
+- Always include all four rows. Unknown surfaces default to `unconfigured`.
+- Check `interview.figma_workflow` — if the user picked `figma`, `canvas`, or `neither`, phrase the unlock line to match.
+
+### Full pipeline path
+
+- Keep the paragraph short — one sentence of what the pipeline does plus the command sequence. Do not rephrase per run.
+
+### Connections / writeback optional
+
+- Keep the paragraph short. Never assert which surface is best; point at `/gdd:connections`.
+
+---
+
+## JSON block
+
+The JSON block at the bottom is the contract future `/gdd:fast` / `/gdd:do` invocations will consume. Shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "ISO-8601",
+  "detected": { "root", "kind", "framework", "design_system", "confidence" },
+  "findings": [{ "id", "title", "file", "line", "severity", "category", "blast_radius" }],
+  "best_first_proof": "F1" | null,
+  "suggested_command": { "kind": "fast" | "brief" | "scan", "text": "/gdd:fast \"...\"" },
+  "visual_proof_readiness": { "preview", "storybook", "figma", "canvas" }
+}
+```
+
+- Finding IDs stay stable `F1`..`F3`.
+- `text` is always a ready-to-run command, single-line.
+- All string values are JSON-safe — escape embedded quotes.
+
+---
+
+## Do Not
+
+- Do not write `.design/STATE.md`, `.design/config.json`, or any source file.
+- Do not invent findings that are not in the context JSON.
+- Do not re-score or re-rank findings — the engine already picked `bestFirstProofId` deterministically.
+- Do not add marketing prose, emojis, or playful copy.
+- Do not emit more than three findings.
+- Do not omit any of the seven H2 sections — even empty, they must exist for downstream regression fixtures.
+
+## START-WRITER COMPLETE

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/hooks/first-run-nudge.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# get-design-done — first-run nudge (Phase 14.7)
+# SessionStart hook. Silent-on-failure by policy: exits 0 on every error path.
+# Prints exactly one restrained line pointing at /gdd:start when all gates pass,
+# and nothing otherwise.
+
+set -u  # intentionally no -e: we want to fall through to exit 0
+
+# Silent logger — writes nothing by default. Set GDD_NUDGE_DEBUG=1 to enable stderr.
+log() {
+  if [ "${GDD_NUDGE_DEBUG:-0}" = "1" ]; then
+    printf '[gdd first-run-nudge] %s\n' "$*" >&2
+  fi
+}
+
+DESIGN_DIR="$(pwd)/.design"
+STATE="${DESIGN_DIR}/STATE.md"
+CONFIG="${DESIGN_DIR}/config.json"
+DISMISS_FLAG="${HOME:-$USERPROFILE}/.claude/gdd-nudge-dismissed"
+
+# Gate 1 — repo already has GDD state, suppress.
+has_design_state() {
+  [ -f "${CONFIG}" ] || [ -f "${STATE}" ]
+}
+
+# Gate 2 — per-install dismissal flag.
+is_dismissed() {
+  [ -f "${DISMISS_FLAG}" ]
+}
+
+# Gate 3 — STATE.md stage belongs to an active pipeline window.
+# Inherits the shape used by Phase 13.3 update-check.sh.
+read_state_stage() {
+  [ -f "${STATE}" ] || { printf ''; return; }
+  grep -E '^stage:' "${STATE}" 2>/dev/null | head -n1 | \
+    sed -E 's/^stage:[[:space:]]*"?([^"[:space:]]+)"?.*/\1/'
+}
+
+is_active_stage() {
+  local s
+  s="$(read_state_stage)"
+  case "${s}" in
+    plan|design|verify|executing|discussing) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Gate 4 — recent session history has a gdd:* command. We cannot reliably read
+# session history from a hook in all runtimes; when the signal is unavailable,
+# treat it as "unknown → not suppressed". This preserves the nudge's
+# usefulness without creating false suppression.
+has_recent_gdd_command() {
+  # Placeholder: no portable transcript path exposed to SessionStart hooks today.
+  # Keep the function for future wiring; for now always returns non-zero (unknown).
+  return 1
+}
+
+# MANDATORY sourcing guard: unit tests source this script to test the helper
+# functions without executing the main flow. Non-negotiable.
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  if has_design_state; then
+    log "design state present — suppress"
+    exit 0
+  fi
+  if is_dismissed; then
+    log "dismissal flag present — suppress"
+    exit 0
+  fi
+  if is_active_stage; then
+    log "active stage — suppress"
+    exit 0
+  fi
+  if has_recent_gdd_command; then
+    log "recent gdd:* command detected — suppress"
+    exit 0
+  fi
+  # All gates passed — emit the locked one-line nudge.
+  printf 'Tip: run /gdd:start to let GDD inspect this codebase and suggest one first fix.\n'
+  exit 0
+fi
+# When sourced (BASH_SOURCE != $0), fall through with function definitions loaded
+# and without side effects.

package/hooks/hooks.json

@@ -16,6 +16,14 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/update-check.sh\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/first-run-nudge.sh\""
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.14.7",
+  "version": "1.15.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -54,7 +54,19 @@
     "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"
   ],
   "skills": [
     "SKILL.md"

package/reference/anti-patterns.md

@@ -334,3 +334,72 @@ grep -rn "bounce\|elastic" src/ --include="*.css"
 - [ ] Bounce or elastic easing anywhere?
 
 If YES to any → rewrite that element before proceeding.
+
+---
+
+### BAN-10: Same Border-Radius on Nested Surfaces
+
+Applying the same `border-radius` to a container and an element inside it (when the element is separated by padding) makes the inner element appear to "float" — the radii should be concentric, not equal.
+
+**Grep (Tailwind):**
+```
+(rounded-\w+)[^"]*"[^>]*>\s*<[^>]*\1
+```
+**Grep (CSS):** Look for identical `border-radius` values in parent and child selectors within the same component.
+
+**Fix:** Apply the concentric formula: `innerRadius = outerRadius − padding`. See `reference/surfaces.md`.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+---
+
+### BAN-11: Tinted Image Outline
+
+Using a colored outline on images (e.g., `outline-slate-200`, `outline-gray-300`, or a hex-value outline color) competes visually with the image content and creates color contamination.
+
+**Grep (Tailwind):**
+```
+outline-(slate|zinc|neutral|gray|stone|blue|red|green|yellow|purple)-\d+
+```
+applied to `<img>` elements.
+
+**Grep (CSS):**
+```
+img\s*\{[^}]*outline:\s*[^}]*#[0-9a-fA-F]{3,8}
+```
+
+**Fix:** Use `outline: 1px solid rgba(0,0,0,0.08)` (light) or `outline: 1px solid rgba(255,255,255,0.08)` (dark). Pure black or white at low opacity only. See `reference/surfaces.md`.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+---
+
+### BAN-12: `transition: all`
+
+`transition: all` animates every animatable CSS property on the element, including layout-triggering properties (width, height, padding, margin). This causes layout recalculation on EVERY transition, creating jank and unexpected visual effects (e.g., a hover transition that also animates the element's size if any dimensions change).
+
+**Grep (CSS):**
+```
+transition:\s*all
+transition-property:\s*all
+```
+**Grep (Tailwind):** bare `\btransition\b` class (without a modifier like `transition-transform` or `transition-[specific-property]`).
+
+**Fix:** Specify the exact properties to animate. For hover effects: `transition: background-color 150ms, color 150ms, opacity 150ms`. For motion: `transition: transform 200ms, opacity 200ms`.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)
+
+---
+
+### BAN-13: `will-change: all`
+
+`will-change: all` promotes every animatable property to its own GPU compositor layer, consuming GPU memory for each property. On complex components this can allocate hundreds of MB of texture memory per instance, causing performance degradation and potential crashes on mobile.
+
+**Grep:**
+```
+will-change:\s*all
+```
+
+**Fix:** Restrict to specific compositing-safe properties: `will-change: transform`, `will-change: opacity`, `will-change: filter`, or `will-change: clip-path`. Remove entirely after animation completes. See `reference/motion.md` will-change section.
+
+Source: jakubkrehel/make-interfaces-feel-better (MIT)

package/reference/audit-scoring.md

@@ -124,7 +124,7 @@ Check for:
 - Content max-width enforced (prose: 65ch, layout: 1200–1440px)
 - Mobile breakpoint respected (no horizontal scroll)
 
-### 6. Anti-Pattern Compliance (Weight: 10%)
+### 6. Anti-Pattern Compliance (Weight: 5%)
 
 Score = 10 − (number of hard-ban violations × 3) − (number of AI-slop tells × 1), minimum 0.
 
@@ -155,8 +155,9 @@ Score = (Accessibility × 0.25)
       + (Typography × 0.15)
       + (Color × 0.15)
       + (Layout × 0.10)
-      + (Anti-Patterns × 0.10)
+      + (Anti-Patterns × 0.05)
       + (Motion × 0.05)
+      + (Micro-polish × 0.05)
 ```
 
 | Grade | Score | Meaning |
@@ -184,8 +185,9 @@ Baseline score: [N/100]
 | Typography | /10 | 15% | |
 | Color | /10 | 15% | |
 | Layout | /10 | 10% | |
-| Anti-Patterns | /10 | 10% | |
+| Anti-Patterns | /10 | 5% | |
 | Motion | /10 | 5% | |
+| Micro-polish | /10 | 5% | |
 | **Total** | | | **/100** |
 
 ### Findings
@@ -203,3 +205,32 @@ Baseline score: [N/100]
 | ... | | |
 | **Total** | /40 | **= NNG Score:** /100 |
 ```
+
+---
+
+<!-- BREAKING: Anti-Pattern Compliance pillar weight changed 10%→5% in v1.15.0; Micro-polish pillar added at 5%. Cross-cycle score comparisons should account for this change. -->
+
+### 8. Micro-polish (Weight: 5%)
+
+Text-wrap, font-smoothing, tabular-nums, concentric radius, image outlines, hit areas, canonical press scale, will-change discipline.
+
+| Score | Criteria |
+|---|---|
+| 10 | All 14 micro-polish checklist items pass |
+| 7–9 | 2–3 violations found |
+| 4–6 | 7 or more violations, core items failing (press scale, transition:all) |
+| 0–3 | Most items fail or not considered |
+
+Check for (see `reference/checklists.md` Micro-Polish Check gate):
+- Headings: `text-wrap: balance`; body/captions: `text-wrap: pretty`
+- Font smoothing at `:root` only
+- Dynamic numbers: `font-variant-numeric: tabular-nums`
+- Nested elements: concentric radius (`innerRadius = outerRadius − padding`)
+- Images: `outline: 1px solid rgba(0,0,0,0.08)` — no tinted outlines
+- Interactive elements <40px: `::after` hit-area extension to 40×40
+- Press feedback: `scale(0.96)` exactly
+- `AnimatePresence` on persistent UI: `initial={false}`
+- Icon cross-fade spring: `bounce: 0`
+- No `transition: all` (BAN-12)
+- No `will-change: all` (BAN-13)
+- `prefers-reduced-motion` respected