@hegemonart/get-design-done 1.28.0 → 1.28.5

package/skills/scan/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: scan
-description: "Design scanner for new or uninitialized repos. Automatically maps the existing design system (colors, typography, spacing, components, tokens), runs a full anti-pattern audit, scores all 7 categories, and produces two artifacts: DESIGN.md (living design system snapshot) and .design/DESIGN-DEBT.md (prioritized debt roadmap with effort estimates). Run this once before starting discovery in any new codebase."
+description: "Pre-pipeline initializer that maps an existing repo's design system (colors, typography, spacing, components, tokens), runs the anti-pattern audit, scores the 7 weighted categories, and writes DESIGN.md + .design/DESIGN-DEBT.md. Use when starting work in any new or existing repo before /gdd:discover."
 argument-hint: "[--quick] [--full]"
 user-invocable: true
 ---
 
 # Get Design Done — Scan
 
-**Pre-pipeline initializer.** Run once in any new or existing repo before starting the Discover → Plan → Design → Verify pipeline.
+**Pre-pipeline initializer.** Run once in any new or existing repo before starting the Discover -> Plan -> Design -> Verify pipeline.
+
+Full procedure detail: `../../reference/scan-procedure.md`.
 
 Produces:
 - `DESIGN.md` — snapshot of the existing design system as it actually is
@@ -22,710 +24,69 @@ Default: full scan of tokens, patterns, and anti-patterns. Component inventory i
 
 ## State Integration
 
-### Read or create STATE.md
-
 At scan entry, before running any step:
 
-1. Check for `.design/STATE.md`.
-   - **If missing:** create it from `reference/STATE-TEMPLATE.md`. Set the following fields:
-     - `started_at` = now (ISO 8601) — **set once; never overwrite on subsequent runs**
-     - `last_checkpoint` = now
-     - frontmatter `stage` = `scan`
-     - `<position>` `stage` = `scan`, `status` = `in_progress`, `task_progress` = `0/8`
-   - **If present and `stage == scan` and `status == in_progress`:** RESUME — skip already-complete steps using `task_progress` as offset. Do not reset `started_at`.
-   - **Otherwise (normal transition):** set frontmatter `stage = scan`, `<position>` `stage = scan`, `status = in_progress`, `task_progress = 0/8`. Do not overwrite `started_at`.
-
-### Probe connection availability
-
-Run both probes below. MCP tools may be in the deferred tool set — **always call ToolSearch first**; without it, a deferred tool invocation fails silently.
-
-**Figma probe (variant-agnostic — resolves any server prefix matching `/figma/i`):**
-
-```
-Step A1 — Keyword ToolSearch:
-  ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
-
-  Parse results for tool names matching:
-    - /^mcp__([^_]*figma[^_]*)__get_metadata$/i  → read-capable prefix set
-    - /^mcp__([^_]*figma[^_]*)__use_figma$/i     → write-capable prefix set
-
-  Empty read set      → figma: not_configured   (skip all Figma steps)
-  One or more matches → proceed to Step A2
-
-Step A2 — Tiebreaker selection:
-  Preference order when multiple read prefixes match:
-    1. Prefer prefixes that appear in BOTH read set and write set
-    2. Prefer `figma` (canonical remote server name)
-    3. Prefer non-`figma-desktop`
-    4. Alphabetical
-
-Step A3 — Live tool call on resolved prefix:
-  call mcp__<prefix>__get_metadata
-  → Success → figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
-  → Error   → figma: unavailable  (skip all Figma steps)
-```
-
-**Refero probe:**
-
-```
-Step B1 — ToolSearch check:
-  ToolSearch({ query: "refero", max_results: 5 })
-  → Empty result      → refero: not_configured  (use fallback chain)
-  → Non-empty result  → refero: available
-```
-
-Note: scan probes **both** connections because the State Integration block is the authoritative connection-detection point for the entire pipeline. Scan itself does not use Refero, but it writes the Refero status so downstream stages (discover) do not need to re-probe from scratch.
-
-### Phase 8 Connection Probes
-
-Run all 4 Phase 8 probes at scan entry. Results are written to STATE.md `<connections>` so downstream stages (verify, compare, darkmode, plan, design) do not re-probe unless needed.
-
-Note: as of v1.0.7.1, Figma is a single connection (`figma:` key) covering reads + writes — no separate `figma_writer:` probe. The Wave A Figma probe above is the sole Figma availability check.
-
-**preview:**
-
-```
-Step P1 — ToolSearch check:
-  ToolSearch({ query: "Claude_Preview", max_results: 5 })
-  → Empty result      → preview: not_configured
-  → Non-empty result  → proceed to Step P2
-
-Step P2 — Live tool call:
-  call mcp__Claude_Preview__preview_list
-  → Success           → preview: available
-  → Error             → preview: unavailable
-
-Write: preview: <status> to STATE.md <connections>
-```
-
-**storybook:**
-
-```
-Step B1 — Project detection:
-  Bash: ls .storybook/ 2>/dev/null || grep '"storybook"' package.json 2>/dev/null
-  → Found → storybook_project: true → proceed to Step B2
-  → Not found → storybook: not_configured
-
-Step B2 — Dev server detection:
-  Bash: curl -sf http://localhost:6006/index.json 2>/dev/null | head -1
-  → Returns JSON → storybook: available
-  → Fails → Bash: curl -sf http://localhost:6006/stories.json 2>/dev/null | head -1
-      → Returns JSON → storybook: available (compat endpoint)
-      → Fails → storybook: unavailable
-
-Write: storybook: <status> to STATE.md <connections>
-```
-
-**chromatic:**
-
-```
-Step C1 — CLI presence:
-  Bash: command -v chromatic 2>/dev/null || npx chromatic --version 2>/dev/null
-  → found → proceed to Step C2
-  → not found → chromatic: not_configured
-
-Step C2 — Token check:
-  Bash: test -n "${CHROMATIC_PROJECT_TOKEN}"
-  → true → chromatic: available
-  → false → chromatic: unavailable
-
-Write: chromatic: <status> to STATE.md <connections>
-```
-
-**graphify:**
-
-```
-Step G1 — Config check:
-  Bash: node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
-  → Error or { enabled: false } → graphify: not_configured
-  → { enabled: true }           → proceed to Step G2
-
-Step G2 — Graph file check:
-  Bash: test -f graphify-out/graph.json
-  → Present → graphify: available
-  → Absent  → graphify: unavailable
-
-Write: graphify: <status> to STATE.md <connections>
-```
-
-After all 4 probes, STATE.md `<connections>` contains all 4 status entries (plus the Wave A `figma:` and `refero:` probes = 6 total entries). Downstream plans (08-02 through 08-05) read these values without re-probing.
-
-**First-run connection nudge:** after writing STATE.md, check whether every probed connection came back `not_configured` AND `.design/config.json > connections_onboarding` is absent. If so, print once at the end of scan output:
-
-```
-Tip: run /gdd:connections to walk through setup for Figma, Storybook, Chromatic, and 9 other integrations.
-```
-
-Suppress the nudge if any probe returned `available` or `unavailable`, or if the user has already run `/gdd:connections` (marker: `connections_onboarding` block present or previously drained).
-
-### Write STATE.md
-
-Update `.design/STATE.md` with probe results:
-
-```xml
-<connections>
-figma: <available | unavailable | not_configured>
-refero: <available | not_configured>
-preview: <available | unavailable | not_configured>
-storybook: <available | unavailable | not_configured>
-chromatic: <available | unavailable | not_configured>
-graphify: <available | unavailable | not_configured>
-</connections>
-```
-
-Update `last_checkpoint` to now. Write `.design/STATE.md` to disk before proceeding to Step 1.
-
----
-
-## Step 1 — Orient
-
-Identify the project structure before scanning:
-
-```bash
-# Framework detection
-cat package.json 2>/dev/null | grep -E '"(next|nuxt|vite|react|vue|svelte|remix|astro|tailwind)"' | head -20
-
-# CSS approach
-ls src/styles/ styles/ app/styles/ 2>/dev/null
-find . -name "tailwind.config.*" -not -path "*/node_modules/*" 2>/dev/null | head -3
-find . -name "*.tokens.json" -o -name "design-tokens.*" -o -name "tokens.css" 2>/dev/null | grep -v node_modules | head -5
-
-# Component count
-find . -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | grep -v node_modules | wc -l
-
-# Style file count
-find . -name "*.css" -o -name "*.scss" -o -name "*.less" 2>/dev/null | grep -v node_modules | wc -l
-```
-
-Record: framework, CSS approach, component count, style file count, token system (yes/no).
-
-**Detect source root.** Check these directories in order and use the first one that exists:
-`src/` → `app/` → `pages/` → `lib/`. Substitute the detected source root (the matched
-directory name) into every subsequent grep command in this SKILL.md that currently references
-`src/` as the primary component root. If none of these directories exist, log
-"No standard source directory found — manual audit required" and proceed with the unchanged
-command (the `2>/dev/null` guards will suppress the no-match output).
-
-Log the detected source root in DESIGN.md frontmatter as:
-    source_roots: [<detected_dir>]
+1. Read or create `.design/STATE.md` from `reference/STATE-TEMPLATE.md` (set `stage=scan`, `status=in_progress`, `task_progress=0/8`; preserve `started_at` on resume). See `../../reference/scan-procedure.md` §State Integration for the full read/create/resume decision tree.
+2. Probe Figma + Refero connections (variant-agnostic ToolSearch + tiebreaker resolution). Detail: `../../reference/scan-procedure.md` §Probe connection availability.
+3. Run the four Phase 8 probes (preview, storybook, chromatic, graphify) and batch-write results to STATE.md `<connections>`. Detail: `../../reference/scan-procedure.md` §Phase 8 Connection Probes.
+4. Emit the first-run connection nudge if every probe returned `not_configured` AND `.design/config.json > connections_onboarding` is absent.
+5. Update `last_checkpoint`; persist STATE.md before proceeding to Step 1.
 
 ---
 
-## Step 2 — Extract Color System
-
-```bash
-# All hex colors used
-grep -roh "#[0-9a-fA-F]\{3,8\}" src/ styles/ app/ --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" --include="*.ts" --include="*.vue" 2>/dev/null | sort | uniq -c | sort -rn | head -40
-
-# oklch / hsl / rgb colors
-grep -rEoh "oklch\([^)]*\)|hsl\([^)]*\)|rgb\([^)]*\)" src/ styles/ --include="*.css" --include="*.scss" 2>/dev/null | sort | uniq -c | sort -rn | head -20
+## Workflow
 
-# CSS custom properties (color tokens)
-grep -rEoh "\-\-[a-z][a-z0-9\-]*color[a-z0-9\-]*:\s*[^;]*|\-\-color[a-z0-9\-]*:\s*[^;]*" src/ styles/ --include="*.css" --include="*.scss" 2>/dev/null | sort | uniq | head -30
+The scan executes eight steps in order. Each step's full grep commands, analysis prompts, and decision rules live in `../../reference/scan-procedure.md` — keep that file open while executing.
 
-# Tailwind color config
-grep -A 100 '"colors"' tailwind.config.* 2>/dev/null | head -50
-```
+### Step 1 — Orient
 
-**Analyze the color data:**
+Detect framework, CSS approach, component count, style file count, token system. Detect source root by ordered fallback (`src/` -> `app/` -> `pages/` -> `lib/`) and substitute into subsequent grep commands. Log the detected source root in DESIGN.md frontmatter. Detail: `../../reference/scan-procedure.md` §Step 1.
 
-1. How many unique colors? (< 10 = disciplined, 10–25 = moderate, > 25 = ad-hoc)
-2. Is there a token layer (CSS custom properties)? Or raw hex in components?
-3. Does the palette contain AI-slop colors? (#6366f1, #8b5cf6, #06b6d4)
-4. Are there semantic roles evident from naming? (`--color-primary`, `--color-danger`)
-5. Is pure black (#000000) used in dark mode?
+### Step 2 — Extract Color System
 
-Produce a color inventory table:
-```
-| Color | Occurrences | Role (inferred) | Issues |
-```
+Grep hex / `oklch()` / `hsl()` / `rgb()` colors, CSS custom properties, and Tailwind color config. Analyze palette size, token discipline, AI-slop colors (#6366f1, #8b5cf6, #06b6d4), semantic naming, dark-mode purity. Produce a color inventory table. Detail: `../../reference/scan-procedure.md` §Step 2.
 
----
-
-## Step 2A — Figma Token Augmentation
-
-**Skip this step if `figma` is `not_configured` or `unavailable` in `.design/STATE.md` `<connections>`.** Fall back to the grep-based token extraction from Step 2 alone — no error, no warning. Scan continues normally.
+### Step 2A — Figma Token Augmentation
 
-### If `figma: available`
+If `figma: available` in STATE.md `<connections>`: call `{prefix}get_variable_defs`, translate variables by type/name pattern, merge with grep-derived tokens (never replace). Skip silently if `figma` is `not_configured` or `unavailable`. Detail: `../../reference/scan-procedure.md` §Step 2A.
 
-Read the resolved prefix from STATE.md `<connections>` (e.g., `prefix=mcp__figma__` or `prefix=mcp__figma-desktop__`) and call `{prefix}get_variable_defs` (no arguments — returns all variables in the active Figma file).
+### Step 3 — Extract Typography System
 
-> If no Figma file is open, the call errors. Treat any error as a graceful skip: update STATE.md `<connections>` to `figma: unavailable` and continue with Step 2 results only.
+Grep font families, sizes, weights, line-heights. Analyze family count, scale compliance, weight hierarchy, line-height on body, reflex-font signals. Read `${CLAUDE_PLUGIN_ROOT}/reference/typography.md` for comparison criteria. Detail: `../../reference/scan-procedure.md` §Step 3.
 
-**For each variable returned, apply the following translation:**
+### Step 4 — Extract Spacing System
 
-| Variable type | Name pattern | Output |
-|---------------|--------------|--------|
-| `COLOR` | any | Add row to color inventory table |
-| `FLOAT` | `spacing/*` | Add row to spacing system |
-| `FLOAT` | `font-size/*` or `typography/*` | Add row to typography system |
+Grep CSS spacing values, Tailwind spacing overrides, space tokens. Score grid compliance against the 4/8/12/16/24/32/48/64 series. Detail: `../../reference/scan-procedure.md` §Step 4.
 
-Record both the variable **NAME** and resolved value — not just the value. `get_variable_defs` returns resolved values only (no alias chains); the name often carries semantic meaning the value cannot.
+### Step 5 — Anti-Pattern Audit
 
-**Multi-mode (Light/Dark):** when `valuesByMode` has multiple entries, extract all values and note dark-mode existence in the DESIGN.md color section.
+Read `${CLAUDE_PLUGIN_ROOT}/reference/anti-patterns.md`. Run all BAN-XX and SLOP-XX grep commands, plus a11y checks (focus rings, reduced-motion, div onClick, small fonts). Detail: `../../reference/scan-procedure.md` §Step 5.
 
-### Merge, don't replace
+### Step 6 — Component Inventory
 
-Keep grep-derived tokens from Step 2 AND Figma tokens. Both sets appear in DESIGN.md:
+If `--quick`, skip. Otherwise run the three-pass multi-signal filter (JSX-return + className + framework-import) to produce an authoritative component list, then enumerate primitives. In `--full` mode, emit one row per file. Detail: `../../reference/scan-procedure.md` §Step 6.
 
-- **Figma-only tokens** (in Figma, not in CSS): annotate as "design intention not yet implemented"
-- **Code-only tokens** (in CSS, not in Figma): annotate as "implementation drift or local override"
-- **Matching tokens**: show Figma value alongside CSS value; flag any discrepancy
+### Step 7 — Score All 7 Categories
 
-### DESIGN.md annotations required
+Read `${CLAUDE_PLUGIN_ROOT}/reference/audit-scoring.md`. Score each category 0–10 and apply the weighted formula `(A11Y * 0.25) + (Visual Hierarchy * 0.20) + (Typography * 0.15) + (Color * 0.15) + (Layout * 0.10) + (Anti-Patterns * 0.10) + (Motion * 0.05)`. Grade A=90+, B=75+, C=60+, D=45+, F<45.
 
-When this step runs successfully:
+### Step 8 — Generate Design Debt Roadmap
 
-1. Change the token layer section header from "CSS custom properties" to "CSS custom properties + Figma variables"
-2. Add to DESIGN.md frontmatter:
-   - `figma_variables_used: true`
-   - `figma_source: [list of collection names returned by get_variable_defs]`
-
-### Caveats
-
-- `get_variable_defs` returns **resolved values only** — no alias chains. Always record the variable NAME alongside the value; the name carries semantic meaning not present in the hex/float alone.
-- **Multi-mode:** when Light and Dark mode values differ, record both. Note dark-mode variable presence in the DESIGN.md color section.
-- **No file open:** if `get_variable_defs` errors (most commonly because no Figma file is open), skip this step entirely and update STATE.md `<connections>` to `figma: unavailable`. Do not error the scan stage.
+Classify each finding P0/P1/P2/P3, estimate effort XS/S/M/L/XL, group by debt theme, compute `priority_score = (severity_weight * effort_weight) + (dependency_depth * 2)`. Mark P1+XS/S items as quick wins. Detail: `../../reference/scan-procedure.md` §Step 8.
 
 ---
 
-## Step 3 — Extract Typography System
-
-```bash
-# Font families
-grep -rEoh "font-family:\s*[^;]*|fontFamily:\s*[^,}]*" src/ styles/ --include="*.css" --include="*.scss" --include="*.ts" --include="*.tsx" 2>/dev/null | sort | uniq -c | sort -rn | head -20
+## Outputs
 
-# Font sizes
-grep -rEoh "font-size:\s*[0-9.]*\(rem|px|em\)|text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)" src/ styles/ --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" 2>/dev/null | sort | uniq -c | sort -rn | head -30
+Write both artifacts using the templates in `../../reference/scan-procedure.md`:
 
-# Font weights
-grep -rEoh "font-weight:\s*[0-9]*|fw-[0-9]*|font-(thin|light|normal|medium|semibold|bold|extrabold|black)" src/ styles/ --include="*.css" --include="*.scss" --include="*.tsx" 2>/dev/null | sort | uniq -c | sort -rn | head -20
-
-# Line heights
-grep -rEoh "line-height:\s*[0-9.]*|leading-[a-z0-9]*" src/ styles/ --include="*.css" --include="*.scss" --include="*.tsx" 2>/dev/null | sort | uniq -c | sort -rn | head -15
-```
-
-**Analyze:**
-
-1. How many font families? (> 2 = violation unless one is monospace)
-2. Are font sizes from a defined scale or arbitrary px?
-3. Map found sizes to nearest modular scale — identify outliers
-4. Are weights following hierarchy? (body 400, headings 600-700, never 300 on small text)
-5. Line-height on body text — is it 1.5–1.75?
-6. Any of the reflex fonts without apparent brand reason? (Inter, DM Sans, Space Grotesk, Plus Jakarta Sans)
-
-Read `${CLAUDE_PLUGIN_ROOT}/reference/typography.md` for comparison criteria.
-
-Produce a typography inventory table.
-
----
-
-## Step 4 — Extract Spacing System
-
-```bash
-# All CSS spacing values
-grep -rEoh "padding:\s*[0-9]*px|margin:\s*[0-9]*px|gap:\s*[0-9]*px" src/ styles/ --include="*.css" --include="*.scss" 2>/dev/null | grep -oh "[0-9]*px" | sort -n | uniq -c | sort -rn | head -20
-
-# Tailwind spacing overrides
-grep -A 30 '"spacing"' tailwind.config.* 2>/dev/null | head -35
-
-# Space tokens
-grep -rEoh "\-\-space[a-z0-9\-]*:\s*[^;]*|\-\-spacing[a-z0-9\-]*:\s*[^;]*" src/ styles/ --include="*.css" 2>/dev/null | head -20
-```
-
-**Analyze:**
-
-Grid compliance: are spacing values in the 4/8/12/16/24/32/48/64 series? Flag any values not in this set (e.g., 13px, 22px, 37px are off-grid).
-
----
-
-## Step 5 — Anti-Pattern Audit
-
-Read `${CLAUDE_PLUGIN_ROOT}/reference/anti-patterns.md`. Run all grep commands.
-
-```bash
-# BAN violations (−3 each from Anti-Pattern score)
-echo "=== BAN-01: Side-stripe borders ===" && grep -rEn "border-left:\s*[2-9][0-9]*px|border-right:\s*[2-9][0-9]*px" src/ --include="*.css" --include="*.scss" --include="*.tsx" 2>/dev/null
-echo "=== BAN-02: Gradient text ===" && grep -rEn "background-clip:\s*text|text-fill-color:\s*transparent" src/ 2>/dev/null
-echo "=== BAN-03: Bounce easing ===" && grep -rEn "cubic-bezier\(.*-[0-9]|bounce|elastic" src/ --include="*.css" --include="*.scss" 2>/dev/null
-echo "=== BAN-08: transition: all ===" && grep -rnE "transition:[[:space:]]*all([^a-zA-Z]|$)" src/ --include="*.css" --include="*.scss" --include="*.tsx" 2>/dev/null | head -10
-echo "=== BAN-05: Pure black dark mode ===" && grep -rEn "#000000\b|rgb\(0,\s*0,\s*0\)" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
-echo "=== BAN-06: Disable zoom ===" && grep -rEn "user-scalable=no|maximum-scale=1" public/ src/ 2>/dev/null
-echo "=== BAN-07: outline:none without replacement ===" && grep -rnE ":focus[[:space:]]*\{" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
-
-# SLOP signals (−1 each)
-echo "=== SLOP-01: AI palette ===" && grep -rEn "#6366f1|#8b5cf6|#06b6d4" src/ 2>/dev/null | head -5
-echo "=== SLOP-04: backdrop-filter ===" && grep -rnE "backdrop-filter:[[:space:]]*blur" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
-
-# Accessibility
-echo "=== A11Y: focus rings ===" && grep -rEn "outline:\s*none|outline:\s*0" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
-echo "=== A11Y: reduced motion ===" && grep -rn "prefers-reduced-motion" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -3
-echo "=== A11Y: div onClick ===" && grep -rEn "onClick.*div|<div.*onClick" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -5
-echo "=== A11Y: small font ===" && grep -rEn "font-size:\s*1[0-5]px|font-size:\s*[0-9]px" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -5
-```
-
-For each finding: record the count, a sample file:line, and severity (BAN = P0, SLOP = P1, A11Y = P0–P1 depending on type).
-
----
-
-## Step 6 — Component Inventory
-
-If `--quick`, skip this step.
-
-### Component pattern indicators
-
-A bare `grep -rln "className" src/` produces false positives on type-only files, test files, utility helpers, and server-only modules — none of which are components. Instead, use a three-pass multi-signal filter. A file qualifies as a component only when **all three indicators** match:
-
-1. Has a JSX-like return: `grep -lE "return\s*\(" <file>`
-2. Has className or class attribute usage: `grep -lE "className=|class=" <file>`
-3. Has a component framework import: `grep -lE "from ['\"](react|preact|vue)" <file>`
-
-```bash
-# Component inventory — three-pass filter (requires all three signals)
-
-# Pass 1: files with JSX-like return statements
-grep -rlE "return\s*\(" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null \
-  | grep -vE "\.test\.|\.spec\.|\.stories\." > /tmp/scan-pass1.txt
-
-# Pass 2: intersect with className/class presence
-grep -lE "className=|class=" $(cat /tmp/scan-pass1.txt) 2>/dev/null > /tmp/scan-pass2.txt
-
-# Pass 3: intersect with framework import (react, preact, or vue)
-grep -lE "from ['\"](react|preact|vue)" $(cat /tmp/scan-pass2.txt) 2>/dev/null > /tmp/components.txt
-
-# Count and list
-wc -l < /tmp/components.txt
-cat /tmp/components.txt
-```
-
-This produces a component inventory that excludes false positives. The resulting file list is the authoritative component set for the rest of this step.
-
-```bash
-# Count components by directory (from the filtered list)
-xargs dirname < /tmp/components.txt | sort | uniq -c | sort -rn | head -20
-
-# Look for design system component patterns
-grep -rEln "Button|Modal|Dialog|Toast|Tooltip|Badge|Card|Input|Select|Dropdown|Table|Tab|Accordion" \
-  $(cat /tmp/components.txt) 2>/dev/null | grep -v node_modules | head -20
-```
-
-Identify:
-- Core UI primitives that exist (Button, Input, Modal, etc.)
-- Which have design system-level implementation vs. one-off styles
-- Which are candidates for design system extraction
-
-### --full mode per-file output
-
-If `--full` flag is set, emit one row per file in the component inventory:
-
-| File | Component Count | Styling Approach | Token Usage | Issues |
-|------|-----------------|------------------|-------------|--------|
-| src/components/Button.tsx | 1 | Tailwind | var(--primary), p-4, gap-2 | heading weight dup |
-| src/components/Card.tsx | 1 | CSS Module | styles.card, rgb(...) | hardcoded color |
-
-Columns:
-- **File**: relative path from repo root
-- **Component Count**: number of exported components in file (grep `export.*function\|export.*const.*=.*\(.*=>`)
-- **Styling Approach**: `Tailwind` | `CSS Module` | `styled-components` | `inline` | `mixed`
-- **Token Usage**: comma-separated tokens/values found (max 5, "+N more" if there are more)
-- **Issues**: short flags for known problems (e.g., `hardcoded color`, `off-grid spacing`, `heading weight dup`)
-
-Without `--full`, the component inventory is a summary count only (not per-file).
-
----
-
-## Step 7 — Score All 7 Categories
-
-Read `${CLAUDE_PLUGIN_ROOT}/reference/audit-scoring.md`. Score each category 0–10 based on what you found in Steps 1–6.
-
-Apply the weighted formula:
-```
-Score = (Accessibility × 0.25) + (Visual Hierarchy × 0.20) + (Typography × 0.15)
-      + (Color × 0.15) + (Layout × 0.10) + (Anti-Patterns × 0.10) + (Motion × 0.05)
-```
-
-Calculate grade (A=90–100, B=75–89, C=60–74, D=45–59, F=0–44).
-
----
-
-## Step 8 — Generate Design Debt Roadmap
-
-Collect all findings from Steps 1–6. Classify each:
-
-| Severity | Code | Rule |
-|---|---|---|
-| Blocker | P0 | BAN violations, contrast failures, keyboard nav broken |
-| Major | P1 | SLOP signals, no token layer, off-grid spacing, no scale system |
-| Minor | P2 | Reflex font without reason, inconsistent weights, redundant colors |
-| Cosmetic | P3 | Polish items, minor naming inconsistencies |
-
-Group into **debt themes**:
-
-1. **Foundation** — token layer, design system architecture
-2. **Typography** — scale, hierarchy, families
-3. **Color** — palette, semantics, dark mode
-4. **Accessibility** — contrast, focus, semantics, motion
-5. **Anti-Patterns** — BAN + SLOP removals
-6. **Components** — inconsistency, missing primitives
-7. **Motion** — easing, duration, reduced-motion
-
-For each debt item, estimate effort:
-- `XS` — single-line grep-and-replace (< 30 min)
-- `S` — localized fix in 1–3 files (< 2h)
-- `M` — affects 5–15 files, requires testing (2–8h)
-- `L` — architectural change, touches 15+ files (1–3 days)
-- `XL` — design system rebuild (3+ days)
-
-### Priority score for ordering DESIGN-DEBT.md entries
-
-Each debt item gets three scores:
-
-- **severity_weight**: `{ P0: 4, P1: 3, P2: 2, P3: 1 }`
-- **effort_weight**: `{ XS: 5, S: 4, M: 3, L: 2, XL: 1 }` — high effort = lower priority
-- **dependency_depth**: count of other debt items this fix unblocks
-
-Formula:
-
-```
-priority_score = (severity_weight × effort_weight) + (dependency_depth × 2)
-```
-
-Ordering rules:
-1. Sort entries by `priority_score` descending (highest first)
-2. Tiebreak: file count descending (more files affected = more impact)
-3. Second tiebreak: alphabetical by item ID (D-001 before D-002)
-
-Example: A P1 issue (`severity_weight = 3`) with S effort (`effort_weight = 4`) that unblocks 2 other items (`dependency_depth = 2`) scores: `(3 × 4) + (2 × 2) = 16`. A P0 issue (`4`) with XL effort (`1`) with no dependencies scores: `(4 × 1) + 0 = 4`. The P1 ranks above the P0 despite lower severity because its XL effort makes the P0 low ROI.
-
-Identify **quick wins**: P1 issues with XS/S effort — these have the best ROI.
-Identify **blocking dependencies**: fixes that must happen before others (e.g., token layer before dark mode).
-
----
-
-## Output 1: DESIGN.md
-
-Write `DESIGN.md` at the project root:
-
-```markdown
----
-generated: [ISO 8601]
-tool: get-design-done scan
-score: [N]/100 ([grade])
-framework: [name]
-css_approach: [tailwind | css-modules | styled-components | plain-css | mixed]
-token_layer: true | false
----
-
-# Design System Snapshot — [Project Name]
-
-> Auto-generated by get-design-done scan. Update manually when the system evolves.
-
-## Current Score
-
-| Category | Score | Grade |
-|---|---|---|
-| Accessibility | [N]/10 | |
-| Visual Hierarchy | [N]/10 | |
-| Typography | [N]/10 | |
-| Color | [N]/10 | |
-| Layout & Spacing | [N]/10 | |
-| Anti-Patterns | [N]/10 | |
-| Motion | [N]/10 | |
-| **Weighted Total** | **[N]/100** | **[grade]** |
-
-## Color System
-
-**Token layer:** [Yes — CSS custom properties / No — raw values in components]
-
-**Palette inventory:**
-| Color | Hex | Role | Occurrences | Issues |
-|---|---|---|---|---|
-| Primary | #[hex] | [inferred role] | [N] | [any issues] |
-
-**Semantic consistency:** [Pass / Fail — describe]
-**Dark mode:** [Yes / No / Partial] — [pure black: yes/no]
-**AI-slop palette present:** [Yes (#6366f1 etc.) / No]
-
-## Typography System
-
-**Families used:** [family 1], [family 2]
-**Scale:** [defined modular scale / ad-hoc px values / Tailwind defaults]
-
-| Token | Size | Found occurrences | Scale-compliant |
-|---|---|---|---|
-| body | [Npx] | [N] | [✓/✗] |
-| sm | [Npx] | [N] | [✓/✗] |
-
-**Line-height body:** [value] ([pass ≥1.5 / fail])
-**Weight hierarchy:** [described]
-**Off-scale values found:** [list any non-standard sizes]
-
-## Spacing System
-
-**Grid:** [8pt / 4pt / ad-hoc / Tailwind defaults]
-**Non-grid values found:** [list off-grid values with occurrence count]
-
-## Component Inventory
-
-**Total components:** [N]
-**With consistent styling:** [N] (~[N]%)
-**Core primitives present:** [Button ✓, Input ✓, Modal ✗, Toast ✗, ...]
-
-## Anti-Pattern Status
-
-| Pattern | Status | Occurrences | Locations |
-|---|---|---|---|
-| BAN-01: Side-stripe border | [✓ Clear / ✗ Found] | [N] | [file:line] |
-| BAN-02: Gradient text | [✓ Clear / ✗ Found] | [N] | |
-| BAN-03: Bounce easing | [✓ Clear / ✗ Found] | [N] | |
-| BAN-07: outline:none | [✓ Clear / ✗ Found] | [N] | |
-| BAN-08: transition:all | [✓ Clear / ✗ Found] | [N] | |
-| SLOP-01: AI palette | [✓ Clear / ✗ Found] | [N] | |
-| SLOP-04: backdrop-filter | [✓ Clear / ✗ Found] | [N] | |
-
-## Motion / Animation
-
-**prefers-reduced-motion:** [Implemented / Missing]
-**Easing used:** [list found easing values]
-**Bounce/elastic:** [Found / None]
-```
-
----
-
-## Output 2: .design/DESIGN-DEBT.md
-
-Create `.design/` if needed. Write `.design/DESIGN-DEBT.md`:
-
-```markdown
----
-generated: [ISO 8601]
-score: [N]/100 ([grade])
-p0_count: [N]
-p1_count: [N]
-p2_count: [N]
-p3_count: [N]
----
-
-# Design Debt — [Project Name]
-
-> Prioritized roadmap of design issues found by get-design-done scan.
-> Fix P0s before shipping. Work through P1s in priority order.
-> Quick wins (P1 + XS/S effort) are marked ⚡.
-
-## Summary
-
-| Severity | Count | Est. Total Effort |
-|---|---|---|
-| P0 Blocker | [N] | [sum of estimates] |
-| P1 Major | [N] | [sum] |
-| P2 Minor | [N] | [sum] |
-| P3 Cosmetic | [N] | [sum] |
-
-**Category score to improve first:** [lowest-scoring category] ([N]/10) — highest impact on overall score.
-
----
-
-## P0 — Blockers (fix before shipping)
-
-### D-001 — [Issue title]
-Category: [scoring category]
-Theme: [foundation | typography | color | accessibility | anti-patterns | components | motion]
-Severity: [P0/P1/P2/P3]
-Effort: [XS/S/M/L/XL]
-priority_score: [computed: (severity_weight × effort_weight) + (dependency_depth × 2)]
-Description: [What the issue is and where it was found]
-Evidence: [file:line or grep pattern that found it]
-Fix: [Concrete steps to fix — specific enough to execute without extra research]
-Acceptance: [What pass looks like — verifiable]
-Depends on: [D-XXX if this fix requires another fix first, else "none"]
-Dependency depth: [N — count of items this fix unblocks]
-
----
-
-## P1 — Major (fix in current design pass)
-
-### D-010 — [Issue title] ⚡
-Category: [category]
-Theme: [theme]
-Severity: P1
-Effort: XS
-priority_score: [computed: (3 × 5) + (dependency_depth × 2) = 15+]
-Description: [...]
-Evidence: [...]
-Fix: [...]
-Acceptance: [...]
-Dependency depth: [N]
-
----
-
-## P2 — Minor (fix if time allows)
-
-[same structure]
-
----
-
-## P3 — Cosmetic (deferred to polish pass)
-
-[same structure]
-
----
-
-## Recommended Fix Order
-
-Based on dependencies and ROI:
-
-1. **[D-XXX]** — [title] (unblocks [D-XXX, D-XXX])
-2. **[D-XXX]** — ⚡ quick win
-3. **[D-XXX]** — [title]
-...
-
-## Pipeline Recommendation
-
-Given the scan results:
-
-```
-Suggested first pipeline run:
-  /get-design-done:discover --auto
-    → Will use DESIGN.md as baseline context
-  /get-design-done:plan
-    → Scope: address all P0s + top 5 P1s
-  /get-design-done:design
-  /get-design-done:verify
-    → Target score: [current + 15 points minimum]
-```
-
-Focus areas for first design pass:
-1. [highest-impact category]: [specific what to fix]
-2. [second-highest-impact]: [specific what to fix]
-3. Quick wins: [D-XXX], [D-XXX], [D-XXX] (all XS effort, instant score gain)
-```
+- **`DESIGN.md`** (project root) — design-system snapshot with score table, color/typography/spacing/component inventories, anti-pattern status, motion summary. Frontmatter records `score`, `framework`, `css_approach`, `token_layer`, and (if Figma ran) `figma_variables_used` + `figma_source`. Template: `../../reference/scan-procedure.md` §Output 1.
+- **`.design/DESIGN-DEBT.md`** — prioritized debt roadmap grouped P0/P1/P2/P3, with priority_score ordering, recommended fix order, and pipeline recommendation. Template: `../../reference/scan-procedure.md` §Output 2.
 
 ---
 
 ## After Writing
 
-```
-━━━ Scan complete ━━━
-Project:  [name]
-Score:    [N]/100 ([grade])
-P0 blockers:  [N]
-P1 major:     [N]
-Quick wins:   [N] (P1 + XS/S effort)
-
-Artifacts written:
-  DESIGN.md           — design system snapshot
-  .design/DESIGN-DEBT.md — prioritized debt roadmap
-
-Next steps:
-  Option A — Start the pipeline:
-    /get-design-done:discover
-    (DESIGN.md will be used as baseline context)
-
-  Option B — Fix quick wins first, then start:
-    [list top 3 quick win fixes inline]
-    Then: /get-design-done:discover
-
-  Option C — Just reference the debt:
-    DESIGN-DEBT.md is your backlog. Filter by theme or severity.
-━━━━━━━━━━━━━━━━━━━━━
-```
+Print the user-facing summary block from `../../reference/scan-procedure.md` §After Writing — project name, score, P0/P1 counts, quick-win count, artifact paths, and next-step options (start pipeline, fix quick wins first, or just reference the debt).
+
+## SCAN COMPLETE