@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/scan/scan-procedure.md

@@ -0,0 +1,731 @@
+---
+name: scan-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [scan, procedure, extracted, pipeline-stage, design-system, audit]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/scan/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/scan/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (STATE integration, connection
+probes, extraction grep commands, scoring, output contracts).
+
+# Scan Procedure
+
+Detailed procedure for the get-design-done `scan` pre-pipeline initializer. Companion to
+`../skills/scan/SKILL.md`. Read this file when executing a specific scan step; the SKILL.md
+keeps the load-bearing workflow + decision tree, this file holds the deep methodology.
+
+---
+
+## 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>]
+
+---
+
+## 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
+
+# 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
+
+# Tailwind color config
+grep -A 100 '"colors"' tailwind.config.* 2>/dev/null | head -50
+```
+
+**Analyze the color data:**
+
+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?
+
+Produce a color inventory table:
+```
+| Color | Occurrences | Role (inferred) | Issues |
+```
+
+---
+
+## 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.
+
+### If `figma: available`
+
+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).
+
+> 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.
+
+**For each variable returned, apply the following translation:**
+
+| 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 |
+
+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.
+
+**Multi-mode (Light/Dark):** when `valuesByMode` has multiple entries, extract all values and note dark-mode existence in the DESIGN.md color section.
+
+### Merge, don't replace
+
+Keep grep-derived tokens from Step 2 AND Figma tokens. Both sets appear in DESIGN.md:
+
+- **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
+
+### DESIGN.md annotations required
+
+When this step runs successfully:
+
+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.
+
+---
+
+## 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
+
+# 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
+
+# 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] | [check/cross] |
+| sm | [Npx] | [N] | [check/cross] |
+
+**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 check, Input check, Modal cross, Toast cross, ...]
+
+## 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 with lightning bolt.
+
+## 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] (quick-win)
+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)
+```
+
+---
+
+## 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.
+=====================
+```