Pencil Design System Generator
Generate a complete, Mews-inspired design system in a Pencil
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.
⛔ GOLDEN RULES — Read These First
These rules prevent the #1 visual bug (overlapping elements). Violating any of these produces a broken design.
- EVERY frame MUST have or . 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.
- Category display rows MUST use . Components shown side-by-side need a horizontal row frame.
- Use on section frames — never fixed pixel heights.
- After EVERY , take a screenshot and CHECK for overlapping elements. Missing → add it immediately.
- Copy the exact operation code from the reference files. Do NOT improvise layout code.
- NEVER call . Always check first — if a file exists, use it.
Getting Started
When this skill is invoked via
, begin with:
- Parse the user's input — extract domain, brand name, color preferences, font preferences from their message after
- 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...
- 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
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
to continue,
to redo, or
to skip ahead.
Phase 1 — Research the Domain
If is available: Use it for visual research before web search.
- Call
collectui_search({ query: "[domain]", limit: 8 })
- Analyze the returned design screenshots — extract dominant colors (hex), typography patterns, layout styles, corner radii, shadow depth
- 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 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:
| 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) | , , , , , , , --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 | , , , , |
| 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 | , , , , |
| 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 | , , --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) | , |
| 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
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
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
field.
⛔ STOP AND DECIDE — do NOT skip this check:
- If contains a file (e.g., , , anything ending in ): USE THAT FILE. Do NOT call at all. The document is already open. Save the for all subsequent calls.
- ONLY if is empty/null/undefined (meaning NO file is open): Create a named file:
open_document("./[domain]-design-system.pen")
NEVER call . This creates a generic
that ignores the existing file.
NEVER call if a file is already open. This creates a SECOND document.
Step 2 — Call
get_guidelines({ topic: "design-system" })
.
Step 3 — Call
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
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 (
,
,
) 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
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 | , , , , , , , , , |
| Semantic colors | 8 | , , , + foregrounds |
| Typography | 3 | , , |
| Border radius | 6 | (0) through (9999) |
| Spacing | 12 | (4) through (96) |
| Shadows | 4 | , , , |
| Font sizes | 9 | (12) through (48) |
| Line heights | 3 | (1.25), (1.5), (1.75) |
| Font weights | 6 | ("200") through ("700") |
| Letter spacing | 4 | (-0.5) through (1.5) |
| Sizing | 9 | (16), (40), (40), (240) |
| Opacity | 3 | (0.5), (0.8), (0.6) |
| Border widths | 3 | (1), (1.5), (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 (
,
,
,
). 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 format. Copy this structure exactly. Do NOT deviate.
CORRECT format for color tokens (themed — light + dark):
json
{
"--primary": {
"type": "color",
"value": [
{ "value": "#3E2723", "theme": { "mode": "light" } },
{ "value": "#D7CCC8", "theme": { "mode": "dark" } }
]
}
}
CORRECT format for non-color tokens (no theme needed):
json
{
"--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:
json
// 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
, immediately call
and check EVERY color token. Each must show:
"theme": {"mode": "light"}
"theme": {"mode": "dark"}
If ANY color shows
(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
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
so the frame grows to fit all content. Inside it, build 11 visual documentation frames:
- 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.
- Typography Scale — 6 specimens (H1 → Caption) rendered at real sizes with metadata labels.
- Spacing Scale — 12 visual blocks showing each spacing value with labels. Use 2 rows of 6 blocks each.
- Elevation — 4 cards demonstrating shadow levels in a single horizontal row.
- Border Radius — 6 rectangles showcasing each radius token in a single horizontal row.
- Font Sizes — 9 text samples rendered at actual through sizes with token name + pixel value labels.
- Font Weights — Same sample text rendered in each of the 6 weight tokens ( through ).
- Semantic Colors — 4 large card-like swatches for success/warning/error/info, each showing the color paired with its foreground.
- Sizing — Visual rectangles showing icon sizes (sm/md/lg), avatar sizes (sm/md/lg), button height, and input height.
- Shadows & Borders — Expanded elevation section showing 4 shadow levels + 3 border width examples + 3 opacity examples.
- Letter Spacing — Same text rendered at each value with labels.
Critical: Use a neutral white backdrop (), NOT the design system's own 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
,
, and
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
code (spread across Batches A–J within 25-op limits).
After each batch, call
to verify rendering.
⛔ REVIEW — Foundations
Call
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:
| Category | Icons (7 each) |
|---|
| Navigation | , , , , , , |
| Action | , , , , , , |
| Status | , , , , , , |
| Social | , , , , , , |
| Media | , , , , , , |
| Misc | , , , , , , |
Each icon rendered as:
javascript
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
calls.
Domain adaptation: Supplement the base 42 icons with domain-specific icons:
- Food/Bakery: , , , ,
- SaaS/Dashboard: , , , ,
- Fitness: , , , ,
- E-commerce: , , , ,
IMPORTANT: Use explicit pixel values (24) for
width/height — variable references like
may resolve to 0 for
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
.
⚠ CRITICAL STRUCTURE FOR EACH BATCH:
- Create a category frame (, ) inside Components section
- Add a category title text
- Create a display row (, , ) inside the category
- Insert components into the display row — NOT directly into the Components section
- If elements overlap after batch_design, the parent frame is missing — 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
, uses only
tokens, and follows
naming. See
references/component-specs.md
.
MANDATORY — Post-Batch Validation (after EVERY batch_design call):
- Check the batch response for "unknown properties were ignored" warnings — fix immediately.
- Call on the affected section — visually confirm no overlapping elements, no invisible shadows, no broken layouts.
- If ANY elements overlap or stack on top of each other, the parent frame is missing or . 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.
| 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
and
snapshot_layout({ problemsOnly: true })
. Fix issues immediately. See
references/component-specs.md
.
⛔ REVIEW — Components
Call
batch_get({ patterns: [{ reusable: true }] })
,
, 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:
- Form Pattern — Vertical stack () of InputGroup refs + Submit button.
- Data Display Pattern — Table ref with populated rows + Pagination ref, stacked vertically.
- Navigation Pattern — Horizontal layout with sidebar (left, , width: 240px) + content area (right, , ). The sidebar frame MUST have so nav items stack. Each nav item is a separate text/ref element inside the sidebar.
- Card Layout Pattern — Horizontal row of populated Card refs (, ). Use on cards to distribute evenly. Add domain-relevant stock images to each card using
G(imageFrame, "stock", "[domain] keyword")
Using images ( operation):
- Card images: Insert a frame (e.g.,
width: "fill_container", height: 200
G(frame, "stock", "[domain keyword]")
- Avatar components:
G(avatarFrame, "stock", "professional portrait")
- Hero sections in screens:
G(heroFrame, "stock", "[domain] hero")
- Use for realistic photos, for custom/branded visuals
- Always insert the frame FIRST, then apply — images are fills on frames, not separate nodes
Layout rules for patterns:
- Every frame that arranges children horizontally MUST have
- Every frame that stacks children vertically MUST have
- Sidebar/nav containers are ALWAYS
- Content areas with mixed content are ALWAYS
Each pattern uses only
instances +
tokens.
After each pattern, run the Post-Batch Validation (screenshot + check for overlapping/broken layouts). See
references/screen-patterns.md
.
⛔ REVIEW — Patterns
Call
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
instances and
variable tokens.
Per-screen workflow:
- Call
find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 })
- Insert screen frame at returned position.
- Build layout with component refs. Customize via
U(instanceId+"/descendantId", {...})
- Add domain imagery via .
- Call to verify.
See
references/screen-patterns.md
for domain-specific screen templates.
⛔ REVIEW — Domain Screens (only if Phase 8 was executed)
Call
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:
- Read existing components:
batch_get({ patterns: [{ reusable: true }], readDepth: 2 })
- Read existing tokens:
get_variables({ filePath })
- Plan screens based on user requirements — map each user flow or feature to a screen.
- For each screen:
a. Call
find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 })
U(instanceId+"/descendantId", {...})
⛔ REVIEW — Business Logic Screens
Call
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
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:
,
,
— regardless of whether
already appears (since
doesn't display
in its output — it's considered the default).
Step 3 — Bulk-apply to ALL identified frames.
javascript
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
to those instead.
Step 4 — Verify shadows use hex colors.
Check any frame with
property. If
uses
format, replace with 8-digit hex
.
Step 5 — Screenshot every section to confirm no overlapping elements.
This is safe to run multiple times — setting
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.
- Visual — on Foundations, Components, Patterns (and screens if created). Check alignment, spacing, typography, color, overflow.
- Layout —
snapshot_layout({ problemsOnly: true })
- Token audit —
search_all_unique_properties
- Component audit —
batch_get({ patterns: [{ reusable: true }] })
- Organization audit — Verify no orphan components at document root. All should be under Components section.
- Fix and re-verify — Re-screenshot affected areas after fixes.
- 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
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 . Build the CSS file with all tokens as CSS custom properties:
- v3: with HSL values (space-separated, no wrapper), overrides, font utilities
- v4: , , with hex values, overrides, font utilities
Step 6 — Generate (v3 only). Map all tokens to Tailwind utility names: colors via
, radii, shadows, font sizes, spacing, line heights.
Step 7 — Generate font loading code.
- Next.js: with loader setting , , CSS variables
- Vite+React: tags in 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 prop
- Uses v3 mapped classes () or v4 arbitrary values () based on the chosen version
Step 9 — Generate screen/page TSX files. For each screen design in the .pen file:
- Deep-read the screen frame:
batch_get({ nodeIds: [screenId], readDepth: 10, resolveInstances: true })
- Take a reference screenshot:
get_screenshot({ nodeId: screenId })
- Follow Pencil's Component Implementation Workflow (from Step 4's ):
- Steps 1A-1C: Extract components, map ALL instances with ALL overrides and descendants
- Step 2: Create React components using
get_guidelines("tailwind")
- Step 3: Validate each component with — pixel-perfect match required
- Step 4: Integrate into frame, verify instance count and prop completeness
- Handle screen-level elements: semantic HTML for headings/labels/links, page wrapper, form behavior, icon name conversion, image fills
- Assemble into a complete page file with all imports
- 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
instance.
Rule 2 — Never hardcode values. All colors use
tokens. All fonts use
. All radii use
. All font sizes use
. Raw values only appear in
.
Rule 3 — Prevent overflow. Constrain text with
. Use layout frames. Validate with
snapshot_layout({ problemsOnly: true })
.
Rule 4 — Verify visually. Call
after every major batch. Fix problems immediately.
Rule 5 — Reuse assets. Copy images with
instead of regenerating with
.
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
| # | 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 |
References
Load the relevant file before starting each phase:
references/pencil-mcp-guide.md
references/domain-research-guide.md
references/design-tokens-reference.md
references/foundations-specs.md
references/component-specs.md
references/screen-patterns.md
references/verification-checklist.md
references/code-export-guide.md