Pencil Design

Create and manipulate .pen design files using Pencil MCP tools.

Workflow

1. Orientation

get_editor_state     → Check active file and selection
get_guidelines       → Load topic-specific rules (landing-page, design-system, table, code, tailwind)
batch_get            → Read file structure or find components

2. Design (if creating from scratch)

get_style_guide_tags → Browse available visual styles
get_style_guide      → Load style guide for inspiration
open_document        → Create new file if needed

3. Build

batch_design         → Insert, update, copy, replace, move, delete nodes (max 25 ops/call)
get_screenshot       → Verify visual output after changes
snapshot_layout      → Debug layout issues or find clipping problems

4. Refine

get_variables        → Read design tokens and themes
set_variables        → Update tokens for consistent styling
replace_all_matching_properties → Bulk property updates

---

Quick Reference

Element Types

Type	Purpose	Key Properties
frame	Container/layout	layout, gap, padding, children, reusable
text	Typography	content, fontFamily, fontSize, fontWeight
rectangle	Shape	width, height, fill, cornerRadius
ref	Component instance	ref (source ID), descendants (overrides)
icon_font	Icon	iconFontName, iconFontFamily ("lucide")
path	Vector	geometry (SVG path data)

Layout

Property	Values
layout	"none" (absolute), "horizontal", "vertical"
justifyContent	start, center, end, space_between
alignItems	start, center, end, stretch
width/height	360, "fill_container", "fill_container(360)", "fit_content"
padding	16, [12, 24], [8, 16, 8, 16]

Tokens

Prefix: $--

Category	Examples
Colors	$--primary, $--foreground, $--background, $--border
Semantic	$--color-success, $--color-warning, $--color-error
Typography	$--font-primary, $--font-secondary
Radii	$--radius-none, $--radius-m, $--radius-pill

---

Operations (batch_design)

Operations use JavaScript-like syntax. Every Insert/Copy/Replace needs a binding.

Op	Syntax	Use
I	btn=I(parent, {type: "frame", ...})	Insert node
U	U(path, {content: "New"})	Update properties
C	copy=C(sourceId, parent, {...})	Copy node
R	new=R(path, {type: "text", ...})	Replace node
M	M(nodeId, newParent, index?)	Move node
D	D(nodeId)	Delete node
G	G(nodeId, "stock", "office")	Apply image fill

Component Instances

// Insert instance and override text
card=I(container, {type: "ref", ref: "CardComp"})
U(card+"/titleText", {content: "New Title"})

// Replace slot content
newContent=R(card+"/slot", {type: "text", content: "Custom"})

Critical Rules

1. IDs auto-generate — never set id in node data
2. Bindings required — every I/C/R must have name=...
3. Max 25 ops — split larger designs across calls
4. Copy descendants — use descendants property, not separate U() calls
5. Verify visually — call get_screenshot after modifications

---

Reference Files

File	When to Read
mcp-operations.md	Detailed operation syntax, examples, and edge cases
patterns.md	Element creation examples, styling patterns, theming
schema.json	Authoritative property definitions for validation