Pencil Basics

Pencil の基本

Pencil MCP サーバーを使用して、.pen ファイルを読み取り、編集し、デザインを作成する方法を説明します。

コアコンセプト

.pen ファイルの構造

.pen ファイルは、デザインデータを保存する暗号化された形式です。アクセスには必ず Pencil MCP ツールのみを使用してください。

重要：Read、Grep、Write ツールで .pen ファイルを直接読み書きしないでください。常に Pencil MCP ツールを使用してください。

ノードタイプ

タイプ	用途	主な属性
frame	コンテナー、レイアウト	layout、gap、padding、fill
text	テキストコンテンツ	content、fontSize、fontWeight、textColor
rectangle	四角形	fill、stroke、cornerRadius
ellipse	円／楕円	fill、stroke
ref	コンポーネントインスタンス	ref（コンポーネント ID 参照）
image	画像フレーム	G() オペレーションで適用
icon_font	アイコン	icon、iconSize

レイアウトシステム

Auto Layout 属性：

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

サイズ指定：

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

必須ツール

1. get_editor_state

現在のエディター状態と選択中のノード情報を取得します。

mcp__pencil__get_editor_state(include_schema: boolean)

デザイン作業を始める前に必ず呼び出し、アクティブなファイルと選択状態を確認してください。

2. batch_get

ノードを検索するか、ID で読み取ります。

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

使用例：

• 再利用可能なコンポーネントの一覧：patterns: [{ reusable: true }]
• 特定のノードを読み取る：nodeIds: ["nodeId1", "nodeId2"]
• テキストノードを検索する：patterns: [{ type: "text" }]

3. batch_design

デザイン編集オペレーションを実行します。

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

4. get_screenshot

ノードのスクリーンショットを取得して、視覚的に検証します。

mcp__pencil__get_screenshot(filePath: string, nodeId: string)

デザイン作業の後は必ずスクリーンショットで結果を確認してください。

batch_design オペレーション

Insert (I)

新しいノードを挿入します。

// 기본 삽입
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)

既存のノードの属性を更新します。

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

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

Copy (C)

ノードをコピーします。

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

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

Replace (R)

ノードを新しいノードに置き換えます。

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

Delete (D)

ノードを削除します。

D("nodeId")

Move (M)

ノードを別の位置に移動します。

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

Generate Image (G)

フレームに画像を適用します。

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

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

ワークフローパターン

新しい画面の作成

1. get_editor_stateで現在の状態を確認
2. batch_getで利用可能なコンポーネントを確認
3. get_guidelinesでデザインガイドラインを読み込む
4. get_style_guide_tags + get_style_guideでスタイルの参考情報を得る
5. batch_designで画面を構成
6. get_screenshotで結果を検証

コンポーネントの編集

1. batch_getで対象ノードの構造を把握
2. batch_designのU()オペレーションで属性を編集
3. get_screenshotで変更を確認

レイアウトの問題解決

1. snapshot_layoutでレイアウト構造を分析
2. オーバーフローやクリッピングの問題を確認
3. batch_designで編集
4. get_screenshotで検証

ベストプラクティス

推奨事項

• batch_designのたびにget_screenshotで検証する
• 小さな単位でオペレーションを実行する（最大25件）
• バインディング名は毎回新しく作成する
• コンポーネントの編集にはインスタンスパスを使用する（instanceId/childId）

禁止事項

• Read、Write、Grepで.penファイルに直接アクセスする
• 一度に多くのオペレーションを実行する
• バインディング名を再利用する
• id 属性を直接指定する（自動生成されます）

追加リソース

リファレンスファイル

• references/node-properties.md - すべてのノードタイプの詳細な属性
• references/layout-examples.md - レイアウトパターンの例