pencil basics

Pencil Basics

Provides methods for reading, modifying, and generating designs in .pen files using the Pencil MCP server.

Core Concepts

.pen File Structure

.pen files are an encrypted format that stores design data. They must be accessed only using Pencil MCP tools.

Important: Do not read or write .pen files directly with the Read, Grep, or Write tools. Always use Pencil MCP tools.

Node Types

Type	Purpose	Main Properties
frame	Container, Layout	layout, gap, padding, fill
text	Text Content	content, fontSize, fontWeight, textColor
rectangle	Rectangle Shape	fill, stroke, cornerRadius
ellipse	Circle/Ellipse	fill, stroke
ref	Component Instance	ref (component ID reference)
image	Image Frame	Applied via the G() operation
icon_font	Icon	icon, iconSize

Layout System

Auto Layout Properties:

layout: "horizontal" | "vertical" | "grid"
gap: number (자식 간 간격)
padding: number | [top, right, bottom, left]
alignItems: "start" | "center" | "end" | "stretch"
justifyContent: "start" | "center" | "end" | "space-between"

Size Specification:

width: number | "fill_container" | "hug_contents"
height: number | "fill_container" | "hug_contents"

Essential Tools

1. get_editor_state

Retrieves the current editor state and information about the selected node.

mcp__pencil__get_editor_state(include_schema: boolean)

Always call this before starting design work to check the active file and selection state.

2. batch_get

Searches for nodes or reads them by ID.

mcp__pencil__batch_get(
  filePath: string,
  patterns?: [{ reusable?: boolean, type?: string, name?: string }],
  nodeIds?: string[],
  readDepth?: number,
  searchDepth?: number
)

Usage Examples:

• List of reusable components: patterns: [{ reusable: true }]
• Read a specific node: nodeIds: ["nodeId1", "nodeId2"]
• Search for text nodes: patterns: [{ type: "text" }]

3. batch_design

Executes design modification operations.

mcp__pencil__batch_design(
  filePath: string,
  operations: string  // JavaScript 유사 구문
)

4. get_screenshot

Retrieves a screenshot of a node to visually verify it.

mcp__pencil__get_screenshot(filePath: string, nodeId: string)

Always check the result with a screenshot after design work.

batch_design Operations

Insert (I)

Inserts a new node.

// 기본 삽입
frame1=I("parentId", { type: "frame", layout: "vertical", gap: 16 })
text1=I(frame1, { type: "text", content: "Hello", fontSize: 16 })

// 컴포넌트 인스턴스 삽입
button=I("parentId", { type: "ref", ref: "ButtonComponentId" })

Update (U)

Updates the properties of an existing node.

// 직접 업데이트
U("nodeId", { fill: "#FF0000", padding: 16 })

// 컴포넌트 인스턴스 내부 노드 업데이트
U("instanceId/labelId", { content: "New Label" })

Copy (C)

Copies a node.

// 단순 복사
copy1=C("sourceId", "parentId", { x: 100, y: 100 })

// 속성 오버라이드와 함께 복사
copy2=C("sourceId", "parentId", {
  descendants: {
    "labelId": { content: "Copied Label" }
  }
})

Replace (R)

Replaces a node with a new node.

newNode=R("oldNodeId", { type: "text", content: "Replaced" })

Delete (D)

Deletes a node.

D("nodeId")

Move (M)

Moves a node to a different position.

M("nodeId", "newParentId", 0)  // index는 선택사항

Generate Image (G)

Applies an image to a frame.

// AI 생성 이미지
imgFrame=I("parentId", { type: "frame", width: 400, height: 300 })
G(imgFrame, "ai", "modern office workspace")

// 스톡 이미지
G("existingFrameId", "stock", "nature landscape")

Workflow Patterns

Creating a New Screen

1. get_editor_stateCheck the current state with
2. batch_getCheck available components with
3. get_guidelinesLoad design guidelines with
4. get_style_guide_tags + get_style_guideGet style inspiration with
5. batch_designCompose the screen with
6. get_screenshotVerify the result with

Modifying Components

1. batch_getIdentify the target node structure with
2. batch_designModify properties with the U() operation of
3. get_screenshotCheck the changes with

Troubleshooting Layout Issues

1. snapshot_layoutAnalyze the layout structure with
2. Check for overflow and clipping issues
3. batch_designFix with
4. get_screenshotVerify with

Best Practices

Do

• Verify with get_screenshot after every batch_design
• Execute operations in small units (maximum 25)
• Generate binding names anew each time
• Use instance paths when modifying components (instanceId/childId)

Don't

• Directly accessing .pen files with Read, Write, or Grep
• Running too many operations at once
• Reusing binding names
• Specifying the id attribute directly (auto-generated)

Additional Resources

Reference Files

• references/node-properties.md - Detailed attributes of all node types
• references/layout-examples.md - Layout pattern examples