@hegemonart/get-design-done 1.13.3 → 1.14.2

package/connections/21st-dev.md

@@ -0,0 +1,98 @@
+# 21st.dev Magic MCP — Connection Specification
+
+This file is the connection specification for the 21st.dev Magic MCP within the get-design-done pipeline. 21st.dev is a component-generator tool — it searches a marketplace of pre-built components and generates new ones via AI. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+- Node.js ≥ 18
+- A 21st.dev account and API key at [21st.dev](https://21st.dev)
+- `TWENTY_FIRST_API_KEY` environment variable set
+
+### Install command (Claude Code)
+
+```bash
+npx @21st-dev/magic@latest init
+```
+
+This sets up the local MCP server. Add to Claude Code settings:
+```json
+{
+  "mcpServers": {
+    "21st-magic": {
+      "command": "npx",
+      "args": ["@21st-dev/magic@latest"],
+      "env": { "TWENTY_FIRST_API_KEY": "${TWENTY_FIRST_API_KEY}" }
+    }
+  }
+}
+```
+
+### Verification
+
+```
+ToolSearch({ query: "mcp__21st", max_results: 5 })
+```
+
+Expect non-empty results including `21st_magic_component_builder` or `21st_magic_component_search`. If empty, re-run `npx @21st-dev/magic@latest init` and restart Claude Code session.
+
+---
+
+## Probe Pattern
+
+```
+ToolSearch({ query: "mcp__21st", max_results: 5 })
+→ Empty       → 21st-dev: not_configured (skip all 21st.dev steps)
+→ Non-empty   → 21st-dev: available
+```
+
+Write result to STATE.md `<connections>`: `21st-dev: <status>`
+
+Fallback: when `not_configured`, the explore stage skips the prior-art gate and proceeds with custom component generation.
+
+---
+
+## 21st.dev Magic MCP Tools
+
+| Tool | Stage | Purpose |
+|------|-------|---------|
+| `21st_magic_component_search` | explore | Semantic search of marketplace; returns top N matching components with fit scores |
+| `21st_magic_component_builder` | design | Generate component with multiple variations from a description |
+| `21st_magic_component_get` | design | Fetch full source code for a specific marketplace component |
+| `svgl_get_brand_logo` | explore + design | Fetch brand logo/icon SVG by brand name (SVGL integration) |
+
+---
+
+## Pipeline Integration
+
+| Stage | What 21st.dev provides |
+|-------|------------------------|
+| explore | **Prior-art gate**: `21st_magic_component_search` before any greenfield build; top-3 in `<prior-art>` block in DESIGN.md |
+| explore | **Brand assets**: `svgl_get_brand_logo` for logo/icon lookups by brand name |
+| design | `21st_magic_component_builder` for component scaffolding via `design-component-generator` agent |
+
+### Prior-Art Gate Logic
+
+Before building any custom component:
+1. `21st_magic_component_search(component_description, limit: 3)`
+2. Evaluate top result fit score (0–100):
+   - **≥ 80%**: surface as `<prior-art>` block in DESIGN.md; recommend adoption
+   - **< 80%**: note top candidate for reference; proceed with custom build
+3. Design-executor confirms adoption with user before calling `21st_magic_component_get`
+
+This is a **decision gate** — the agent surfaces candidates, the user/executor decides. No automatic code insertion.
+
+### SVGL Brand Logo Integration
+
+`svgl_get_brand_logo(brand_name, format: "svg")` returns SVG markup for major brands (GitHub, Vercel, Stripe, etc.). Wire into explore stage for brand asset lookups — eliminates manual SVG hunting.
+
+---
+
+## Fallback Behavior
+
+When `21st-dev: not_configured`:
+- Prior-art gate is skipped. Print: `21st.dev not configured — prior-art gate skipped.`
+- Custom component generation proceeds normally.
+- Brand logo lookups fall back to icon library references in `reference/iconography.md` (Phase 15).

package/connections/claude-design.md

@@ -6,20 +6,94 @@ This file is the connection specification for Claude Design (https://claude.ai/d
 
 ## What Is a Claude Design Handoff Bundle?
 
-Claude Design produces AI-generated designs that can be exported as **handoff bundles**. A bundle contains:
+Claude Design produces AI-generated designs that can be exported in several formats or sent directly to Claude Code via a hosted URL. The pipeline supports all of them.
 
-| Artifact | Format | Contains |
-|----------|--------|---------|
-| Standalone HTML export | `.html` | Rendered component tree, inline CSS (design tokens as CSS custom properties), component structure, color/spacing/typography values |
-| Design spec (optional) | `.md` or `.json` | Design decisions as structured text, token tables, component annotations |
-| Assets (optional) | `assets/` dir | Icons, images referenced by the HTML export |
+### Entry Points
 
-**Bundle entry point:** The primary parseable artifact is the HTML export. It contains inline `<style>` blocks with CSS custom properties (e.g., `--color-primary: #3B82F6`) and class-level token usage.
+| Source | How it arrives | handoff_source value |
+|--------|---------------|----------------------|
+| **"Send to local coding agent"** | Anthropic-hosted URL in the agent prompt | `claude-design-url` |
+| **"Download zip"** | `.zip` bundle dropped into project | `claude-design-zip` |
+| **"Save as standalone HTML"** | `.html` file dropped into project | `claude-design-html` |
+| **"Save as PDF"** | `.pdf` file (spec text extraction only) | `claude-design-pdf` |
+| **"Save as PPTX"** | `.pptx` file (spec text extraction only) | `claude-design-pptx` |
+| **Bundle directory** | Unzipped directory with HTML + spec + assets | `claude-design-bundle` |
 
-**Bundle discovery:** The pipeline looks for the bundle in:
-1. The path passed via `--from-handoff <path>` flag or `handoff <path>` sub-command
-2. The value of `handoff_source` in `.design/STATE.md` (if a prior session already set it)
-3. A `claude-design-handoff.html` file in the project root (convention — not required)
+### Bundle contents by format
+
+| Format | Primary artifact | Design tokens | Spec text | Images |
+|--------|-----------------|---------------|-----------|--------|
+| URL (hosted) | Fetched HTML | ✅ CSS custom props | ✅ if readme present | ✅ |
+| ZIP | Unzipped HTML | ✅ CSS custom props | ✅ `readme.md` inside | ✅ |
+| Standalone HTML | `.html` file | ✅ CSS custom props | ✅ if `.md` alongside | ✅ inline |
+| PDF | `.pdf` text | ❌ (no CSS) | ✅ extracted text | ❌ |
+| PPTX | `.pptx` slides | ❌ (no CSS) | ✅ slide text only | ❌ |
+
+**Bundle entry point:** The primary parseable artifact is always the HTML — it contains inline `<style>` blocks with CSS custom properties (e.g., `--color-primary: #3B82F6`) and class-level token usage. PDF and PPTX are text-extraction fallbacks when no HTML is available.
+
+**Bundle discovery:** The pipeline looks for the bundle in this priority order:
+1. A `https://api.anthropic.com/v1/design/h/` URL in the agent invocation arguments
+2. The path passed via `--from-handoff <path>` flag or `handoff <path>` sub-command
+3. The value of `handoff_source` in `.design/STATE.md` (if a prior session already set it)
+4. A `claude-design-handoff.{html,zip,pdf,pptx}` file in the project root (convention — not required)
+
+---
+
+## Format-Specific Ingestion
+
+### URL format — `https://api.anthropic.com/v1/design/h/<hash>`
+
+This is the native entry point when the user clicks **"Send to local coding agent"** in Claude Design. The agent prompt arrives as:
+
+```
+Fetch this design file, read its readme, and implement the relevant aspects of the design. https://api.anthropic.com/v1/design/h/<hash>
+Implement: <user description>
+```
+
+**Detection:** grep the raw arguments/prompt for the pattern `https://api\.anthropic\.com/v1/design/h/[A-Za-z0-9_-]+`.
+
+**Fetch sequence:**
+1. `WebFetch` the URL — the response is either an HTML bundle or a redirect to a ZIP download
+2. If `Content-Type: text/html` → treat as standalone HTML, parse normally
+3. If `Content-Type: application/zip` or redirect to `.zip` → download to `.design/handoff/claude-design-handoff.zip`, then follow ZIP ingestion below
+4. Check the response for an embedded `readme.md` link (often served alongside) — fetch it separately if present
+5. Set `handoff_source: claude-design-url` and `handoff_url: <url>` in STATE.md
+
+**Implement description:** The text after `Implement:` in the agent prompt is the user's implementation scope — capture it as a project note, not a D-XX decision.
+
+### ZIP format
+
+**Detection:** input path ends in `.zip` OR fetched from URL as zip.
+
+**Ingestion sequence:**
+1. Extract to `.design/handoff/` (temp directory, not committed)
+2. Find the primary HTML: `index.html`, `design.html`, or any `.html` at root
+3. Find spec: `readme.md`, `spec.md`, `design.md`, or any `.md` at root
+4. Parse HTML + spec using the standard field catalogue below
+5. Clean up `.design/handoff/` after parsing (keep only extracted decisions in STATE.md)
+
+### PDF format
+
+**Detection:** input path ends in `.pdf`.
+
+**Ingestion:** PDF yields no CSS custom properties — token extraction is not possible. Instead:
+1. Extract all text content (pdftotext or equivalent)
+2. Grep for `Decision:`, `Rationale:`, `Token:`, `Color:`, `Typography:`, `Spacing:` prefixes
+3. Treat matched lines as spec text → translate to D-XX entries tagged `(source: claude-design-pdf)` + `(tentative — text-only, no CSS confirmation)`
+4. Note in STATE.md: `handoff_format: pdf` + caveat that token values were extracted from text, not CSS
+
+**Limitation:** PDF handoffs cannot produce `(locked)` token decisions — all are `(tentative)`. Surface this explicitly to the user in the discussant step.
+
+### PPTX format
+
+**Detection:** input path ends in `.pptx`.
+
+**Ingestion:** Same as PDF — text extraction only, no CSS tokens.
+1. Extract slide text (python-pptx or unzip `.pptx` and parse `ppt/slides/*.xml`)
+2. Same grep patterns as PDF
+3. Tag all entries `(source: claude-design-pptx)` + `(tentative — text-only)`
+
+**Limitation:** Same as PDF — all decisions are tentative. PPTX format is the weakest source; prefer HTML or ZIP if available.
 
 ---
 
@@ -114,13 +188,15 @@ Claude Design is not an MCP server — it has no tools to probe via ToolSearch.
 
 ```
 At scan stage entry:
-  1. Check STATE.md <position> for handoff_source field
+  1. Check invocation arguments/prompt for https://api.anthropic.com/v1/design/h/ URL
   2. Check $ARGUMENTS for --from-handoff <path> flag
-  3. Check project root for claude-design-handoff.html
+  3. Check STATE.md <position> for handoff_source / handoff_url / handoff_path field
+  4. Check project root for claude-design-handoff.{html,zip,pdf,pptx}
 
-  → Bundle path found AND file exists           → claude_design: available
-  → Bundle path provided but file missing/bad   → claude_design: unavailable
-  → No bundle path, no file                      → claude_design: not_configured
+  → URL detected (step 1)                        → claude_design: available (fetch at ingest time)
+  → File path found AND file exists              → claude_design: available
+  → Path/URL provided but unreachable/bad        → claude_design: unavailable
+  → None of the above                            → claude_design: not_configured
 ```
 
 Write result to STATE.md `<connections>` at scan entry.
@@ -168,17 +244,25 @@ skipped_stages: scan, discover, plan
 
 **`handoff_source` values:**
 
-| Value | Meaning |
-|-------|---------|
-| `claude-design-html` | Bundle is a standalone HTML export from Claude Design |
-| `claude-design-bundle` | Bundle is a directory with HTML + spec markdown + assets |
-| `manual` | User manually initialized STATE.md with design decisions (no bundle file) |
+| Value | Meaning | Token quality |
+|-------|---------|---------------|
+| `claude-design-url` | Fetched from Anthropic-hosted URL (Send to local coding agent) | High — HTML |
+| `claude-design-zip` | ZIP bundle dropped into project | High — HTML inside |
+| `claude-design-html` | Standalone HTML export | High — CSS custom props |
+| `claude-design-bundle` | Directory with HTML + spec markdown + assets | High — CSS custom props |
+| `claude-design-pdf` | PDF export (text extraction only) | Low — text only, all tentative |
+| `claude-design-pptx` | PPTX export (text extraction only) | Low — text only, all tentative |
+| `manual` | User manually initialized STATE.md with design decisions (no bundle file) | N/A |
 
 ---
 
 ## Caveats and Pitfalls
 
-1. **Handoff bundle format is undocumented by Anthropic.** The Claude Design handoff bundle format is inferred from the product announcement and common HTML export patterns. The pipeline uses defensive parsing: grep for CSS custom properties in `<style>` tags, extract component class names from `class="component-*"` patterns, and fall back to the spec markdown/JSON if CSS parsing yields no results. If the format changes in a future Claude Design release, update this spec and the synthesizer's parsing patterns.
+1. **Handoff bundle format is undocumented by Anthropic.** The Claude Design handoff bundle format is inferred from the product UI and common HTML export patterns. The pipeline uses defensive parsing: grep for CSS custom properties in `<style>` tags, extract component class names from `class="component-*"` patterns, and fall back to the spec markdown/JSON if CSS parsing yields no results. If the format changes in a future Claude Design release, update this spec and the synthesizer's parsing patterns. The URL endpoint (`/v1/design/h/<hash>`) may return different content types — always check `Content-Type` before deciding whether to parse as HTML or unzip.
+
+6. **PDF and PPTX handoffs produce only tentative decisions.** These formats contain no CSS — all token values must be inferred from prose. Never promote PDF/PPTX-sourced decisions to `(locked)` without explicit user confirmation. If the user provides both a PDF and an HTML export, always prefer the HTML.
+
+7. **ZIP extraction is ephemeral.** Extracted ZIP contents go to `.design/handoff/` and are deleted after parsing. Only the extracted D-XX decisions are persisted to STATE.md. Never commit the raw extracted files.
 
 2. **`(tentative)` decisions MUST be confirmed by the user.** The discussant `--from-handoff` mode surfaces all tentative decisions for confirmation before proceeding to verify. Do NOT skip this step — implementing against unconfirmed inferred values is the primary failure mode of handoff-sourced workflows.
 

package/connections/connections.md

@@ -16,6 +16,10 @@ This directory contains connection specifications for external tools and MCPs th
 | Graphify | Active | [`connections/graphify.md`](connections/graphify.md) | CLI: `graphify`; `gsd-tools graphify *` |
 | Pinterest | Active | [`connections/pinterest.md`](connections/pinterest.md) | `mcp__mcp-pinterest__*` tools (ToolSearch-only probe; headless scraping, no API key) |
 | Claude Design | Active | [`connections/claude-design.md`](connections/claude-design.md) | No MCP — bundle file probe; enables `/gdd:handoff` pipeline + bidirectional write-back via figma-writer |
+| paper.design | Active | [`connections/paper-design.md`](connections/paper-design.md) | Uses `mcp__paper-design__*` tools; free tier: 100 calls/week |
+| pencil.dev | Active | [`connections/pencil-dev.md`](connections/pencil-dev.md) | File-based; `.pen` YAML specs; git-tracked; no MCP |
+| 21st.dev Magic MCP | Active | [`connections/21st-dev.md`](connections/21st-dev.md) | Uses `mcp__21st*` tools; `TWENTY_FIRST_API_KEY` required |
+| Magic Patterns | Active | [`connections/magic-patterns.md`](connections/magic-patterns.md) | Claude connector (`mcp__magic_patterns*`) + API key fallback |
 
 ---
 
@@ -23,16 +27,20 @@ This directory contains connection specifications for external tools and MCPs th
 
 Each cell describes what the connection contributes at that pipeline stage, or `—` if it is not used.
 
-| Connection | scan | discover | plan | design | verify |
-|-----------|------|----------|------|--------|--------|
-| Figma | token augmentation via `get_variable_defs` (CONN-03) | decisions pre-populate via `get_variable_defs` (CONN-04) | — | write tokens/annotations/Code Connect via `use_figma` (FWR-01..04) | — |
-| Refero | — | reference search via `mcp__refero__search`; fallback → awesome-design-md (CONN-05) | — | — | — |
-| Preview | — | — | — | — | screenshots for `? VISUAL` checks (VIS-02) |
-| Storybook | — | component inventory (STB-01) | change-risk via story count (STB-02) | `.stories.tsx` stub (STB-03) | a11y per story (STB-02) |
-| Chromatic | — | — | change-risk scoping (CHR-02) | — | visual delta narration (CHR-01) |
-| Graphify | — | — | dependency scoping (GRF-03) | — | orphan detection (GRF-04) |
-| Pinterest | probe only | visual reference search via `pinterest_search`; fallback → Refero → awesome-design-md | — | — | — |
-| Claude Design | bundle probe → `claude_design: available` | synthesizer handoff mode — parses bundle → D-XX decisions; discussant `--from-handoff` confirms | — (skipped in handoff) | — (skipped in handoff) | Handoff Faithfulness section; bidirectional write-back via figma-writer `implementation-status` mode |
+| Connection | scan | discover | plan | design | verify | canvas | generator |
+|-----------|------|----------|------|--------|--------|--------|-----------|
+| Figma | token augmentation via `get_variable_defs` (CONN-03) | decisions pre-populate via `get_variable_defs` (CONN-04) | — | write tokens/annotations/Code Connect via `use_figma` (FWR-01..04) | — | — | — |
+| Refero | — | reference search via `mcp__refero__search`; fallback → awesome-design-md (CONN-05) | — | — | — | — | — |
+| Preview | — | — | — | — | screenshots for `? VISUAL` checks (VIS-02) | — | — |
+| Storybook | — | component inventory (STB-01) | change-risk via story count (STB-02) | `.stories.tsx` stub (STB-03) | a11y per story (STB-02) | — | — |
+| Chromatic | — | — | change-risk scoping (CHR-02) | — | visual delta narration (CHR-01) | — | — |
+| Graphify | — | — | dependency scoping (GRF-03) | — | orphan detection (GRF-04) | — | — |
+| Pinterest | probe only | visual reference search via `pinterest_search`; fallback → Refero → awesome-design-md | — | — | — | — | — |
+| Claude Design | bundle probe → `claude_design: available` | synthesizer handoff mode — parses bundle → D-XX decisions; discussant `--from-handoff` confirms | — (skipped in handoff) | — (skipped in handoff) | Handoff Faithfulness section; bidirectional write-back via figma-writer `implementation-status` mode | — | — |
+| paper.design | — | canvas read: `get_selection`, `get_jsx`, `get_computed_styles` | — | paper-writer: annotate/tokenize/roundtrip | `get_screenshot` for `? VISUAL` | ✓ | — |
+| pencil.dev | `.pen` discovery | `.pen` as canonical design source | — | pencil-writer: annotate/roundtrip | spec-vs-impl diff | ✓ | — |
+| 21st.dev | — | prior-art gate: marketplace search before greenfield build | — | component-generator (21st impl) | — | — | ✓ |
+| Magic Patterns | — | — | — | component-generator (magic-patterns impl) | preview_url → `? VISUAL` check | — | ✓ |
 
 **Column definitions:**
 
@@ -41,6 +49,8 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 - **plan** — what the connection contributes to planning artifacts
 - **design** — what the connection provides during design execution
 - **verify** — what the connection checks or surfaces during verification
+- **canvas** — whether the connection provides bidirectional canvas read+write (see `reference/ai-native-tool-interface.md`)
+- **generator** — whether the connection provides AI component generation (see `reference/ai-native-tool-interface.md`)
 
 ---
 
@@ -202,4 +212,24 @@ To add a new connection to the pipeline:
 
 - `connections/` is infrastructure scaffolding introduced in Phase 1. Stage integration (wiring detection and graceful degradation into each stage) is Phase 2 work.
 - Phase 8 added five new active connections. Linear and GitHub remain planned for a future phase.
-- The capability matrix columns map to the five pipeline stages: `scan | discover | plan | design | verify`.
+- Phase 14 added four AI-native design tool connections (paper.design, pencil.dev, 21st.dev, Magic Patterns) and the canvas/generator capability columns.
+- The capability matrix columns map to the five pipeline stages: `scan | discover | plan | design | verify`, plus `canvas` and `generator` sub-categories.
+
+---
+
+## Future AI-Native Tools (Backlog)
+
+Candidate tools to integrate using the contract in `reference/ai-native-tool-interface.md`.
+
+| Tool | Sub-category | Priority |
+|------|-------------|----------|
+| Subframe | canvas | high |
+| v0.dev | generator | high |
+| Galileo AI | generator | medium |
+| Builder.io Visual Copilot | canvas + generator | medium |
+| Locofy | generator | low |
+| Anima | canvas | low |
+| Plasmic | generator | medium |
+| TeleportHQ | generator | low |
+
+To add any of these: follow the steps in `reference/ai-native-tool-interface.md §Extending with Future Tools`.

package/connections/magic-patterns.md

@@ -0,0 +1,105 @@
+# Magic Patterns — Connection Specification
+
+This file is the connection specification for Magic Patterns within the get-design-done pipeline. Magic Patterns is a component-generator tool — it generates DS-aware UI components from natural-language descriptions. It integrates via the Magic Patterns Claude connector (no manual setup when enabled) or via a direct API key. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+
+**Path A — Claude connector (preferred):**
+- Magic Patterns Claude connector enabled in your Claude environment
+- No additional setup required
+
+**Path B — API key fallback:**
+- A Magic Patterns account and API key at [magicpatterns.com](https://magicpatterns.com)
+- `MAGIC_PATTERNS_API_KEY` environment variable set
+- MCP server install:
+  ```bash
+  claude mcp add magic-patterns --transport http https://mcp.magicpatterns.com/sse \
+    -e MAGIC_PATTERNS_API_KEY=$MAGIC_PATTERNS_API_KEY
+  ```
+
+### Verification
+
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+```
+
+Non-empty results including `magic_patterns_generate` → Claude connector available (Path A).
+Empty → install Path B and restart Claude Code session.
+
+---
+
+## Probe Pattern
+
+Magic Patterns uses a two-path probe. Check Claude connector first; fall back to API key path.
+
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+→ Non-empty  → magic-patterns: available (Claude connector)
+→ Empty      → check MAGIC_PATTERNS_API_KEY env var
+               set → magic-patterns: available (API key path)
+               unset → magic-patterns: not_configured
+```
+
+Write result to STATE.md `<connections>`: `magic-patterns: <status>`
+
+Fallback: when `not_configured`, the design stage skips Magic Patterns and falls back to 21st.dev (if available) or manual component build.
+
+---
+
+## Magic Patterns Tools
+
+| Tool | Stage | Purpose |
+|------|-------|---------|
+| `magic_patterns_generate` | design | Generate component from description; returns `{ code, preview_url, component_id }` |
+| `magic_patterns_annotate` | design | Post DESIGN-DEBT findings back to a component by ID |
+| `magic_patterns_regenerate` | design | Roundtrip: regenerate with updated description |
+
+### `magic_patterns_generate` parameters
+
+| Parameter | Values | Notes |
+|-----------|--------|-------|
+| `description` | string | Natural-language component spec |
+| `design_system` | `"shadcn" \| "tailwind" \| "mantine" \| "chakra"` | Auto-detected from project in explore stage |
+| `quality_mode` | `"fast" \| "best"` | `fast` for explore iterations; `best` for final design stage output |
+
+---
+
+## Pipeline Integration
+
+| Stage | What Magic Patterns provides |
+|-------|------------------------------|
+| explore | DS detection → STATE.md `<design_system>` block for generator targeting |
+| design | `magic_patterns_generate(description, design_system, quality_mode: "best")` → component source + `preview_url` |
+| verify | `preview_url` from generate response → feeds Phase 8 Preview `? VISUAL` check |
+| design | `magic_patterns_annotate(component_id, feedback)` → roundtrip mode; post DESIGN-DEBT notes back |
+
+### Design-System Auto-Detection
+
+Before invoking `magic_patterns_generate`, the explore stage detects the project's active design system (see `agents/design-context-builder.md` Step 0C):
+
+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.
+
+### Preview Integration
+
+`magic_patterns_generate` returns `preview_url`. The design-component-generator agent writes this URL to STATE.md `<generator>` block. The verify stage's `? VISUAL` check reads `preview_url` from STATE.md and opens it in Phase 8 Preview for visual comparison.
+
+---
+
+## Fallback Behavior
+
+When `magic-patterns: not_configured`:
+- Print: `Magic Patterns not configured — component generator skipped.`
+- Falls back to 21st.dev if `21st-dev: available`.
+- If both not configured, design stage proceeds with manual component build.

package/connections/paper-design.md

@@ -0,0 +1,137 @@
+# paper.design MCP — Connection Specification
+
+This file is the connection specification for paper.design within the get-design-done pipeline. paper.design is a canvas tool — it treats the design canvas as both source AND destination, enabling a full canvas→code→verify→canvas round-trip. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+- A paper.design account
+- paper.design MCP server registered in your Claude Code session
+
+### Install command (Claude Code)
+
+```bash
+claude mcp add paper-design --transport http https://mcp.paper.design/sse
+```
+
+After running this command, restart the Claude Code session.
+
+### Verification
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+```
+
+Expect non-empty results including `mcp__paper-design__get_selection` or similar. If empty, re-run the install command above and restart the Claude Code session.
+
+### Budget
+
+paper.design **free tier**: 100 MCP calls/week. Pro tier: 1M calls/week. The pipeline tracks `budget_used` in STATE.md `<connections>` and warns at 90 calls.
+
+---
+
+## Probe Pattern
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+→ Empty       → paper-design: not_configured (skip all paper.design steps)
+→ Non-empty   → proceed to live call
+
+call mcp__paper-design__get_selection
+→ Success     → paper-design: available
+→ Error       → paper-design: unavailable
+```
+
+Write result to STATE.md `<connections>`: `paper-design: <status>`
+
+Also write initial budget state:
+```xml
+<connections>
+paper-design: available | budget_used: 0 | budget_limit: 100
+</connections>
+```
+
+---
+
+## paper.design MCP Tools
+
+| Tool | Stage | Purpose |
+|------|-------|---------|
+| `mcp__paper-design__get_selection` | explore | JSON of selected canvas elements (id, type, name, bounds) |
+| `mcp__paper-design__get_jsx` | explore | React JSX string of selected component tree |
+| `mcp__paper-design__get_computed_styles` | explore | CSS computed styles for current selection |
+| `mcp__paper-design__get_screenshot` | verify | Base64 PNG screenshot of selected canvas element |
+| `mcp__paper-design__add_comment` | design | Add annotation comment to a canvas node |
+| `mcp__paper-design__update_styles` | design | Update CSS properties of a canvas node |
+| `mcp__paper-design__set_text_content` | design | Write text content to a canvas text layer |
+| `mcp__paper-design__write_html` | design | Write HTML snippet to a canvas layer |
+
+---
+
+## Pipeline Integration
+
+| Stage | What paper.design provides |
+|-------|---------------------------|
+| explore | Canvas read: `get_selection` (node list), `get_jsx` (React component tree), `get_computed_styles` (CSS values) → merged into DESIGN-CONTEXT.md |
+| design | `design-paper-writer` agent: annotate / tokenize / roundtrip modes via write tools |
+| verify | `get_screenshot` for components flagged `? VISUAL` — element-scoped (complements route-scoped Preview screenshots) |
+
+### Canvas Read (Explore Stage)
+
+The explore stage context-builder reads the paper.design canvas via:
+
+1. `mcp__paper-design__get_selection` — get selected element IDs and names
+2. `mcp__paper-design__get_jsx` — get full React component tree of selection
+3. `mcp__paper-design__get_computed_styles` — get computed CSS values
+
+Results are merged into DESIGN-CONTEXT.md as a `<canvas_sources>` block alongside Figma variables, Refero refs, and other sources.
+
+### Write-Back (Design Stage)
+
+The `design-paper-writer` agent handles write-back in three modes:
+- **annotate** — add design-decision comments to canvas nodes (`add_comment`)
+- **tokenize** — sync CSS token values to paper.design node styles (`update_styles`)
+- **roundtrip** — write implementation status back as text/HTML layers (`set_text_content`, `write_html`)
+
+All writes require user confirmation via proposal→confirm flow. See `agents/design-paper-writer.md`.
+
+### Screenshot Verification (Verify Stage)
+
+`mcp__paper-design__get_screenshot(node_id)` captures a PNG of a specific canvas element.
+
+- Canvas-element-scoped (NOT route-scoped like Phase 8 Preview)
+- Both are complementary: paper.design → canvas component view; Preview → rendered browser route
+- Screenshots saved to `.design/screenshots/paper-<component>-<date>.png`
+
+---
+
+## Budget Tracking
+
+After every write tool call, increment `budget_used` in STATE.md:
+
+```xml
+<connections>
+paper-design: available | budget_used: 12 | budget_limit: 100
+</connections>
+```
+
+Warn when `budget_used >= 90`: `Warning: paper.design budget at 90/100 calls this week.`
+
+Read tools (`get_selection`, `get_jsx`, `get_computed_styles`, `get_screenshot`) also consume budget — track them as well.
+
+---
+
+## Fallback Behavior
+
+When `paper-design: not_configured`:
+- Skip all paper.design steps. Print: `paper.design not configured — canvas integration skipped.`
+- Explore stage proceeds with code-only context (grep + Figma + Storybook if available).
+- Verify stage uses Preview screenshots only (no canvas-element screenshots).
+- Design stage does not offer paper-writer.
+
+When `paper-design: unavailable`:
+- Update STATE.md to `paper-design: unavailable`.
+- Print: `paper.design unavailable — check MCP connection and try again.`
+- Degrade as above.

package/connections/pencil-dev.md

@@ -0,0 +1,88 @@
+# pencil.dev — Connection Specification
+
+This file is the connection specification for pencil.dev within the get-design-done pipeline. pencil.dev uses git-tracked `.pen` files as its source of truth — no MCP server is required. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+- pencil.dev VS Code or Cursor extension installed from the marketplace
+- One or more `.pen` files in the project (typically at project root or in `src/`)
+
+### Verification
+
+Run in the project directory:
+```bash
+find . -name "*.pen" -not -path "*/node_modules/*" | head -5
+```
+One or more results = pencil.dev is in use.
+
+No MCP server install needed — the pipeline reads and writes `.pen` files directly via standard file tools.
+
+---
+
+## Probe Pattern
+
+pencil.dev does not use MCP tools. Probe is file-based.
+
+```bash
+PEN_FILES=$(find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null)
+if [ -n "$PEN_FILES" ]; then
+  echo "pencil-dev: available"
+else
+  echo "pencil-dev: not_configured"
+fi
+```
+
+Write result to STATE.md `<connections>`: `pencil-dev: available` or `pencil-dev: not_configured`.
+
+---
+
+## .pen File Format
+
+`.pen` files are YAML-front-matter component specs:
+
+```yaml
+---
+component: Button
+variant: primary
+state: default
+design-tokens:
+  bg: brand-primary-500
+  text: white
+  radius: 6px
+  padding: "8px 16px"
+---
+
+Notes: Primary CTA button. Use for the main action in any modal or form.
+```
+
+- `component` — component name (must match the implementation filename)
+- `variant` — variant label (matches Storybook story name where applicable)
+- `state` — `default | hover | focus | disabled | error`
+- `design-tokens` — key/value map of token names to values (CSS variables or literal values)
+- Body prose — optional implementation notes
+
+`.pen` files are **git-tracked source of truth**. Commits to `.pen` files must be atomic — spec and implementation changes committed together when possible.
+
+---
+
+## Pipeline Integration
+
+| Stage | What pencil.dev provides |
+|-------|--------------------------|
+| explore | `.pen` file discovery; synthesizer merges `.pen` declarations with code grep results |
+| verify | Spec-vs-implementation diff: `.pen` declared token values vs. actual token values in code |
+| design | `design-pencil-writer` agent: annotate + roundtrip modes; atomic git commits on `.pen` writes |
+
+**Architectural advantage:** Both the design spec (`.pen` file) and implementation (source code) are version-controlled. Pre-merge diff verification is uniquely strong compared to tools where the design lives outside git.
+
+---
+
+## Fallback Behavior
+
+When `pencil-dev: not_configured`:
+- All pencil.dev steps are skipped silently.
+- A one-line diagnostic is printed: `pencil.dev not configured — no .pen files found.`
+- Pipeline continues normally.