Pencil Design System generator. Invoke with /pds followed by a business domain (e.g., "/pds coffee shop that sells coffee online"). Creates a complete design system with tokens, foundations, components, patterns, and optional screens in a .pen file.
Generate a complete, Mews-inspired design system in a Pencil .pen file. Research the business domain, create ~89 themed tokens, build visual foundation documentation, ~25 reusable components organized by category, and composition patterns — all from a single command like /pds coffee shop that sells coffee online. Domain screens are generated only if the user explicitly requests them.
These rules prevent the #1 visual bug (overlapping elements). Violating any of these produces a broken design.
layout: "vertical" or layout: "horizontal". No exceptions. Without it, children are placed at absolute position (0,0) and overlap each other. This includes: section frames, category rows, component root frames, card bodies, nav containers — ALL frames.layout: "horizontal". Components shown side-by-side need a horizontal row frame.height: "fit_content" on section framesbatch_design, take a screenshot and CHECK for overlapping elements. Missing layout → add it immediately.open_document("new"). Always check get_editor_state first — if a .pen file exists, use it.When this skill is invoked via /pds, begin with:
/pdsPencil 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...
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:
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.
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 →]
No components live at the document root except these section frames and the optional navigation index.
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.
If collectui-mcp is available: Use it for visual research before web search.
collectui_search({ query: "[domain]", limit: 8 }) — e.g., "coffee shop", "dashboard", "e-commerce"If a reference image exists: Check if the user placed an image on the canvas or provided one in chat.
get_screenshot on the image node to analyze itRun a 7-pass structured extraction to map visual properties to specific tokens:
| Pass | What to Extract | Token Mapping |
|---|---|---|
| 1. Colors | Background color(s), primary brand color, secondary/supporting color, accent color (buttons/links/highlights), text colors (heading, body, muted/caption), border/divider colors, any semantic indicators (green/amber/red for status) | --background, --primary, --secondary, --accent, --foreground, --muted-foreground, --border, --color-success/warning/error/info |
| 2. Typography | Heading font (serif/sans? geometric/humanist?), body font, font weights observed (thin, regular, semibold, bold?), letter spacing patterns (tight headings? wide all-caps?), line height density | --font-primary, --font-secondary, --weight-*, --tracking-*, --leading-* |
| 3. Spacing & Sizing | Overall density (spacious/moderate/compact), padding scale estimates (small 4-8px, medium 12-16px, large 24-32px), component sizes (button height, input height, icon sizes), gap patterns between cards/fields/sections | --space-*, --size-button-height, --size-input-height, --size-icon-*, --size-sidebar-width |
| 4. Shape Language | Corner radius style (sharp 0-2px, subtle 4-6px, medium 8-12px, rounded 16+px, pill), shadow depth (none/subtle/moderate/prominent), border usage pattern | --radius-*, --shadow-*, --border-thin/default/thick |
| 5. Visual Patterns | Card-heavy or flat/borderless layout, icon style (outlined/solid, thin/regular stroke), opacity usage (transparent overlays, disabled states), border widths (hairline 1px, default 1-2px, thick 2-3px) | --opacity-*, --border-* |
| 6. Tone | Professional/corporate, playful/casual, minimal/clean, bold/dramatic, organic/natural — and implied audience (enterprise, consumer, creative, developer) | Informs semantic color derivation and font selection |
| 7. Structured Output | Compile a mapping table: each extracted value → specific token name and estimated value | Feeds directly into Phase 3 token creation |
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.
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:
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.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.
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:
| Category | Count | Examples |
|---|---|---|
| Core colors | 19 | --background, --foreground, --primary, --secondary, --muted, --accent, --destructive, --border, --input, --ring |
| Semantic colors | 8 | --color-success, --color-warning, --color-error, --color-info + foregrounds |
| Typography | 3 | --font-primary, --font-secondary, --font-mono |
| Border radius | 6 | --radius-none (0) through --radius-pill (9999) |
| Spacing | 12 | --space-1 (4) through --space-24 (96) |
| Shadows | 4 | --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl |
| Font sizes | 9 | --text-xs (12) through --text-5xl (48) |
| Line heights | 3 | --leading-tight (1.25), --leading-normal (1.5), --leading-relaxed (1.75) |
| Font weights | 6 | --weight-thin ("200") through --weight-bold ("700") |
| Letter spacing | 4 | --tracking-tight (-0.5) through --tracking-wide (1.5) |
| Sizing | 9 | --size-icon-sm (16), --size-avatar-md (40), --size-button-height (40), --size-sidebar-width (240) |
| Opacity | 3 | --opacity-disabled (0.5), --opacity-hover (0.8), --opacity-overlay (0.6) |
| Border widths | 3 | --border-thin (1), --border-default (1.5), --border-thick (2) |
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 valueIf 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.
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:
--text-xs through --text-5xl sizes with token name + pixel value labels.--weight-thin through --weight-bold).--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.
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:
| Category | Icons (7 each) |
|---|---|
| Navigation | house, arrow-left, arrow-right, chevron-down, menu, search, x |
| Action | plus, minus, edit, trash-2, download, upload, copy |
| Status | check, circle-check, circle-x, triangle-alert, info, loader, clock |
| Social | share, heart, star, bookmark, message-circle, bell, user |
| Media | image, camera, play, pause, volume-2, mic, film |
| Misc | settings, filter, eye, eye-off, lock, unlock, globe |
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:
utensils, cake, coffee, wine, shopping-baglayout-dashboard, bar-chart-2, database, cloud, webhookdumbbell, timer, activity, trophy, flameshopping-cart, package, truck, credit-card, tagIMPORTANT: 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.
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:
layout: "vertical", width: "fill_container") inside Components sectionlayout: "horizontal", gap: 16, width: "fill_container") inside the categorylayout — fix immediately| Batch | Category | Components | Count |
|---|---|---|---|
| 1 | Buttons | Category (vertical) → Row (horizontal) → Primary, Secondary, Outline, Ghost, Destructive | 5 |
| 2 | Inputs | Category (vertical) → Row (horizontal) → TextField, Textarea, Select, InputGroup | 4 |
| 3 | Typography | Category (vertical) → H1, H2, H3, Body, Caption, Label stacked | 6 |
| 4 | Badges | Category (vertical) → Row (horizontal) → Default, Success, Warning, Error | 4 |
| 5 | Alerts | Category (vertical) → Info, Success, Warning, Error stacked | 4 |
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):
get_screenshot on the affected section — visually confirm no overlapping elements, no invisible shadows, no broken layouts.layout: "horizontal" or layout: "vertical". Fix it before proceeding to the next batch.Continue inside the Components section frame, adding category sub-frames for each composite group.
| Batch | Category | Components | Count |
|---|---|---|---|
| 6 | Card | Header + Content + Actions slots | 1 |
| 7 | Navigation | Sidebar container, ActiveItem, DefaultItem, SectionTitle | 4 |
| 8 | Table | Wrapper, HeaderRow, DataRow | 3 |
| 9 | Tabs | Container, ActiveTab, InactiveTab | 3 |
| 10 | Breadcrumbs | Item, Separator, ActiveItem | 3 |
| 11 | Pagination | Container, PageItem, ActiveItem, PrevNext | 4 |
| 12 | Modal | Dialog with Header/Body/Footer | 1 |
| 13 | Dropdown | Container, Item, Divider, SectionTitle | 4 |
| 14 | Misc | Avatar, Divider, Switch, Checkbox, Radio | 5 |
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.
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:
layout: "vertical") of InputGroup refs + Submit button.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.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):
width: "fill_container", height: 200) inside the card, then G(frame, "stock", "[domain keyword]")G(avatarFrame, "stock", "professional portrait")G(heroFrame, "stock", "[domain] hero")"stock" for realistic photos, "ai" for custom/branded visualsG() — images are fills on frames, not separate nodesLayout rules for patterns:
layout: "horizontal"layout: "vertical"layout: "vertical"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.
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:
find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 }).U(instanceId+"/descendantId", {...}).G().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.
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:
Workflow:
batch_get({ patterns: [{ reusable: true }], readDepth: 2 }).get_variables({ filePath }).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.
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.
Run comprehensive QA. Fix every issue before presenting to the user.
get_screenshot on Foundations, Components, Patterns (and screens if created). Check alignment, spacing, typography, color, overflow.snapshot_layout({ problemsOnly: true }) to detect clipping/overflow. Fix all.search_all_unique_properties for fillColor, textColor, fontFamily, fontSize. Replace leaked hex values and raw font sizes with $-- tokens.batch_get({ patterns: [{ reusable: true }] }). Verify ~25 components.See references/verification-checklist.md.
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.
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:
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:
:root with HSL values (space-separated, no hsl() wrapper), .dark overrides, @layer base font utilities@import "tailwindcss", @custom-variant dark, :root with hex values, .dark overrides, @layer base font utilitiesStep 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.
layout.tsx with next/font/google loader setting --font-primary, --font-secondary, --font-mono CSS variables<link> tags in index.html loading all three fonts from Google FontsStep 8 — Generate component TSX files. One file per component category (button.tsx, input.tsx, card.tsx, badge.tsx, alert.tsx, etc.). Each component:
className propbg-primary) or v4 arbitrary values (bg-[var(--primary)]) based on the chosen versionStep 9 — Generate screen/page TSX files. For each screen design in the .pen file:
batch_get({ nodeIds: [screenId], readDepth: 10, resolveInstances: true })get_screenshot({ nodeId: screenId })get_guidelines("code")):
get_guidelines("tailwind") for property-to-class mappingget_screenshot — pixel-perfect match requiredSee references/code-export-guide.md (Section 7) for the complete screen export workflow and common pitfalls.
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 | Type | Variants |
|---|---|---|---|
| 1–5 | Button | Primitive | Primary, Secondary, Outline, Ghost, Destructive |
| 6–9 | Input | Primitive | TextField, Textarea, Select, InputGroup |
| 10–15 | Typography | Primitive | H1, H2, H3, Body, Caption, Label |
| 16–19 | Badge | Primitive | Default, Success, Warning, Error |
| 20–23 | Alert | Primitive | Info, Success, Warning, Error |
| 24 | Card | Composite | Header + Content + Actions slots |
| 25–28 | Sidebar Nav | Composite | Container, ActiveItem, DefaultItem, SectionTitle |
| 29–31 | Table | Composite | Wrapper, HeaderRow, DataRow |
| 32–34 | Tabs | Composite | Container, ActiveTab, InactiveTab |
| 35–37 | Breadcrumbs | Composite | Item, Separator, ActiveItem |
| 38–41 | Pagination | Composite | Container, PageItem, ActiveItem, PrevNext |
| 42 | Modal/Dialog | Composite | Overlay + Content with slots |
| 43–46 | Dropdown | Composite | Container, MenuItem, Divider, SectionTitle |
| 47–51 | Miscellaneous | Composite | Avatar, Divider, Switch, Checkbox, Radio |
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).