Excalidraw

手描き風の Excalidraw JSON で図を作ります（構成図、フロー図、シーケンス図）。

skill の情報

参考: SKILL.md 全文

Excalidraw Diagram Skill

Excalidraw の標準的な要素 JSON を書き、.excalidraw ファイルとして保存することで図を作ります。できたファイルは excalidraw.com にドラッグ＆ドロップすれば、そのまま表示も編集もできます。アカウントも API キーも描画用のライブラリも要りません。あるのは JSON だけです。

こんなときに使います

構成図、フロー図、シーケンス図、概念図などを .excalidraw ファイルとして作ります。ファイルは excalidraw.com で開けますし、アップロードすれば共有用のリンクにもできます。

進め方

1. この skill を読み込みます（もう済んでいます）
2. 要素の JSON を書きます — Excalidraw の要素オブジェクトを並べた配列です
3. ファイルを保存します — write_file で .excalidraw ファイルを作ります
4. 必要ならアップロードします — terminal から scripts/upload.py を使うと共有用のリンクになります

図を保存する

要素の配列を .excalidraw の標準的な外枠で包み、write_file で保存します。

{
  "type": "excalidraw",
  "version": 2,
  "source": "hermes-agent",
  "elements": [ ...your elements array here... ],
  "appState": {
    "viewBackgroundColor": "#ffffff"
  }
}

保存先はどこでも構いません。たとえば ~/diagrams/my_diagram.excalidraw です。

共有用のリンクを作る

この skill の scripts/ ディレクトリにあるアップロード用スクリプトを、ターミナルから実行します。

python skills/creative/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw

これで excalidraw.com にアップロードされ（アカウントは不要です）、共有用の URL が表示されます。pip の cryptography パッケージが必要です（pip install cryptography）。

要素の書き方一覧

必ず要る項目（すべての要素）

type、id（重複しない文字列）、x、y、width、height

初期値（書かなくて構いません。自動で付きます）

• strokeColor: "#1e1e1e"
• backgroundColor: "transparent"
• fillStyle: "solid"
• strokeWidth: 2
• roughness: 1（手描き風の見た目になります）
• opacity: 100

キャンバスの背景は白です。

要素の種類

長方形:

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }

• 角を丸くするなら roundness: { "type": 3 }
• 中を塗るなら backgroundColor: "#a5d8ff"、fillStyle: "solid"

楕円:

{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }

ひし形:

{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }

文字入りの図形（入れ物として結び付ける） — 図形に結び付いたテキスト要素を作ります。

> 警告: 図形に "label": { "text": "..." } を使ってはいけません。これは Excalidraw の正しい項目ではなく、黙って無視され、中身のない図形ができてしまいます。必ず下の、入れ物として結び付けるやり方を使ってください。

図形の側にはテキストを並べた boundElements が要り、テキストの側には図形を指す containerId が要ります。

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
  "boundElements": [{ "id": "t_r1", "type": "text" }] },
{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "r1", "originalText": "Hello", "autoResize": true }

• 長方形、楕円、ひし形で使えます
• containerId を付けると、Excalidraw が文字を自動で中央に寄せます
• テキストの x / y / width / height はおおよそで構いません。読み込み時に Excalidraw が計算し直します
• originalText は text と同じにします
• fontFamily: 1 は必ず入れてください（Virgil という手描き風の書体です）

文字入りの矢印 — 入れ物として結び付けるやり方は同じです。

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
  "boundElements": [{ "id": "t_a1", "type": "text" }] },
{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "a1", "originalText": "connects", "autoResize": true }

単独のテキスト（見出しや注記だけに使います。入れ物には結び付けません）:

{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
  "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }

• x は左端です。位置 cx を中心にしたいときは x = cx - (text.length * fontSize * 0.5) / 2 とします
• 位置決めを textAlign や width に任せてはいけません

矢印:

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow" }

• points: 要素の x、y からのずれを [dx, dy] で書きます
• endArrowhead: null | "arrow" | "bar" | "dot" | "triangle"
• strokeStyle: "solid"（初期値） | "dashed" | "dotted"

矢印の結び付け（矢印を図形につなぐ）

{
  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
  "points": [[0,0],[150,0]], "endArrowhead": "arrow",
  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
}

fixedPoint の座標は、上が top=[0.5,0]、下が bottom=[0.5,1]、左が left=[0,0.5]、右が right=[1,0.5] です。

描く順番（重なりの順番）

• 配列の順番がそのまま重なりの順番になります（先頭が奥、末尾が手前）
• 少しずつ書き出します。背景の区画 → 図形 → その図形に結び付いたテキスト → その図形から出る矢印 → 次の図形、という順です
• 悪い例: 長方形をすべて書き、次にテキストをすべて書き、最後に矢印をすべて書く
• 良い例: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
• 結び付いたテキスト要素は、必ず入れ物になる図形のすぐ後ろに置きます

大きさの目安

文字の大きさ:

• 本文、ラベル、説明の fontSize は 16 以上にします
• 見出しの fontSize は 20 以上にします
• 補助的な注記に限り fontSize 14 まで下げられます（多用しないでください）
• fontSize を 14 より小さくしてはいけません

要素の大きさ:

• 文字入りの長方形や楕円は、最低でも 120x60 にします
• 要素どうしは最低 20〜30px 空けます
• 小さい要素をたくさん置くより、少なく大きく置くほうがよいです

配色

色の一覧は references/colors.md にあります。早見表は次のとおりです。

コツ

• 図全体で配色をそろえます
• 文字の見やすさがいちばん大事です — 白い背景に薄い灰色は絶対に使わないでください。白地に置く文字の色は #757575 までにします
• 文中に絵文字を使ってはいけません。Excalidraw の書体では表示されません
• 暗い配色の図については references/dark-mode.md を見てください
• もっと大きな例は references/examples.md にあります