excalidraw

Excalidraw 図表スキル

標準的な Excalidraw 要素 JSON を記述し、.excalidraw ファイルとして保存することで図表を作成します。これらのファイルは excalidraw.com にドラッグ＆ドロップすると、表示や編集ができます。アカウントも API キーもレンダリングライブラリも必要ありません。JSON だけで作成できます。

使用する場面

アーキテクチャ図、フローチャート、シーケンス図、概念マップなどの .excalidraw ファイルを生成します。ファイルは excalidraw.com で開くか、アップロードして共有可能なリンクを作成できます。

ワークフロー

1. このスキルを読み込む（すでに読み込まれています）
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 など、任意のパスに保存します。

共有可能なリンクのためのアップロード

terminal 経由でアップロードスクリプト（このスキルの scripts/ ディレクトリ内）を実行します。

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

これにより excalidraw.com にアップロードされ（アカウントは不要です）、共有可能な URL が出力されます。cryptography pip パッケージが必要です（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]

描画順序（z-order）

• 配列の順序が z-order になります（最初が背面、最後が前面）
• 背景ゾーン → 図形 → その図形にバインドしたテキスト → その図形の矢印 → 次の図形、の順に段階的に出力します
• 悪い例： すべての長方形、次にすべてのテキスト、最後にすべての矢印
• 良い例： 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を参照してください。クイックリファレンス：

用途	塗りつぶし色	Hex
主要／入力	ライトブルー	#a5d8ff
成功／出力	ライトグリーン	#b2f2bb
警告／外部	ライトオレンジ	#ffd8a8
処理／特殊	ライトパープル	#d0bfff
エラー／重大	ライトレッド	#ffc9c9
メモ／判断	ライトイエロー	#fff3bf
ストレージ／データ	ライトティール	#c3fae8

ヒント

• 図全体でカラーパレットを一貫して使用します
• テキストのコントラストは非常に重要です――白い背景に薄いグレーを使用しないでください。白地で使用するテキストの最小色は#757575です
• テキストに絵文字を使用しないでください。Excalidrawのフォントでは表示されません
• ダークモードの図については、references/dark-mode.mdを参照してください
• 大きな例については、references/examples.mdを参照してください