excalidraw-diagrams

Excalidraw 図の作成

Excalidraw 図を作成するときは、次の点を確認してください。

• 適切な間隔でレイアウトを作成します
• 色、フォント、図形を一貫性のある論理的な方法で使用します
• テキストは、（意図する場合を除き）独立したテキスト要素ではなく、図形の中に正しく追加します
• 矢印や線は図形に正しく固定・接続し、浮いた状態にならないようにします。オブジェクトを移動しても、接続が維持されます
• Excalidraw 図の内容をファイルに保存し、ファイルパスへのリンクを提示します
• 各セッションで最初に create_view を呼び出す前に read_me を呼び出します。色のパレット、カメラサイズ、レイアウトのルール、要素形式のリファレンスを確認できます。
• ユーザーから Excalidraw 図の作成を依頼されたものの、Excalidraw MCP が有効になっていない場合は、追加を依頼してください。HTTP MCP URL https://excalidraw-mcp-app.vercel.app/mcp を使って設定できます。MCP のドキュメントはこちらで確認できます：https://github.com/excalidraw/excalidraw-mcp

ワークフローを選ぶ

ユーザーのニーズに合わせて、いずれかを選択してください。両方を使うことを既定にしないでください。

インラインプレビューのみ（create_view）

図が会話内でのみ使用され、ユーザーがチャットで見たいだけでファイルを必要としない場合に使います。

• 図形に label を指定して create_view を使います（ここでは正常に動作します）
• cameraUpdate を使ってアニメーションを付け、注目を誘導します
• ファイル出力は不要です

ファイル出力のみ（Python スクリプト）

ユーザーが開いたり、共有、編集、保存したりできる .excalidraw ファイルを必要とする場合に使います。create_view は一切使いません。

• scripts/generate_excalidraw.py を使ってファイルを生成します（以下を参照）
• ファイルパスをユーザーに提示します
• ファイルは excalidraw.com、Excalidraw デスクトップアプリ、または Excalidraw 拡張機能をインストールした VS Code にドラッグして開けます

両方（インラインプレビュー＋ファイル）

ユーザーがチャットで図を見たいだけでなく、ファイルも保存したい場合に使います。注：それぞれ異なる要素形式で個別に作成します。両者をつなぐデータブリッジはありません。図の構造は概念上は一度定義しますが、描画は二度行います。

• インラインプレビューには label を指定して create_view を使います
• .excalidraw ファイルには labeled_rect を使った Python スクリプトを使います

重要：テキストはエクスポート後に保持されません

図形の label プロパティは create_view 専用の簡易機能です。次の場合には機能しません。

• export_to_excalidraw へのアップロード（図形は描画されますが、テキストは表示されません）
• create_view のチェックポイントデータから作成した .excalidraw ファイル

共有する図には export_to_excalidraw を使わないでください。テキストがすべて気付かないうちに削除されるバグがあるようです。

ネイティブ Excalidraw では、図形内のテキストはリンクされた2つの要素として表されます。

1. 図形："boundElements": [{"id": "text-id", "type": "text"}]
2. テキスト："containerId": "shape-id"、"textAlign": "center"、"verticalAlign": "middle"

テキスト要素には、label の省略表記に含まれない次のフィールドが必要です：fontFamily（1）、width、height、originalText、lineHeight（1.25）、autoResize（true）。

.excalidraw ファイル内のすべての要素には、次のフィールドも必要です：angle、seed、version、versionNonce、isDeleted、groupIds、frameId、updated、link、locked。

この JSON を手書きすると間違いやすいため、代わりに Python スクリプトを使ってください。

Python スクリプト：scripts/generate_excalidraw.py

必要なフィールドをすべて含むネイティブの .excalidraw ファイルを生成します。bash のヒアドキュメント内で直接使用することも、ライブラリとしてインポートすることもできます。

主な関数：

関数	戻り値	用途
labeled_rect(id, x, y, w, h, bg, stroke, label, ...)	[rect, text]	中央揃えの境界付きテキストを含む図形（すべてのバインドとフィールド生成を処理します）
rect(id, x, y, w, h, bg, stroke, ...)	要素	テキストなしの長方形
txt(id, x, y, w, h, text, size, ...)	要素	独立またはバインドされたテキスト
bound_arrow(id, elements, start_id, start_point, end_id, end_point, ...)	要素	2つの図形にアンカーされた矢印（図形の boundElements を変更します）
arrow(id, x, y, w, h, points, ...)	要素	バインドされていない／浮動する矢印（図形を接続する場合は、代わりに bound_arrow を使用してください）
ellipse(...) / diamond(...)	要素	その他の図形タイプ
write_scene(elements, path)	ファイルを書き込みます	シーン構造でラップして保存します

例：

python3 << 'PYEOF'
import sys, random
sys.path.insert(0, "/Users/samm/.claude/skills/excalidraw-diagrams/scripts")
from generate_excalidraw import *

random.seed(42)
elements = []
elements.append(txt("t1", 200, 10, 300, 30, "My Diagram", 24))
elements.extend(labeled_rect("a", 50, 60, 200, 70, "#a5d8ff", "#4a9eed", "Step One"))
elements.extend(labeled_rect("b", 350, 60, 200, 70, "#b2f2bb", "#22c55e", "Step Two"))
elements.append(bound_arrow("a1", elements, "a", [1, 0.5], "b", [0, 0.5]))
write_scene(elements, "/path/to/output.excalidraw")
PYEOF

labeled_rect の簡易関数を使わない図形では、rect(..., bound_text="tid") と txt(..., container="rid", align="center", valign="middle") を組み合わせてください。

矢印のアンカー設定

デフォルトでは、矢印は図形に固定されません。図形を移動しても、矢印はその場に残ります。矢印を図形に固定するには、arrow の代わりに bound_arrow を使用してください。双方向のバインドを自動的に処理します（矢印は図形を参照し、図形は boundElements に矢印を記載します）。

図形上の接続点に指定する fixedPoint の値は、上=[0.5, 0]、右=[1, 0.5]、下=[0.5, 1]、左=[0, 0.5] です。図形の左上隅が 0,0、右下隅が 1,1 となる任意の [fx, fy] 値を指定できます。

重要：

• bound_arrow は図形を検索して、その boundElements を変更するため、呼び出す前に図形が elements 内に存在している必要があります。
• 接続する図形の間隔は最低 60px 必要です。 Excalidraw は描画時にバインドされた矢印のジオメトリを再計算します。図形同士が近すぎる（間隔が約 60px 未満）と、矢印が重なり、図形の辺で接続せずにボックスを通り抜けてしまいます。このしきい値に違反すると、スクリプトが警告します。十分な間隔を確保してレイアウトを計画してください。
• 接続可能な図形と重なる大きな背景の長方形は避けてください。 バインドされた矢印の端点が、接続先の図形と重なる背景の長方形の内側にあると、Excalidraw のバインド解決が誤作動することがあります。セクションの背景が必要な場合は、すべてのバインドされた矢印を追加した後に配置するか、独立したテキストラベルと色分けしたボックスを使用してください。

インラインの create_view ワークフローでは、矢印要素に startBinding／endBinding と fixedPoint を直接指定してください。

プライバシー

図に機密性の高い情報（詳細なネットワーク図や個人を特定できる情報など）が含まれる可能性があり、ユーザーから図を excalidraw.com にアップロードするよう求められた場合は、図が一般に公開されることを事前に警告し、続行してよいか確認してください。