OpenPencil デザイン
PenNode JSONツリーを記述することで、プロダクションレベルのベクターデザインを生成します。op CLIまたはMCPツールを使用して、OpenPencilキャンバス上のノードを作成、読み取り、更新、削除します。
使用するタイミング
.opファイル内のUIデザインを作成または変更する場合opCLIを使用してデザイン操作をスクリプト化する場合- MCPツール(
batch_design、insert_node、design_skeleton)を介してデザインする場合 - PenNodeスキーマ、ロール、レイアウトルールのリファレンスが必要な場合
クイックリファレンス — op CLI
# アプリケーション制御
op start [--desktop|--web] # アプリを起動
op stop # 実行中のインスタンスを停止
op status # 実行中か確認
# ドキュメント
op open [file.op] # ファイルを開く、またはライブキャンバスに接続
op save <file.op> # 現在のドキュメントを保存
op get [--depth N] [--pretty] # ドキュメントツリーを取得
op selection [--depth N] # 現在のキャンバス選択範囲を取得
op read-nodes [id...] [--depth N] [--vars] # ノードサブツリーを読み取る(オプションで変数解決)
op layout [--parent P] [--depth N] # 計算された位置を含むレイアウトツリーのスナップショット
op find-space [--direction D] [--width N] [--height N] # キャンバス上の空きスペースを検索
# ノード操作
op insert '<json>' [--parent P] # ノードを挿入(--index N, --post-process)
op update <id> '<json>' # ノードを更新
op delete <id> # ノードを削除
op move <id> <parent> [index] # ノードを移動
op copy <id> <parent> # ノードをディープコピー
op replace <id> '<json>' # ノードを置き換え
# バッチデザイン
op design '<dsl>' # バッチデザインDSL(インライン、@file、またはstdin)[--canvas-width N]
op design @ui.js # サンドボックス化されたJSスクリプト:I(parent, obj) + ループ(.js/.mjsは--scriptを意味します)
op design '<js>' --script # 同上、インライン/stdin(フラグはペイロードの後に続く必要があります)
# レイヤードワークフロー
op design:skeleton '<json>' # セクション構造を作成
op design:content <id> '<json>' # セクションコンテンツを設定
op design:refine --root-id <id> # 検証+自動修正(アイコンを解決)[--canvas-width N]
# インポート
op import:svg <file.svg> [--parent P] # SVGを編集可能なノードとしてインポート
op import:figma <file.fig> [--out out.op] # Figma .fig を .op ドキュメントに変換
# ページ
op page list # すべてのページを一覧表示
op page add [--name N] # 新しいページを追加
op page remove <id> # ページを削除
op page rename <id> '<name>' # ページ名を変更
op page reorder <id> <index> # ページを位置に移動
op page duplicate <id> # 新しいIDでページを複製
# 変数とテーマ
op vars / op vars:set '<json>' # 変数(--replaceですべて置き換え)
op themes / op themes:set '<json>' # テーマ(--replaceですべて置き換え)
op theme:save <file.optheme> # 現在のテーマをプリセットファイルとして保存
op theme:load <file.optheme> # テーマプリセットファイルを読み込む
op theme:list <directory> # ディレクトリ内の.opthemeプリセットを一覧表示
# コード生成パイプライン
op codegen:plan '<json>' # コード生成計画を送信(フレームワーク、rootIds、オプション)
op codegen:submit '<json>' # ノードのコードチャンクを送信
op codegen:assemble [--framework F] # 送信されたすべてのチャンクを最終出力にアセンブル
op codegen:clean # コード生成状態をクリア
グローバルフラグ:--file <path>、--page <id>、--pretty。入力:インライン文字列、@filepath、または-(stdin)。
デザインの構築 — 3つのアプローチ
アプローチ1: op insert(推奨)
デザインを構築する最も信頼性の高い方法です。--parent を使用して親ノードを指定します。返された nodeId をキャプチャして後で参照します。アイコンを解決しレイアウトを検証するために、必ず design:refine で終了してください。
# ルートフレームを作成し、そのIDをキャプチャ
ROOT=$(op insert '{"type":"frame","name":"Page","width":375,"height":812,"layout":"vertical"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")
# --parent を使用して子を挿入
op insert --parent "$ROOT" '{"type":"text","content":"Hello","fontSize":28,"fontWeight":700}'
# 後処理:アイコンを解決、レイアウトを検証
op design:refine --root-id "$ROOT"
アプローチ2: バッチデザインDSL
1行に1つの操作。name= で結果をバインドし、後で参照します。シンプルでフラットな構造に最適です。
制限: DSLパーサーは、深くネストされたJSON(例:ネストされたオブジェクトを持つ
children配列、または複数レベルの配列ネスト)を処理できません。各I()呼び出しは 単一レベルのネスト に制限してください。子を持つ複雑なノードの場合は、親と子に別々のI()呼び出しを使用するか、op insert --parentを使用します。
root=I(null, { "type": "frame", "width": 1200, "layout": "vertical" })
nav=I(root, { "type": "frame", "role": "navbar", "height": 72 })
U(nav, { "fill": [{"type": "solid", "color": "#FFFFFF"}] })
card2=C(card1, grid, { "name": "Card 2" })
M(sidebar, main, 0)
D(old_section)
R(old_btn, { "type": "rectangle", "role": "button" })
| 演算 | 構文 | アクション |
|---|---|---|
I | name=I(parent, { node }) | 挿入 |
U | U(ref, { updates }) | 更新 |
C | name=C(source, parent, { overrides }) | コピー |
R | name=R(ref, { node }) | 置き換え |
M | M(ref, parent, index?) | 移動 |
D | D(ref) | 削除 |
G | name=G(parent, "search", "query") | 検索で画像を生成 |
DSL安全パターン — 常に親と子を個別に挿入します:
btn=I(form, {"type":"rectangle","role":"button","width":"fill_container","height":50,"cornerRadius":12,"fill":[{"type":"solid","color":"#111111"}],"layout":"horizontal","justifyContent":"center","alignItems":"center"})
I(btn, {"type":"text","content":"Submit","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]})
アプローチ3: スクリプトモード(ループとデータ駆動 — 繰り返し構造に推奨)
op design @ui.js # .js / .mjs ファイルはスクリプトモードを意味します
op design '<jsコード>' --script # インラインまたはstdin; --script はペイロードの後に続く必要があります
MCP経由:script 引数を指定して batch_design を呼び出します(呼び出しごとに nodes_json | operations | script のいずれか1つだけ)。これはOpenPencilの内部デザインエージェントが使用するのと同じプロトコルです。同じ契約に従ってください:
デザインを構築するJavaScriptプログラム(散文やマークダウンフェンスは不要)を記述し、グローバル関数 I(parent, node) を呼び出します。
const id = I(parent, { ...node... }); // ノードを挿入し、そのID(文字列)を返します
parent はルートフレームの場合はnull、それ以外の場合は以前の I(...) 呼び出しによって返されたIDです。ノードは、I(X, {...}) を呼び出した場合にのみ X の子になります。
I(...) が利用可能な唯一の関数です — console や他のビルダーはありません。console.log やヘルパーを呼び出さないでください。単に I(...) を呼び出してください。スクリプトモードは挿入のみです。更新/移動/削除にはDSL演算(アプローチ2)を使用します。
実際のJavaScriptを使用 — const/let、データの配列、そして for...of / .forEach ループ — を使用して、データ配列をループすることで繰り返し構造(テーブル行、ナビゲーション項目、カード、リスト項目)を生成します。ほぼ同一の I(...) 呼び出しをコピーペーストするよりも、ループを優先します。
各ノードオブジェクトは type("frame"/"text"/"rectangle"/"ellipse"/"path"/"icon_font")で始まり、キャメルケースのプロパティ(cornerRadius、fontSize、fontWeight、justifyContent、alignItems、clipContent)を使用します。レイアウトフレーム内の子に x/y を設定しないでください。
例:
const sec = I(null, {type:"frame", name:"Clients", layout:"vertical", width:"fill_container", gap:0});
const tbl = I(sec, {type:"frame", layout:"vertical", width:"fill_container"});
const rows = [{name:"Alice Chen", status:"Active"}, {name:"Bob Ito", status:"VIP"}];
for (const r of rows) {
const row = I(tbl, {type:"frame", layout:"horizontal", width:"fill_container", padding:[12,16]});
const c1 = I(row, {type:"frame", width:"fill_container"}); I(c1, {type:"text", content:r.name});
const c2 = I(row, {type:"frame", width:"fill_container"}); I(c2, {type:"text", content:r.status});
}
すべての行/カード/項目を現実的な値で生成します。JavaScriptプログラムのみを出力します。
CLI/MCPに関する注意点:
- ネストされた
children配列はここでは安全です — エンジンは各オブジェクトを完全な単一行JSONにシリアライズするため、DSLの単一レベルネスト制限は適用されません。ただし、親バインディングが必要な場合は、とにかく別々のI()呼び出しを推奨します。 - ノードIDは挿入時に再マッピングされます — 呼び出し後に作成された
"id"を参照しないでください。返されたバインディングのみが意味を持ち、このスクリプト内でのみ有効です。 - 制限: ソース256 KiB、4096回の挿入、8 MiBの記録出力、2秒のCPU、64 MiBのメモリ。途中で切り詰められたスクリプトはベストエフォートで修復されます(完全なプレフィックスは引き続き実行されます)。
厳格なJSONルール
PenNode JSON(op insert、op design、batch_design、insert_node を介して)を出力する場合、厳密に有効なJSONを生成する必要があります。解析を壊す一般的な間違い:
- すべてのプロパティにはキーと値の両方が必要です。キー名なしで
": 50や: 50を出力しないでください。これは、切り詰め/再フォーマット時に頻繁に発生します — 再確認してください。 - すべてのキーは、ダブルクォートで囲まれた空でない文字列である必要があります。
fillは常に配列です:"fill": [{"type": "solid", "color": "#hex"}]。"fill": "#hex"のような省略形も機能しますが、配列形式が正規の形状です。strokeはfill配列を持つオブジェクトです:"stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}。"stroke": {"thickness": 1, "color": "#hex"}や"stroke": "#hex"は絶対に使用しないでください(パーサーはこれらを自動変換しますが、正しい形状が推奨されます)。}または]の前に末尾のカンマを付けないでください。- JSON内にコメントを付けないでください(
//や/* */)。 - ストレートな二重引用符
"を使用し、スマート引用符やカーリー引用符は使用しないでください。 - テキストには
textではなくcontentを使用します:{"type": "text", "content": "Hello"}。 - アイコンには
iconNameやiconではなくiconFontNameを使用します:{"type": "icon_font", "iconFontName": "lock"}。 - JSONを最終決定する前に、すべてのキーに値があり、すべての値にキーがあり、すべてのブラケットが一致していることを頭の中で確認してください。
PenNodeスキーマ
共通プロパティ
{
"type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
"name": "表示名",
"role": "セマンティックロール",
"x": 0, "y": 0,
"rotation": 0, "opacity": 1, "visible": true
}
コンテナプロパティ(frame, rectangle, group, ellipse)
{
"width": 400, // 数値 | "fill_container" | "fit_content"
"height": 300,
"layout": "vertical", // "none" | "vertical" | "horizontal"
"gap": 16,
"padding": [16, 24], // 数値 | [v, h] | [top, right, bottom, left]
"justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
"alignItems": "center", // "start" | "center" | "end"
"clipContent": true,
"cornerRadius": 12, // 数値 | [tl, tr, br, bl]
"fill": [{ "type": "solid", "color": "#FFFFFF" }],
"stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }], "align": "inside", "dashPattern": [5, 3] },
"effects": [{ "type": "shadow", "offsetX": 0, "offsetY": 4, "blur": 12, "spread": 0, "color": "rgba(0,0,0,0.08)" }],
"children": []
}
テキスト
{
"type": "text",
"content": "こんにちは", // 文字列 または StyledTextSegment[]
"fontSize": 16, "fontFamily": "Inter", "fontWeight": 600,
"textAlign": "center", // "left" | "center" | "right"
"textGrowth": "fixed-width", // "auto" | "fixed-width" | "fixed-width-height"
"lineHeight": 1.5, "letterSpacing": 0,
"fill": [{ "type": "solid", "color": "#111111" }]
}
リッチテキスト:"content": [{ "text": "太字 ", "fontWeight": "bold" }, { "text": "標準" }]
アイコン — 2つのオプション
オプションA: icon_font(推奨 — 直接レンダリング、後処理不要)
{ "type": "icon_font", "name": "ロックアイコン", "iconFontName": "lock",
"width": 20, "height": 20,
"fill": [{ "type": "solid", "color": "#6B7280" }] }
フィールドは iconFontName です(iconName ではありません、icon でもありません)。 値は小文字のケバブケースのLucide名です:mail、lock、eye、eye-off、chrome、apple、message-circle、x、arrow-right、search、heart、star、check、plus、bell、home、user、settings、chevron-right、download、globe、layers、zap、shield、play。
すべてのコンテキストで機能します:CLI、MCPツール、または直接 .op ファイル — design:refine は必要ありません。
オプションB: path(後処理が必要)
{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
PascalCase + "Icon" サフィックス。後処理中にLucideセットから自動解決されます。
パスアイコンは後処理が必要です。 パスノードを挿入した後、
op design:refine --root-id <id>を実行するか、op insert --post-processを使用します。これがないと、パスアイコンは視覚的にレンダリングされません。スタンドアロンのMCPサーバー(ACPエージェントが使用)にはフック実装が登録されていないため、パスアイコンはそこで解決されません — MCPコンテキストではicon_fontを推奨します。
画像
{ "type": "image", "src": "https://example.com/photo.jpg", "width": 400, "height": 300,
"objectFit": "crop", "cornerRadius": 12 }
AI画像プレースホルダー(design:refine によって解決される):
{ "type": "image", "width": 400, "height": 300,
"imagePrompt": "自然光が差し込むモダンなオフィスワークスペース",
"imageSearchQuery": "modern office workspace" }
画像調整(すべて-100から100):exposure、contrast、saturation、temperature、tint、highlights、shadows。
ポリゴン
{ "type": "polygon", "polygonCount": 6, "width": 80, "height": 80, "cornerRadius": 4,
"fill": [{ "type": "solid", "color": "#6366F1" }] }
アイコンフォント
{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
"fill": [{ "type": "solid", "color": "#111111" }] }
線
{ "type": "line", "x2": 200, "y2": 0,
"stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }
塗りつぶしタイプ
{ "type": "solid", "color": "#3B82F6" }
{ "type": "linear
...