Pencil Design

Pencil MCP サーバーを使って .pen ファイルのデザイン作業を行うためのワークフローとガイドライン。

重要な制約: 保存は GUI アプリでのみ可能

Pencil MCP では .pen ファイルの保存ができない。 MCP 経由で行った変更はアプリのメモリ上にのみ存在し、ファイルシステムには反映されない。

•batch_design で変更を加えた後、必ずユーザーに Pencil GUI アプリで保存 (Cmd+S) するよう伝えること
•「ファイルに変更が反映されていない」「git diff に出ない」場合は、まず GUI での保存漏れを疑う
•
保存が必要なタイミング:
- •デザイン変更の一区切りごと
- •スクリーンショットを export_nodes で書き出す前
- •git commit する前

やりがちなミス: batch_design で変更 → export_nodes や git 操作 → ファイルが更新されていない → 原因がわからず迷走。これは GUI 保存をしていないだけ。変更後は必ずユーザーに保存を依頼する。

code

get_editor_state(include_schema: true)  -- スキーマと現在の状態を取得

code

batch_get(filePath, patterns/nodeIds)   -- ノード構造を調査
snapshot_layout(filePath)               -- レイアウト状況を確認

code

batch_design(filePath, operations)      -- ノードの挿入・更新・削除

code

get_screenshot(filePath, nodeId)        -- 変更結果を視覚的に確認
snapshot_layout(filePath, problemsOnly: true)  -- レイアウト問題を検出

変更が完了したら、ユーザーに GUI アプリでの保存を依頼する。

コンポーネントのサイズを変更した場合、隣接するコンポーネントの位置も調整が必要。これは自動では行われない。

重要: snapshot_layout(problemsOnly: true) はかぶりを検出しない。 このツールはクリッピング等の問題のみ検出する。トップレベルフレーム同士のかぶりは自分で座標を計算して検証する必要がある。

かぶり検証の手順:

フレーム内にコンテンツを追加してフレームの高さが増えた場合も、同じ検証が必要。 fit_content のフレームは子の追加で自動的に高さが変わるため、追加のたびにかぶりを再確認すること。

例: 高さ 10px のコンポーネント A (Y=0) の下に、マージン 10px を挟んでコンポーネント B (Y=20) がある場合:

同じまたは似たデザインパターンが 2 箇所以上で使われる場合、reusable コンポーネントとして共通化する。

やるべきこと:

やってはいけないこと:

ツール	用途
`get_editor_state`	作業開始時。スキーマ取得、現在の選択状態の確認
`open_document`	.pen ファイルを開く、または新規作成
`batch_get`	ノード構造の調査。パターン検索や ID 指定での読み取り
`batch_design`	ノードの挿入・更新・削除・移動・コピー
`get_screenshot`	変更結果の視覚的確認
`snapshot_layout`	レイアウトの数値確認、問題検出
`find_empty_space_on_canvas`	新規コンポーネントの配置場所を探す
`export_nodes`	PNG/JPEG/PDF への書き出し
`get_guidelines`	デザインガイドラインの取得 (トピック別)
`get_style_guide_tags` / `get_style_guide`	デザインインスピレーション取得
`get_variables` / `set_variables`	テーマ変数の管理
`replace_all_matching_properties`	プロパティの一括置換
`search_all_unique_properties`	使用中プロパティの調査

新規デザインやスクリーン作成時は、適切なガイドラインを取得する:

スタイルの方向性を決める場合は get_style_guide_tags → get_style_guide の順で取得する。