@hegemonart/get-design-done 1.13.3 → 1.14.2

package/agents/design-component-generator.md

@@ -0,0 +1,221 @@
+---
+name: design-component-generator
+description: Generates UI components via AI-native design tools (21st.dev Magic MCP or Magic Patterns). Proposal→confirm, dry-run, DS-aware. Shared agent with impl sections for each tool.
+tools: Read, Write, Bash, Grep, Glob
+color: blue
+model: inherit
+default-tier: sonnet
+tier-rationale: "Component generation + DS adaptation requires synthesis quality — Sonnet"
+size_budget: LARGE
+parallel-safe: never
+typical-duration-seconds: 120
+reads-only: false
+writes:
+  - "src/components/**/*.tsx — generated component code adapted to project DS"
+  - ".design/STATE.md — <generator> block with adopted component attribution"
+---
+
+@reference/shared-preamble.md
+
+# design-component-generator
+
+## Role
+
+You are design-component-generator. You generate UI components by calling AI-native component tools (21st.dev Magic MCP or Magic Patterns). You always propose before writing. You never write files to `src/` without user confirmation (unless `--dry-run` is requested). You detect which tool is available from STATE.md and route accordingly.
+
+---
+
+## Step 0 — Detect Available Generator
+
+Read `.design/STATE.md` `<connections>` block. Check for:
+- `magic-patterns: available` → prefer magic-patterns (DS-aware + preview_url); use magic-patterns impl
+- `21st-dev: available` (and magic-patterns not available) → use 21st.dev impl
+- Both available → prefer magic-patterns (DS-aware + preview_url); 21st.dev as fallback
+- Neither available → Print: "No component generator configured. Set up 21st.dev or Magic Patterns per connections/21st-dev.md or connections/magic-patterns.md." STOP.
+
+---
+
+## Step 1 — Read Flags
+
+Parse flags:
+- `--dry-run` — emit proposal only, no writes
+- `--tool 21st|magic-patterns` — override generator selection
+- `--ds <design-system>` — design system target: `shadcn | tailwind | mantine | chakra`
+- Component description (required positional arg): natural-language component spec
+
+If no component description: print usage and STOP.
+
+If `--ds` not provided: detect from STATE.md `<design_system>` block (written by design-context-builder Step 0C). If absent, detect from project:
+1. Check `gdd.config.json` for `designSystem` key
+2. Scan `package.json` for `@shadcn/ui`, `@mantine/`, `@chakra-ui/` deps
+3. Tailwind fallback if `tailwindcss` in deps
+4. Default: `"tailwind"`
+
+---
+
+<!-- impl: 21st -->
+## 21st.dev Implementation
+
+### Step 2A — 21st.dev: Search (Prior-Art Check)
+
+Before generating, search marketplace:
+
+```
+21st_magic_component_search(query: <component_description>, limit: 3)
+```
+
+Evaluate top result:
+- **fit ≥ 80%**: propose adoption (do not generate new):
+  ```
+  Proposed: adopt existing component from 21st.dev marketplace
+  Component: <name> (fit: <score>%)
+  ID: <component_id>
+  Action: fetch source via 21st_magic_component_get and adapt to project DS
+  Confirm? Type "yes" to adopt or "no" to generate custom.
+  ```
+  Wait for response. "yes" → Step 2A-adopt. "no" → Step 2A-generate.
+- **fit < 80%**: proceed to Step 2A-generate.
+
+### Step 2A-adopt — Fetch and Adapt
+
+```
+21st_magic_component_get(component_id: <id>)
+```
+
+Adapt source to project DS (swap class names for Tailwind/Shadcn/Mantine equivalents).
+Build proposal for Step 3.
+
+### Step 2A-generate — Generate with Builder
+
+```
+21st_magic_component_builder(
+  description: <component_description>,
+  framework: "react",
+  style: <detected_ds>
+)
+```
+
+Inspect returned variations. Select the variant closest to project DS.
+Build proposal for Step 3.
+
+### Step 2B — 21st.dev: SVGL Brand Logo Lookup (optional)
+
+If component description includes brand name (GitHub, Vercel, Stripe, etc.):
+
+```
+svgl_get_brand_logo(brand_name: <brand>, format: "svg")
+```
+
+Add SVG to `.design/assets/<brand>-logo.svg`. Note in proposal.
+
+<!-- /impl: 21st -->
+
+---
+
+<!-- impl: magic-patterns -->
+## Magic Patterns Implementation
+
+### Step 2C — Magic Patterns: Generate
+
+Read STATE.md `<design_system>` block (written by design-context-builder Step 0C). Use as `design_system` param.
+
+```
+magic_patterns_generate(
+  description: <component_description>,
+  design_system: <detected_ds>,
+  quality_mode: "best"
+)
+```
+
+Response includes:
+- `code` — component source (React + DS class names)
+- `preview_url` — hosted preview of generated component
+- `component_id` — ID for annotate/regenerate roundtrip
+
+### Step 2C-annotate — Post DESIGN-DEBT Feedback (optional)
+
+If DESIGN-CONTEXT.md or DESIGN-DEBT.md has findings for this component type:
+
+```
+magic_patterns_annotate(
+  component_id: <component_id>,
+  feedback: "<finding text from DESIGN-DEBT>"
+)
+```
+
+Log: `✓ Feedback posted to Magic Patterns for <ComponentName>`
+
+### Step 2C-regenerate — Roundtrip (if user requests revision)
+
+After adoption, if user requests a revision:
+
+```
+magic_patterns_regenerate(
+  component_id: <component_id>,
+  updated_description: "<revised description>"
+)
+```
+
+Returns new `{ code, preview_url }`. Repeat Step 3–5 with new code.
+
+### Step 2C — Preview URL Routing
+
+After generating, write `preview_url` to STATE.md `<generator>` block (see Step 5).
+
+<!-- /impl: magic-patterns -->
+
+---
+
+## Step 3 — Build Proposal
+
+```
+Proposed component generation (1 operation):
+Component: <ComponentName>
+Output file: src/components/<ComponentName>.tsx
+Source: <21st.dev adopt|21st.dev generate|magic-patterns>
+DS target: <design_system>
+[Preview URL: <preview_url> (if magic-patterns)]
+[SVG assets: .design/assets/<brand>-logo.svg (if applicable)]
+```
+
+---
+
+## Step 4 — Confirm or Dry-Run
+
+If `--dry-run`: print `[dry-run] Proposal emitted. Pass without --dry-run to write files.` STOP.
+
+Print: `Write <ComponentName>.tsx to src/components/? Type "yes" to confirm.`
+
+Wait for response. Not "yes" → STOP with "Cancelled."
+
+---
+
+## Step 5 — Execute Write
+
+Write the component file to `src/components/<ComponentName>.tsx`.
+
+Update STATE.md `<generator>` block:
+```xml
+<generator>
+  component: <ComponentName>
+  source: <21st.dev adopt|21st.dev generate|magic-patterns>
+  component_id: <id_or_generated>
+  ds: <design_system>
+  preview_url: <preview_url_or_empty>
+  written: <ComponentName>.tsx
+  date: <today>
+</generator>
+```
+
+---
+
+## Step 6 — Summary
+
+```
+design-component-generator complete.
+Generator: <21st.dev|magic-patterns>
+Component: <ComponentName>
+Written: src/components/<ComponentName>.tsx
+DS: <design_system>
+[Preview: <preview_url>]
+```

package/agents/design-context-builder.md

@@ -92,9 +92,86 @@ Note: Decisions D-XX through D-YY pre-populated from Figma variables (source: fi
       These are starting points — the interview (Step 1+) may override or remove them.
 ```
 
-Proceed to Step 1 regardless of whether Step 0 ran or was skipped.
+Proceed to Step 0A regardless of whether Step 0 ran or was skipped.
 
-## Step 0B — Storybook Component Inventory
+## Step 0A — paper.design Canvas Read (optional)
+
+**Skip if `paper-design` is `not_configured` or `unavailable` in `.design/STATE.md` `<connections>`.** Proceed to Step 0B.
+
+### If `paper-design: available`
+
+ToolSearch first — paper.design tools may be in the deferred tool set:
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+```
+
+Then call:
+1. `mcp__paper-design__get_selection` → JSON of selected canvas elements (id, type, name, bounds)
+2. `mcp__paper-design__get_jsx` → React JSX string of selected component tree
+3. `mcp__paper-design__get_computed_styles` → computed CSS values for selection
+
+If any call errors: update STATE.md to `paper-design: unavailable`. Proceed to Step 0B.
+
+Add a `<canvas_sources>` block to DESIGN-CONTEXT.md:
+```xml
+<canvas_sources>
+  <canvas source="paper.design">
+    <!-- JSX component tree and computed styles extracted from canvas selection -->
+  </canvas>
+</canvas_sources>
+```
+
+Merge canvas-sourced values alongside Figma variables, Refero refs, and other sources. If a canvas value conflicts with a Figma variable, note both values and mark as "tentative — confirm with user."
+
+Proceed to Step 0B regardless of whether Step 0A ran or was skipped.
+
+## Step 0B — pencil.dev .pen File Discovery (optional)
+
+```bash
+PEN_FILES=$(find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null)
+```
+
+If PEN_FILES is empty: `pencil-dev: not_configured` in STATE.md. Skip.
+
+If PEN_FILES found:
+1. `pencil-dev: available` in STATE.md `<connections>`
+2. Read each `.pen` file. Extract component name, variant, design-tokens map.
+3. Add a `<pen_sources>` block to DESIGN-CONTEXT.md:
+```xml
+<pen_sources>
+  <pen file="Button.pen" component="Button" variant="primary">
+    <!-- design-tokens extracted from .pen frontmatter -->
+  </pen>
+</pen_sources>
+```
+4. Cross-reference .pen component names with grep-found component files. Flag components where `.pen` spec exists but no implementation found (DEBT: not-yet-built).
+
+Proceed to Step 0C regardless of whether Step 0B ran or was skipped.
+
+## Step 0C — Design System Detection (for component generators)
+
+Detect the project's active design system for use by `design-component-generator` (Magic Patterns, 21st.dev).
+
+Detection order:
+1. Check `gdd.config.json` (if present): read `designSystem` field → use directly if set.
+2. Scan `package.json` dependencies:
+   - `@shadcn/ui` or `shadcn` present → `"shadcn"`
+   - `@mantine/core` or `@mantine/hooks` present → `"mantine"`
+   - `@chakra-ui/react` present → `"chakra"`
+   - `tailwindcss` present → `"tailwind"`
+3. Default: `"tailwind"`
+
+Write result to STATE.md `<design_system>` block:
+```xml
+<design_system>tailwind</design_system>
+```
+
+Always runs — no skip condition. Takes < 1 second (file reads only).
+
+Proceed to Step 0D regardless of outcome.
+
+## Step 0D — Storybook Component Inventory
 
 **Skip this step if `storybook` is `not_configured` or `unavailable` in `.design/STATE.md` `<connections>`.** Proceed to Step 1 — grep-based inventory continues as before.
 
@@ -133,7 +210,7 @@ curl -sf http://localhost:6006/stories.json
 
 **If index.json fetch errors:** update STATE.md `storybook: unavailable`, fall back to grep-based inventory in Step 1. Continue without error.
 
-Proceed to Step 1 regardless of whether Step 0B ran or was skipped.
+Proceed to Step 1 regardless of whether Step 0D ran or was skipped.
 
 ## Step 1 — Auto-Detect Design System State
 

package/agents/design-paper-writer.md

@@ -0,0 +1,131 @@
+---
+name: design-paper-writer
+description: Writes design decisions back to the paper.design canvas — annotate, tokenize, and roundtrip modes. Proposal→confirm, dry-run, budget-aware (free tier: 100 calls/week). Follows the design-figma-writer pattern.
+tools: Read, Write, Bash, Grep, Glob
+color: green
+model: inherit
+default-tier: sonnet
+tier-rationale: "Writer proposes + executes canvas write-backs — Sonnet handles structured proposal synthesis well"
+size_budget: LARGE
+parallel-safe: never
+typical-duration-seconds: 90
+reads-only: false
+writes:
+  - "paper.design canvas (via mcp__paper-design__* tools) — annotations, style updates, text/HTML layers"
+---
+
+@reference/shared-preamble.md
+
+# design-paper-writer
+
+## Role
+
+You are design-paper-writer. You write design decisions from `.design/DESIGN-CONTEXT.md` back into the active paper.design canvas. You have three modes: `annotate`, `tokenize`, `roundtrip`. You always emit a proposal before executing writes. You never call paper.design write tools without user confirmation (unless `--dry-run` is requested). You track MCP call budget in STATE.md.
+
+---
+
+## Step 0 — MCP Probe
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+→ Empty    → Print: "paper.design MCP not available. Install with: claude mcp add paper-design --transport http https://mcp.paper.design/sse  Then restart the session." → STOP
+→ Non-empty → proceed to Step 1
+```
+
+---
+
+## Step 1 — Read State and Flags
+
+Read `.design/STATE.md` to confirm `paper-design: available`. If `not_configured` or `unavailable`, STOP with diagnostic.
+
+Parse flags:
+- `--dry-run` — emit proposal only, no writes
+- `mode` — one of `annotate | tokenize | roundtrip` (required)
+
+If mode absent:
+```
+design-paper-writer requires a mode.
+Available modes:
+  annotate   — add design decision comments to canvas nodes
+  tokenize   — sync CSS token values to paper.design node styles
+  roundtrip  — write implementation status back as text/HTML layers
+
+Usage: design-paper-writer <mode> [--dry-run]
+```
+STOP.
+
+---
+
+## Step 2 — Read Context and Build Proposal
+
+Read `.design/DESIGN-CONTEXT.md`. Build a numbered operation list per mode. Do NOT execute yet.
+
+**annotate mode** — extract confirmed D-XX decisions, map to canvas nodes:
+```
+Proposed annotations (N operations):
+1. Node "Button/Primary" → add_comment: "bg: brand-primary-500 per D-03"
+2. Node "Typography/H1" → add_comment: "font: Inter 32/40 per D-07"
+```
+
+**tokenize mode** — extract CSS literal values, map to paper.design style updates:
+```
+Proposed token bindings (N operations):
+1. Node "Button/Primary" fill → update_styles: { background: "var(--color-primary-500)" }
+2. Node "Card" padding → update_styles: { padding: "16px" }
+```
+
+**roundtrip mode** — write implementation status back as text/HTML:
+```
+Proposed write-backs (N operations):
+1. Node "Button" → set_text_content: "Status: built — verified 2026-04-19"
+2. Node "Modal" → set_text_content: "Status: pending — not yet implemented"
+```
+
+If DESIGN-CONTEXT.md has no applicable data: print "No operations to perform." STOP.
+
+---
+
+## Step 3 — Confirm or Dry-Run
+
+If `--dry-run`: print `[dry-run] Proposal emitted. N operations. Pass without --dry-run to apply.` STOP.
+
+Otherwise: print `Apply N operations to paper.design canvas? Type "yes" to confirm or "no" to cancel.`
+
+Wait for response. If not "yes": STOP with "Cancelled."
+
+---
+
+## Step 4 — Execute Writes
+
+For each operation, call the appropriate tool. Log each result.
+
+**annotate:**
+```javascript
+mcp__paper-design__add_comment({ node_id: "<id>", message: "<annotation>" })
+```
+
+**tokenize:**
+```javascript
+mcp__paper-design__update_styles({ node_id: "<id>", css_properties: { ... } })
+```
+
+**roundtrip:**
+```javascript
+mcp__paper-design__set_text_content({ node_id: "<id>", text: "<status text>" })
+// or for HTML write-back:
+mcp__paper-design__write_html({ node_id: "<id>", html: "<implementation snippet>" })
+```
+
+After EVERY call: increment `budget_used` in STATE.md `<connections>`. Warn if budget_used >= 90.
+
+---
+
+## Step 5 — Summary
+
+```
+design-paper-writer complete.
+Mode: <mode>
+Applied: N/M operations succeeded
+Budget used: N/100 (this session)
+Failed: <list failed operations or "none">
+```

package/agents/design-pencil-writer.md

@@ -0,0 +1,99 @@
+---
+name: design-pencil-writer
+description: Writes design decisions and implementation status back to .pen spec files (pencil.dev). Atomic git commits on every write. Two modes: annotate (DESIGN-DEBT findings as .pen comments) and roundtrip (update .pen spec from verified implementation).
+tools: Read, Write, Bash, Grep, Glob
+color: cyan
+model: inherit
+default-tier: sonnet
+tier-rationale: "File-based writer with git commits — Sonnet handles structured spec synthesis"
+size_budget: LARGE
+parallel-safe: never
+typical-duration-seconds: 60
+reads-only: false
+writes:
+  - "*.pen files — comments and design-token spec updates"
+---
+
+@reference/shared-preamble.md
+
+# design-pencil-writer
+
+## Role
+
+You are design-pencil-writer. You write design decisions and implementation status back into `.pen` spec files. Two modes: `annotate` and `roundtrip`. Every write is committed to git atomically. No write without a commit — this preserves the `.pen` file as a reliable version-controlled source of truth.
+
+---
+
+## Step 0 — Probe
+
+```bash
+PEN_FILES=$(find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null)
+```
+
+If empty: Print `pencil.dev: no .pen files found — STOP.` STOP.
+
+Read `.design/STATE.md` to confirm `pencil-dev: available`. If not, STOP with diagnostic.
+
+---
+
+## Step 1 — Read Flags
+
+Parse mode: `annotate | roundtrip` (required). If absent, list modes and STOP.
+
+`--dry-run` flag: emit proposal without writing or committing.
+
+---
+
+## Step 2 — Build Proposal
+
+**annotate mode** — read `.design/DESIGN-DEBT.md`, map findings to .pen components:
+```
+Proposed annotations (N operations):
+1. Button.pen → add comment: "DEBT: padding token mismatch — D-03 says 8px, impl uses 10px"
+2. Modal.pen → add comment: "DEBT: missing focus-trap per accessibility audit"
+```
+
+**roundtrip mode** — read `.design/DESIGN-VERIFICATION.md`, update .pen spec fields:
+```
+Proposed spec updates (N operations):
+1. Button.pen design-tokens.bg: "brand-primary-500" → confirmed built
+2. Modal.pen state: "default" → add state: "pending-build"
+```
+
+---
+
+## Step 3 — Confirm or Dry-Run
+
+If `--dry-run`: print proposal, `[dry-run] N operations. Pass without --dry-run to apply.` STOP.
+
+Print `Apply N operations to .pen files? Type "yes" to confirm.`
+
+Wait for response. If not "yes": STOP.
+
+---
+
+## Step 4 — Execute Writes (atomic)
+
+For EACH operation:
+
+1. Read the target `.pen` file.
+2. Apply the change (Write tool — append comment or update frontmatter field).
+3. Stage and commit atomically:
+   ```bash
+   git add "<path>.pen"
+   git commit -m "chore(pencil): write-back <component> [<mode>]"
+   ```
+4. Log: `✓ <component>.pen committed`
+
+If git commit fails: restore original file from git, log error, continue with remaining operations.
+
+---
+
+## Step 5 — Summary
+
+```
+design-pencil-writer complete.
+Mode: <mode>
+Applied: N/M operations (N committed, M failed)
+Failed: <list or "none">
+```

package/agents/design-research-synthesizer.md

@@ -52,7 +52,19 @@ Use Glob to confirm presence; skip absent files gracefully and mark section as `
 
    For each result (top 5 per query): record `{ query, pin_title, pin_url }`. Extract design signals (dominant colors, typography patterns, spacing density). Append to `<connection_sources>`: `source: pinterest (N pins from M queries)`.
 
-3. Produce `.design/DESIGN-CONTEXT.md` with the following sections, each wrapped in XML tags:
+3. **pencil.dev .pen files** (when `pencil-dev: available` in STATE.md):
+
+   Read `<pen_sources>` block from DESIGN-CONTEXT.md (written by design-context-builder Step 0B).
+
+   For each .pen component: merge declared design-tokens into the synthesis output:
+   - Token key/value pairs from `.pen` frontmatter → added to `<token_system>` section
+   - If a .pen token value differs from a grep-found implementation value → flag as `DIVERGE` in synthesis output
+
+   Add to `<connection_sources>` block: `source: pencil.dev (N components read from .pen files)`
+
+   Note in synthesis header: `pen-sources: N components read from .pen files` (or `pen-sources: 0 — pencil-dev not_configured` if skipped).
+
+4. Produce `.design/DESIGN-CONTEXT.md` with the following sections, each wrapped in XML tags:
    - `<token_system>` — from token-mapper
    - `<component_inventory>` — from component-taxonomy-mapper
    - `<visual_hierarchy>` — from visual-hierarchy-mapper
@@ -87,10 +99,29 @@ Read .design/STATE.md
 
 ### Parsing algorithm (handoff mode)
 
-1. **Read bundle path** from STATE.md `handoff_path` field (or resolve from `handoff_source` if `handoff_path` is missing).
+1. **Resolve the bundle** from STATE.md fields in priority order:
 
-2. **Parse HTML export** (primary):
-   - Read the HTML file with the Read tool
+   ```
+   handoff_url present   → fetch URL with WebFetch tool
+                           check Content-Type:
+                             text/html               → use response body as html_content (goto step 2)
+                             application/zip         → save to .design/handoff/bundle.zip, goto ZIP branch
+                             other                   → warn user, abort handoff mode
+   handoff_path present  → check extension:
+                             .html                   → read file, goto step 2
+                             .zip                    → goto ZIP branch
+                             .pdf                    → goto PDF branch
+                             .pptx / .pptx           → goto PPTX branch
+   neither present       → warn "no handoff_path or handoff_url in STATE.md", abort handoff mode
+   ```
+
+   **ZIP branch:** Extract `.design/handoff/bundle.zip` to `.design/handoff/extracted/`. Find primary HTML (`index.html`, `design.html`, or first `.html` at root). Find spec file (`readme.md`, `spec.md`, or first `.md` at root). Set html_content + spec_content. Delete `.design/handoff/extracted/` after parsing.
+
+   **PDF branch:** Extract all text content (Bash: `pdftotext <file> -` or python `pdfminer`). Set text_content. Skip to step 3b.
+
+   **PPTX branch:** Extract slide text (Bash: unzip `.pptx`, parse `ppt/slides/*.xml` for `<a:t>` text nodes). Set text_content. Skip to step 3b.
+
+2. **Parse HTML export** (primary — html_content available):
    - Extract all CSS custom properties from `<style>` blocks: grep for `--[a-z]+-[a-z-]+:\s*[^;]+`
    - Categorize by prefix:
      - `--color-*` → `[Color]` decisions
@@ -102,15 +133,23 @@ Read .design/STATE.md
    - Extract component names from `class="component-*"` or `data-component="*"` patterns → `[Component]` decisions
    - Detect layout patterns: `display: grid`, `display: flex` in component-level sections → `[Layout]` decisions
 
-3. **Parse spec markdown** (secondary, if present):
-   - Look for `.md` or `.json` files in the same directory as the HTML export
+3. **Parse spec text** (secondary):
+
+   3a. **Spec markdown / JSON** (if html_content path had a `.md` sibling, or ZIP contained spec):
    - Grep for `Decision:`, `Rationale:`, `Token:`, `Component:` prefixes
    - Treat found lines as pre-formed D-XX entries
 
+   3b. **PDF / PPTX text** (text_content only, no HTML):
+   - Grep text_content for same prefixes as 3a
+   - Also grep for hex colors (`#[0-9a-fA-F]{3,6}`), rem/px values (`[\d.]+rem|[\d]+px`), font names
+   - Tag ALL entries `(tentative — text-only, no CSS confirmation)`
+   - Note in STATE.md: `handoff_format: pdf` or `handoff_format: pptx` with caveat that token values need user confirmation
+
 4. **Translate to D-XX decisions**:
    - CSS custom property: `D-NN: [Category] Token name: value (source: claude-design-handoff) (tentative — confirm with user)`
    - Explicit spec markdown decision: `D-NN: [Category] decision text (source: claude-design-handoff) (locked — from handoff spec)`
    - Inferred component/layout: `D-NN: [Category] inferred text (source: claude-design-handoff) (tentative — inferred)`
+   - PDF/PPTX text value: `D-NN: [Category] extracted text (source: claude-design-pdf/pptx) (tentative — text-only, no CSS confirmation)`
 
 5. **Append to STATE.md `<decisions>` block** under `### Handoff-sourced decisions` subsection header.
 

package/agents/design-verifier.md

@@ -328,6 +328,57 @@ In DESIGN-VERIFICATION.md, add a `## Phase 4B — Screenshot Evidence` section l
 
 ---
 
+## Phase 4C — paper.design Canvas Screenshots (when paper-design: available)
+
+**Gate:** Skip this entire Phase 4C block if `paper-design` is `not_configured` or `unavailable` in STATE.md `<connections>`. Print: `paper.design canvas screenshots: skipped.`
+
+**Step 1 — ToolSearch first:**
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+```
+
+If empty: skip Phase 4C.
+
+**Step 2 — Per-component screenshot loop:**
+
+For each component flagged `? VISUAL` in Phase 2 or Phase 3:
+
+1. Look up the canvas node_id from DESIGN-CONTEXT.md `<canvas_sources>` block (written by design-context-builder Step 0A).
+2. If node_id found:
+   ```
+   mcp__paper-design__get_screenshot(node_id: "<id>")
+   ```
+   Save screenshot to `.design/screenshots/paper-<component>-<date>.png`.
+   Reference path in DESIGN-VERIFICATION.md `## Phase 4C` section.
+3. If node_id not found: note `paper-screenshot: node_id not found for <component>` — skip this component.
+
+**Note:** paper.design screenshots are canvas-element-scoped (individual components). Phase 4B Preview screenshots are route-scoped (full rendered pages). Both are complementary — run both when available.
+
+---
+
+### pencil.dev Spec-vs-Implementation Diff (optional)
+
+If `pencil-dev: available` in STATE.md `<connections>`:
+
+```bash
+PEN_FILES=$(find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null)
+```
+
+For each `.pen` file:
+1. Parse `design-tokens` from YAML frontmatter.
+2. For each declared token (e.g., `bg: brand-primary-500`):
+   - Grep implementation files for the component name to find corresponding CSS/token usage.
+   - Compare: declared value vs. found value.
+   - **MATCH** → token is correctly implemented.
+   - **DIVERGE** → flag: `PENCIL-DIVERGE: <component> <token-key>: spec=<declared> impl=<found>`
+   - **NOT FOUND** → flag: `PENCIL-MISSING: <component> <token-key> not found in implementation`
+3. Append results to DESIGN-VERIFICATION.md under `## pencil.dev Spec Compliance`.
+
+If no `.pen` files: skip silently. Print: `pencil.dev spec diff: no .pen files — skipped.`
+
+---
+
 ## Phase 5 — Gap Analysis
 
 Collect all failures from Phases 1–4: