Pds

Getting Started

When this skill is invoked via /pds, begin with:

1. Parse the user's input — extract domain, brand name, color preferences, font preferences from their message after /pds
2. Greet and confirm — show what was understood and what will be built:

Pencil Design System Generator

Domain: [extracted domain]
Brand:  [extracted name or "unnamed"]
Colors: [extracted preferences or "will research"]
Fonts:  [extracted preferences or "will research"]

I'll build this step by step:
 1. Research    -> design brief
 2. Tokens      -> ~89 themed variables (light + dark)
 3. Foundations  -> visual documentation
 4. Components  -> ~25 reusable parts
 5. Patterns    -> 4 composition showcases

Each step pauses for your review. Type:
  c  to continue
  r  to redo (tell me what to change)
  s  to skip ahead to final verification

Want screens too? Tell me now or add them later.

Starting with domain research...

3. Proceed to Phase 1 immediately — the first review pause comes after the design brief is ready.

Input

The user provides a business domain (e.g., "bakery", "fitness app", "SaaS dashboard"). Optional extras: brand name, color preferences, font preferences, specific screens wanted, light/dark theme preference, reference image. If the user gives only a domain, infer everything else from research.

If the user specifies colors or fonts: Use their values as the primary/accent/background tokens in Phase 3 and derive the remaining palette around them (secondary, muted, foregrounds). Research still runs to fill in gaps, but user preferences take priority over both research and fallback tables.

If the user provides a reference image (placed on the canvas, pasted in chat, or as a URL): This is the highest-priority design input. In Phase 1, run the 7-pass structured extraction to derive:

• Colors — dominant color, accent colors, background color, text color (report as hex values)
• Typography style — serif/sans-serif, weight, spacing (match to closest Google Fonts)
• Tone — minimal, bold, playful, corporate, organic, etc.
• Layout density — spacious vs compact, card-heavy vs list-heavy
• Visual patterns — rounded corners vs sharp, shadow depth, border usage

Use these extracted values as the foundation for all tokens. Research supplements the image analysis but does NOT override it — the reference image is the primary source of truth for the design direction.

Canvas Organization

The canvas is laid out left-to-right in three core sections (always created), plus an optional screens section:

[Foundations 1440×fit] → 100px gap → [Components 1440×fit] → 100px gap → [Patterns 1440×fit] → (optional) [Screens →]

• Foundations — Visual documentation: color palette swatches, typography specimens, spacing scale, elevation examples, border radius showcase.
• Components — All ~25 reusable components, organized under category sub-frames (Buttons, Inputs, Typography, Badges, Alerts, Cards, Navigation, Tables, etc.).
• Patterns — Composition showcases: form pattern, data display pattern, navigation pattern, card layout pattern. Each uses component refs to demonstrate real usage.
• Screens (only if user requests) — 3–5 domain-relevant screens placed to the right of Patterns.

No components live at the document root except these section frames and the optional navigation index.

Workflow

Execute these phases in order. Each phase builds on the previous. Never skip mandatory phases. Reference files in references/ contain detailed specs — load them as each phase begins.

⛔ Review gates are placed after major phases. At each gate you MUST stop, show results, and wait for user input before continuing. The user controls the pace — they type c to continue, r to redo, or s to skip ahead.

Phase 1 — Research the Domain

If collectui-mcp is available: Use it for visual research before web search.

1. Call collectui_search({ query: "[domain]", limit: 8 }) — e.g., "coffee shop", "dashboard", "e-commerce"
2. Analyze the returned design screenshots — extract dominant colors (hex), typography patterns, layout styles, corner radii, shadow depth
3. Use these as strong design signals alongside web research

If a reference image exists: Check if the user placed an image on the canvas or provided one in chat.

• If on canvas: call get_screenshot on the image node to analyze it
• If pasted in chat or provided as a URL: analyze the image directly

Run a 7-pass structured extraction to map visual properties to specific tokens:

If no reference image exists: Skip this extraction and rely on CollectUI visual research + web search + fallback tables. The remaining phases work identically — the image extraction is an enhancement that provides higher-fidelity starting values, not a requirement.

Use extracted values as the PRIMARY design direction — research supplements, not overrides

Web research (always runs): Use WebSearch to study the domain's design conventions. Identify five pillars: color palette, typography, imagery themes, screen inventory, and UI density/tone. Document findings as a design brief.

Typography is research-driven, not table-driven. Run specific font research queries (e.g., "bakery website fonts 2026", "best Google Fonts for bakery") and validate against 3–5 real websites in the domain. The font pairing table in domain-research-guide.md is a fallback — always prefer research-validated choices. See references/domain-research-guide.md.

Priority order for design decisions: Reference image > Collect UI visual research > User preferences > Web research > Fallback tables.

⛔ REVIEW — Design Brief

Present the research findings as a design brief:

Design Brief — [Domain]

Colors:
  Primary:    [hex] ([description])
  Secondary:  [hex] ([description])
  Accent:     [hex] ([description])
  Background: [hex] ([description])

Typography:
  Heading:    [font name]
  Body:       [font name]
  Mono:       [font name]
  Weights:    [list observed: regular, semibold, bold, etc.]
  Tracking:   [tight headings / normal body / wide caps]

Shape & Depth:
  Radius:     [sharp / subtle / medium / rounded / pill]
  Shadows:    [none / subtle / moderate / prominent]
  Borders:    [hairline / default / thick]

Layout:
  Density:    [spacious / moderate / compact]
  Icon style: [outline / solid, thin / regular]

Tone:       [2-3 adjectives]
Source:     [reference image / CollectUI / web research]
Based on:   [list 2-3 reference sites or image description]

[c] Continue to token creation [r] Redo — tell me what to change (e.g., "use teal instead of brown") [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 2 — Initialize the Pencil Document

Step 1 — CHECK for an existing document FIRST: Call get_editor_state({ include_schema: true }). Read the response carefully. Look at the filePath field.

⛔ STOP AND DECIDE — do NOT skip this check:

• If filePath contains a .pen file (e.g., design.pen, project.pen, anything ending in .pen): USE THAT FILE. Do NOT call open_document at all. The document is already open. Save the filePath for all subsequent calls.
• ONLY if filePath is empty/null/undefined (meaning NO .pen file is open): Create a named file: open_document("./[domain]-design-system.pen"). Always prefix with ./.

NEVER call open_document("new"). This creates a generic pencil-new.pen that ignores the existing file. NEVER call open_document if a .pen file is already open. This creates a SECOND document.

Step 2 — Call get_guidelines({ topic: "design-system" }). Step 3 — Call get_style_guide_tags() then get_style_guide({ tags: [...] }) with 5–10 domain-matching tags. Step 4 — Call get_variables({ filePath }) to check for existing tokens.

Merge the style guide with Phase 1 research to form the final design direction.

Phase 3 — Create Design Tokens

Call set_variables to create the full token system (~89 tokens). Every color, font, radius, spacing, shadow, font size, line height, font weight, letter spacing, sizing, opacity, and border width is a variable.

Handling user-specified colors: If the user provided color preferences (e.g., "terracotta and cream"), map them to the appropriate tokens (--primary, --background, --accent) and derive the rest of the palette (secondary, muted, foregrounds, borders) to complement. The industry palette tables are starting points, not mandates.

Post-creation color changes: Since all components use $-- token references (not hardcoded hex), calling set_variables again with new color values updates the entire design system instantly — every component, pattern, and screen inherits the change. No per-node updates needed.

Token categories:

Semantic colors MUST be derived from the primary palette. Match the temperature (warm/cool), saturation, and lightness of your primary/accent colors. Do NOT use default Tailwind green/amber/red/blue (#22C55E, #F59E0B, #EF4444, #3B82F6). A warm muted palette needs warm muted semantics (sage green, golden amber, terracotta red, dusty blue). A cool vivid palette needs cool vivid semantics (teal-green, gold, crimson, blue). See references/design-tokens-reference.md for the derivation algorithm and per-industry examples.

CRITICAL — Exact set_variables format. Copy this structure exactly. Do NOT deviate.

CORRECT format for color tokens (themed — light + dark):

{
  "--primary": {
    "type": "color",
    "value": [
      { "value": "#3E2723", "theme": { "mode": "light" } },
      { "value": "#D7CCC8", "theme": { "mode": "dark" } }
    ]
  }
}

CORRECT format for non-color tokens (no theme needed):

{
  "--font-primary": { "type": "string", "value": [{ "value": "Fraunces, serif" }] },
  "--radius-md":    { "type": "number", "value": [{ "value": 6 }] },
  "--text-base":    { "type": "number", "value": [{ "value": 16 }] },
  "--space-4":      { "type": "number", "value": [{ "value": 16 }] }
}

WRONG — these will break theming:

// WRONG: empty theme object — light/dark switching will NOT work
{ "value": "#3E2723", "theme": {} }

// WRONG: missing theme entirely on colors — both values collapse to same
{ "value": [{ "value": "#3E2723" }, { "value": "#D7CCC8" }] }

// WRONG: "themes" key in variables object — causes error
{ "themes": { "mode": ["light", "dark"] }, "--primary": { ... } }

// WRONG: "values" (plural) instead of "value"
{ "--primary": { "type": "color", "values": [...] } }

Post-creation verification (MANDATORY): After calling set_variables, immediately call get_variables and check EVERY color token. Each must show:

• "theme": {"mode": "light"} on the first value
• "theme": {"mode": "dark"} on the second value

If ANY color shows "theme": {} (empty object) or missing theme keys, the format was WRONG. Delete all variables and redo with the correct format above. Do NOT proceed to Phase 4 with broken themes.

See references/design-tokens-reference.md for full JSON payloads.

⛔ REVIEW — Tokens

Call get_variables and present results:

Tokens Created — [count] total

| Category        | Count | Status      |
|-----------------|-------|-------------|
| Core colors     | 19    | light+dark  |
| Semantic colors | 8     | light+dark  |
| Typography      | 3     |             |
| Border radius   | 6     |             |
| Spacing         | 12    |             |
| Shadows         | 4     |             |
| Font sizes      | 9     |             |
| Line heights    | 3     |             |

[any warnings: missing themes, wrong format, etc.]

[c] Continue to Foundations [r] Redo — tell me what to change [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 4 — Build Foundations (Visual Documentation)

Create the Foundations section frame at the left of the canvas with width: 1440, height: "fit_content", layout: "vertical". Do NOT use fixed heights — use height: "fit_content" so the frame grows to fit all content. Inside it, build 11 visual documentation frames:

1. Color Palette — Labeled swatches for all 27 color tokens. Split into rows of max 5-6 swatches each to prevent horizontal overflow. Use multiple horizontal rows inside a vertical container (e.g., Row 1: Primary, Secondary, Accent, Background, Card. Row 2: Success, Warning, Destructive, Muted, Input, Border. Row 3: Foregrounds + remaining). Each swatch is ~140-160px wide — 6 swatches + gaps fit within 1280px content width.
2. Typography Scale — 6 specimens (H1 → Caption) rendered at real sizes with metadata labels.
3. Spacing Scale — 12 visual blocks showing each spacing value with labels. Use 2 rows of 6 blocks each.
4. Elevation — 4 cards demonstrating shadow levels in a single horizontal row.
5. Border Radius — 6 rectangles showcasing each radius token in a single horizontal row.
6. Font Sizes — 9 text samples rendered at actual --text-xs through --text-5xl sizes with token name + pixel value labels.
7. Font Weights — Same sample text rendered in each of the 6 weight tokens (--weight-thin through --weight-bold).
8. Semantic Colors — 4 large card-like swatches for success/warning/error/info, each showing the color paired with its foreground.
9. Sizing — Visual rectangles showing icon sizes (sm/md/lg), avatar sizes (sm/md/lg), button height, and input height.
10. Shadows & Borders — Expanded elevation section showing 4 shadow levels + 3 border width examples + 3 opacity examples.
11. Letter Spacing — Same text rendered at each --tracking-* value with labels.

Critical: Use a neutral white backdrop (fill: "#FFFFFF"), NOT the design system's own $--background token. The Foundations section is documentation chrome — using the themed background (e.g., cream for a bakery, blue-gray for SaaS) makes light swatches like --card, --secondary, and --muted nearly invisible. A neutral white surface lets every color be evaluated accurately against a known reference. Swatches use $-- tokens for their fills; only the documentation frame itself is neutral.

These are documentation frames, NOT reusable components. They use $-- tokens for swatch fills everywhere. See references/foundations-specs.md for exact batch_design code (spread across Batches A–J within 25-op limits).

After each batch, call get_screenshot to verify rendering.

⛔ REVIEW — Foundations

Call get_screenshot on the Foundations frame and present:

Foundations Complete

Sections built:
 - Color Palette (27 swatches)
 - Typography Scale (6 specimens)
 - Spacing Scale (12 blocks)
 - Elevation (4 shadow levels)
 - Border Radius (6 shapes)
 - Font Sizes (9 samples)
 - Font Weights (6 weight samples)
 - Semantic Colors (4 status cards)
 - Sizing (icons, avatars, buttons, inputs)
 - Shadows & Borders (shadows + border widths + opacity)
 - Letter Spacing (4 tracking samples)

[screenshot]
[any visual issues: blank swatches, overlap, clipping]

[c] Continue to Components [r] Redo — tell me what to fix [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 4b — Build Icon Library

Build a documentation frame inside Foundations (after the Letter Spacing section) containing a curated set of 42 Lucide icons organized into 6 categories. This makes the design system self-documenting — users can see all available icons at a glance.

Structure:

Each icon rendered as:

iconFrame=I(categoryRow, { type: "frame", layout: "vertical", gap: 6, alignItems: "center", width: 80, padding: [12, 8, 12, 8] })
icon=I(iconFrame, { type: "icon_font", iconFontFamily: "lucide", iconFontName: "[name]", width: 24, height: 24, fill: "$--foreground" })
iconLabel=I(iconFrame, { type: "text", content: "[name]", fontFamily: "$--font-mono", fontSize: 10, fill: "$--muted-foreground", textAlignHorizontal: "center" })

Each category row = ~23 ops (1 title + 1 row frame + 7 icons × 3 ops). Total: 6 batch_design calls.

Domain adaptation: Supplement the base 42 icons with domain-specific icons:

• Food/Bakery: utensils, cake, coffee, wine, shopping-bag
• SaaS/Dashboard: layout-dashboard, bar-chart-2, database, cloud, webhook
• Fitness: dumbbell, timer, activity, trophy, flame
• E-commerce: shopping-cart, package, truck, credit-card, tag

IMPORTANT: Use explicit pixel values (24) for icon_font width/height — variable references like $--size-icon-lg may resolve to 0 for icon_font nodes.

No review gate here — continue directly to Phase 5.

Phase 5 — Build Base Components (~15 Primitives)

Create the Components section frame to the right of Foundations with width: 1440, height: "fit_content", layout: "vertical", fill: "#FFFFFF" (same neutral backdrop rationale as Foundations — light-fill variants like Ghost buttons and muted badges need a known white reference). Do NOT use fixed heights — use height: "fit_content".

⚠ CRITICAL STRUCTURE FOR EACH BATCH:

1. Create a category frame (layout: "vertical", width: "fill_container") inside Components section
2. Add a category title text
3. Create a display row (layout: "horizontal", gap: 16, width: "fill_container") inside the category
4. Insert components into the display row — NOT directly into the Components section
5. If elements overlap after batch_design, the parent frame is missing layout — fix immediately

Every component has reusable: true, uses only $-- tokens, and follows "Category/Variant" naming. See references/component-specs.md.

MANDATORY — Post-Batch Validation (after EVERY batch_design call):

1. Check the batch response for "unknown properties were ignored" warnings — fix immediately.
2. Call get_screenshot on the affected section — visually confirm no overlapping elements, no invisible shadows, no broken layouts.
3. If ANY elements overlap or stack on top of each other, the parent frame is missing layout: "horizontal" or layout: "vertical". Fix it before proceeding to the next batch.

Phase 6 — Build Composite Components (~10 Composites)

Continue inside the Components section frame, adding category sub-frames for each composite group.

After batches 8, 11, and 14: run get_screenshot and snapshot_layout({ problemsOnly: true }). Fix issues immediately. See references/component-specs.md.

⛔ REVIEW — Components

Call batch_get({ patterns: [{ reusable: true }] }), get_screenshot, and snapshot_layout({ problemsOnly: true }). Present:

Components Created — [count] reusable

| Category    | Components                              | Count |
|-------------|----------------------------------------|-------|
| Buttons     | Primary, Secondary, Outline, Ghost, Destructive | 5 |
| Inputs      | TextField, Textarea, Select, InputGroup | 4 |
| Typography  | H1, H2, H3, Body, Caption, Label      | 6 |
| Badges      | Default, Success, Warning, Error       | 4 |
| Alerts      | Info, Success, Warning, Error          | 4 |
| Card        | Header + Content + Actions             | 1 |
| Navigation  | Sidebar, Active, Default, SectionTitle | 4 |
| Table       | Wrapper, HeaderRow, DataRow            | 3 |
| ...         | [remaining composites]                 | ... |

[screenshot]
[layout issues from snapshot_layout, if any]

[c] Continue to Patterns [r] Redo — tell me what to fix [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 7 — Build Patterns (Composition Showcases)

Create the Patterns section frame to the right of Components with width: 1440, height: "fit_content", layout: "vertical". Build 4 composition showcases that demonstrate real usage of the components:

1. Form Pattern — Vertical stack (layout: "vertical") of InputGroup refs + Submit button.
2. Data Display Pattern — Table ref with populated rows + Pagination ref, stacked vertically.
3. Navigation Pattern — Horizontal layout with sidebar (left, layout: "vertical", width: 240px) + content area (right, layout: "vertical", width: "fill_container"). The sidebar frame MUST have layout: "vertical" so nav items stack. Each nav item is a separate text/ref element inside the sidebar.
4. Card Layout Pattern — Horizontal row of populated Card refs (layout: "horizontal", gap: 24). Use width: "fill_container" on cards to distribute evenly. Add domain-relevant stock images to each card using G(imageFrame, "stock", "[domain] keyword") — e.g., for a coffee shop: "latte art", "coffee beans", "barista".

Using images (G() operation):

• Card images: Insert a frame (e.g., width: "fill_container", height: 200) inside the card, then G(frame, "stock", "[domain keyword]")
• Avatar components: G(avatarFrame, "stock", "professional portrait")
• Hero sections in screens: G(heroFrame, "stock", "[domain] hero")
• Use "stock" for realistic photos, "ai" for custom/branded visuals
• Always insert the frame FIRST, then apply G() — images are fills on frames, not separate nodes

Layout rules for patterns:

• Every frame that arranges children horizontally MUST have layout: "horizontal"
• Every frame that stacks children vertically MUST have layout: "vertical"
• Sidebar/nav containers are ALWAYS layout: "vertical"
• Content areas with mixed content are ALWAYS layout: "vertical"

Each pattern uses only ref instances + $-- tokens. After each pattern, run the Post-Batch Validation (screenshot + check for overlapping/broken layouts). See references/screen-patterns.md.

⛔ REVIEW — Patterns

Call get_screenshot on the Patterns frame and present:

Patterns Complete — 4 composition showcases

 1. Form Pattern       — InputGroup refs + Submit button
 2. Data Display       — Table ref + Pagination ref
 3. Navigation Pattern — Sidebar + Breadcrumbs + Tabs refs
 4. Card Layout        — Grid of populated Card refs

[screenshot]
[any layout or ref issues]

[c] Continue to Screens (or skip to verification if no screens requested) [r] Redo — tell me what to fix [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 8 — Create Domain Screens (only if user requests)

Skip this phase unless the user explicitly asks for screens (e.g., "build screens for a bakery", "I need a landing page and menu screen", "create example screens"). The core deliverable is Foundations + Components + Patterns — screens are an optional add-on.

If the user requests screens, build 3–5 placed to the right of the Patterns section. Each screen uses only component ref instances and $-- variable tokens.

Per-screen workflow:

1. Call find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 }).
2. Insert screen frame at returned position.
3. Build layout with component refs. Customize via U(instanceId+"/descendantId", {...}).
4. Add domain imagery via G().
5. Call get_screenshot to verify.

See references/screen-patterns.md for domain-specific screen templates.

⛔ REVIEW — Domain Screens (only if Phase 8 was executed)

Call get_screenshot on each screen and present:

Domain Screens — [count] created

 1. [Screen Name] — [brief description]
 2. [Screen Name] — [brief description]
 ...

[screenshots]
[any issues: missing refs, hardcoded values, layout problems]

[c] Continue to Business Logic Screens (or verification) [r] Redo — tell me what to fix [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 8b — Business Logic Screens (only if user provides requirements)

Skip this phase unless the user provides specific product requirements, user flows, or feature specs. This differs from Phase 8 (generic domain screens) — here the user supplies their actual business logic and the AI designs screens tailored to it.

The user might provide:

• User flows: "checkout: cart → address → payment → confirmation"
• Feature specs: "CRM with contact list, deal pipeline kanban, activity timeline"
• A PRD or user story document
• Wireframe descriptions: "onboarding wizard with 4 steps"

Workflow:

1. Read existing components: batch_get({ patterns: [{ reusable: true }], readDepth: 2 }).
2. Read existing tokens: get_variables({ filePath }).
3. Plan screens based on user requirements — map each user flow or feature to a screen.
4. For each screen: a. Call find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 }). b. Insert screen frame at returned position. c. Build layout using existing component ref instances. d. Customize content via U(instanceId+"/descendantId", {...}) with realistic business data. e. Add imagery via G() where appropriate. f. Call get_screenshot to verify.

⛔ REVIEW — Business Logic Screens

Call get_screenshot on each screen and present:

Business Logic Screens — [count] created

 1. [Screen Name] — maps to: [which user requirement/flow]
 2. [Screen Name] — maps to: [which user requirement/flow]
 ...

[screenshots]
[any issues or gaps vs requirements]

[c] Continue to Layout Enforcement [r] Redo — tell me what to fix [s] Skip to final verification

WAIT for user input. Do NOT proceed.

Phase 9 — Layout Enforcement Pass (MANDATORY)

Why this exists: The AI consistently drops layout: "horizontal" from frames during generation, even when specs include it. This pass programmatically catches and fixes every missing layout. This phase is NOT optional — skip it and the design will have broken layouts.

Step 1 — Collect all frames with flex properties.

batch_get({ filePath, patterns: [{ type: "frame" }], searchDepth: 10, readDepth: 0 })

Search within EACH top-level section (Foundations, Components, Patterns, and any screens).

Step 2 — Identify frames needing layout enforcement. From the results, find every frame that has ANY of: gap, alignItems, justifyContent — regardless of whether layout already appears (since batch_get doesn't display layout: "horizontal" in its output — it's considered the default).

Step 3 — Bulk-apply layout: "horizontal" to ALL identified frames.

U("frameId1", { layout: "horizontal" })
U("frameId2", { layout: "horizontal" })
// ... for every frame with gap/alignItems/justifyContent

Exclude frames that should be vertical (identifiable by name: category sections, form containers, vertical stacks). Apply layout: "vertical" to those instead.

Step 4 — Verify shadows use hex colors. Check any frame with effect property. If color uses rgba() format, replace with 8-digit hex #RRGGBBAA.

Step 5 — Screenshot every section to confirm no overlapping elements.

This is safe to run multiple times — setting layout: "horizontal" on a frame that already has it is a no-op.

Phase 10 — Final Verification

Run comprehensive QA. Fix every issue before presenting to the user.

1. Visual — get_screenshot on Foundations, Components, Patterns (and screens if created). Check alignment, spacing, typography, color, overflow.
2. Layout — snapshot_layout({ problemsOnly: true }) to detect clipping/overflow. Fix all.
3. Token audit — search_all_unique_properties for fillColor, textColor, fontFamily, fontSize. Replace leaked hex values and raw font sizes with $-- tokens.
4. Component audit — batch_get({ patterns: [{ reusable: true }] }). Verify ~25 components.
5. Organization audit — Verify no orphan components at document root. All should be under Components section.
6. Fix and re-verify — Re-screenshot affected areas after fixes.
7. Present — Summarize tokens, components, patterns (and screens if created). Show key screenshots.

See references/verification-checklist.md.

Phase 11 — Canvas Navigation Index

Create a small navigation index frame at the canvas origin (x: 0, y: 0) showing a map of all sections with their positions:

Design System Index
├── Foundations (x, y)
├── Components (x, y)
├── Patterns (x, y)
└── Screens (x, y) — only if screens were created

This helps users navigate the canvas. Only include the Screens entry if Phase 8 was executed.

Phase 12 — Code Export (optional, user-triggered)

Skip this phase unless the user explicitly requests code export (e.g., "export to Tailwind", "convert to code", "generate React components", "export as CSS"). This phase converts the design system into production-ready Tailwind CSS + React components.

Step 1 — Collect preferences. Ask the user for:

• Tailwind version: v3 or v4
• Framework: Next.js or Vite+React

Step 2 — Extract tokens. Call get_variables({ filePath }) to read all ~89 tokens. Categorize by type (color, number, string, shadow). Separate themed (light/dark) from static tokens.

Step 3 — Read components. Call batch_get({ patterns: [{ reusable: true }], readDepth: 3, searchDepth: 3 }) to get every reusable component with its full node tree.

Step 4 — Load Pencil's code generation guidelines. Call get_guidelines("code") and get_guidelines("tailwind"). These are the primary authority for translating Pencil nodes to code — they cover component instance mapping, property-to-Tailwind-class translation, font wiring, and visual verification. Follow them for all translation work in Steps 8-9.

Step 5 — Generate globals.css. Build the CSS file with all tokens as CSS custom properties:

• v3: :root with HSL values (space-separated, no hsl() wrapper), .dark overrides, @layer base font utilities
• v4: @import "tailwindcss", @custom-variant dark, :root with hex values, .dark overrides, @layer base font utilities

Step 6 — Generate tailwind.config.js (v3 only). Map all tokens to Tailwind utility names: colors via hsl(var(--name)), radii, shadows, font sizes, spacing, line heights.

Step 7 — Generate font loading code.

• Next.js: layout.tsx with next/font/google loader setting --font-primary, --font-secondary, --font-mono CSS variables
• Vite+React: <link> tags in index.html loading all three fonts from Google Fonts

Step 8 — Generate component TSX files. One file per component category (button.tsx, input.tsx, card.tsx, badge.tsx, alert.tsx, etc.). Each component:

• Uses only token-referencing Tailwind classes (no hardcoded hex)
• Has TypeScript interfaces with variant props where applicable
• Accepts and spreads an optional className prop
• Uses v3 mapped classes (bg-primary) or v4 arbitrary values (bg-[var(--primary)]) based on the chosen version

Step 9 — Generate screen/page TSX files. For each screen design in the .pen file:

1. Deep-read the screen frame: batch_get({ nodeIds: [screenId], readDepth: 10, resolveInstances: true })
2. Take a reference screenshot: get_screenshot({ nodeId: screenId })
3. Follow Pencil's Component Implementation Workflow (from Step 4's get_guidelines("code")):
   • Steps 1A-1C: Extract components, map ALL instances with ALL overrides and descendants
   • Step 2: Create React components using get_guidelines("tailwind") for property-to-class mapping
   • Step 3: Validate each component with get_screenshot — pixel-perfect match required
   • Step 4: Integrate into frame, verify instance count and prop completeness
4. Handle screen-level elements: semantic HTML for headings/labels/links, page wrapper, form behavior, icon name conversion, image fills
5. Assemble into a complete page file with all imports
6. Visually verify the rendered page against the Pencil screenshot — fix any discrepancies

See references/code-export-guide.md (Section 7) for the complete screen export workflow and common pitfalls.

Critical Rules

Rule 1 — Always reuse components. Search with batch_get({ patterns: [{ reusable: true }] }) before creating. On screens, every element must be a ref instance.

Rule 2 — Never hardcode values. All colors use $-- tokens. All fonts use $--font-*. All radii use $--radius-*. All font sizes use $--text-*. Raw values only appear in set_variables.

Rule 3 — Prevent overflow. Constrain text with width: "fill_container". Use layout frames. Validate with snapshot_layout({ problemsOnly: true }).

Rule 4 — Verify visually. Call get_screenshot after every major batch. Fix problems immediately.

Rule 5 — Reuse assets. Copy images with C() instead of regenerating with G().

Rule 6 — Domain coherence. Every choice connects back to Phase 1 research.

Rule 7 — Canvas organization. All components go inside the Components section frame under categorized sub-frames. No components at document root. Foundations, Components, Patterns, and Screens flow left-to-right on the canvas.

Component Inventory

References

Load the relevant file before starting each phase:

• references/pencil-mcp-guide.md — Complete Pencil MCP tool reference with examples and operation syntax.
• references/domain-research-guide.md — Domain research strategies, color psychology, font pairings, screen inventories.
• references/design-tokens-reference.md — Token architecture, set_variables JSON payloads, ~89 token definitions, industry palettes.
• references/foundations-specs.md — Visual foundation documentation: color palette, typography scale, spacing, elevation, radius batch_design code.
• references/component-specs.md — All ~25 component batch_design operation code with section frame organization.
• references/screen-patterns.md — Layout patterns, composition showcases, and domain-specific screen templates.
• references/verification-checklist.md — Visual QA, layout checks, token audits, canvas organization verification.
• references/code-export-guide.md — Tailwind CSS export: token extraction, v3/v4 templates, Pencil-to-Tailwind class cheatsheet, component translation, framework setup (Next.js / Vite+React).