excalidraw-studio

Excalidraw Studio

自然言語による説明から、Excalidraw 形式の図を生成します。Excalidraw（Web、VS Code 拡張機能、または Obsidian プラグイン）で直接開ける .excalidraw JSON ファイルを出力します。

ワークフロー

UNDERSTAND → CHOOSE TYPE → EXTRACT → GENERATE → SAVE

ステップ 1：リクエストを理解する

ユーザーの説明を分析し、次の項目を判断します。

1. 図の種類 — 以下の判断表を使用します
2. 主要な要素 — エンティティ、手順、概念、アクター
3. 関係性 — フローの方向、接続、階層
4. 複雑さ — 要素の数（明瞭さを保つため、20 未満を目標とします）

ステップ 2：図の種類とビジュアルモードを選ぶ

図の種類：

ユーザーの意図	図の種類	キーワード
プロセスフロー、手順	フローチャート	"workflow", "process", "steps"
接続、依存関係	関係図	"relationship", "connections", "dependencies"
概念の階層	マインドマップ	"mind map", "concepts", "breakdown"
システム設計	アーキテクチャ図	"architecture", "system", "components"
データの移動	データフロー図（DFD）	"data flow", "data processing"
部門横断的なプロセス	スイムレーン図	"business process", "swimlane", "actors"
オブジェクト指向設計	クラス図	"class", "inheritance", "OOP"
インタラクションのシーケンス	シーケンス図	"sequence", "interaction", "messages"
データベース設計	ER 図	"database", "entity", "data model"

ビジュアルモード — あらかじめ決定し、すべての要素に一貫して適用します。

モード	roughness	fontFamily	使用する場面
スケッチ	1	5	デフォルト — インフォーマルで親しみやすく、Excalidraw らしいスタイル
クリーン	0	2	経営層向けプレゼンテーション、正式な仕様書
ミックス	zones: 0, shapes: 1	5	アーキテクチャ図（構造的なゾーンとスケッチ風の図形）

ステップ 3：構造化された情報を抽出する

図の種類に基づいて主要な構成要素を抽出します。それぞれの種類について、次の項目を特定します。

• ノード／エンティティ — ボックスや図形にするものは何ですか？
• 接続 — 何と何が、どのようなラベルでつながりますか？
• 階層 — 何が何を含み、何が何より先に来ますか？
• 判断ポイント — フローが分岐する箇所はどこですか？

図の種類ごとの詳細な抽出ガイドラインについては、references/element-types.md を読んでください。

ステップ 4：Excalidraw JSON を生成する

重要：最初の図を生成する前に、references/excalidraw-schema.md を読んでください。 正しい要素形式、テキストコンテナーのモデル、バインディングシステムについて説明しています。

生成に関する主なルール：

1. 図形内のテキスト — 図形に boundElements を使用し、containerId を持つ別のテキスト要素を使用してください。label の省略記法は使用しないでください。

   [
     {
       "id": "step-1",
       "type": "rectangle",
       "x": 100, "y": 100, "width": 200, "height": 80,
       "boundElements": [{ "type": "text", "id": "text-step-1" }]
     },
     {
       "id": "text-step-1",
       "type": "text",
       "x": 130, "y": 128, "width": 140, "height": 24,
       "text": "My Step", "originalText": "My Step",
       "fontSize": 20, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "step-1", "lineHeight": 1.25, "roundness": null
     }
   ]
   

2. 矢印のラベル — 同様に、boundElements と containerId を持つ別のテキスト要素を使用してください。矢印に label の省略記法は使用しないでください。

   [
     {
       "id": "arrow-1",
       "type": "arrow",
       "x": 100, "y": 150,
       "points": [[0, 0], [200, 0]],
       "boundElements": [{ "type": "text", "id": "text-arrow-1" }]
     },
     {
       "id": "text-arrow-1",
       "type": "text",
       "x": 160, "y": 132, "width": 80, "height": 18,
       "text": "sends data", "originalText": "sends data",
       "fontSize": 14, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "arrow-1", "lineHeight": 1.25, "roundness": null
     }
   ]
   

3. 矢印のバインディング — start／end ではなく、startBinding／endBinding を使用してください。接続する図形の boundElements には矢印を指定する必要があります。

   {
     "id": "shape-1",
     "boundElements": [
       { "type": "text", "id": "text-shape-1" },
       { "type": "arrow", "id": "arrow-1" }
     ]
   }
   

   {
     "id": "arrow-1",
     "type": "arrow",
     "startBinding": { "elementId": "shape-1", "focus": 0, "gap": 1 },
     "endBinding": { "elementId": "shape-2", "focus": 0, "gap": 1 }
   }
   

4. Z インデックスの要素順序 — 図形を最初に、矢印を次に、テキスト要素を最後に必ず宣言してください。これにより、テキストが最前面に表示され、矢印やほかの図形に隠されることがありません。

5. 配置 — グリッドに沿った座標（gridSize: 20 の場合は 20px の倍数）を使用してください。要素間には水平方向に 200～300px、垂直方向に 100～150px の間隔を空けてください。

6. 一意の ID — すべての要素に一意の id が必要です。"step-1"、"decision-valid"、"arrow-1-to-2"、"text-step-1" のような説明的な ID を使用してください。

7. 色 — 一貫したパレットを使用してください。

   役割	色	16 進数
   主要なエンティティ	ライトブルー	#a5d8ff
   処理ステップ	ライトグリーン	#b2f2bb
   重要／中心	イエロー	#ffd43b
   警告／エラー	ライトレッド	#ffc9c9
   二次的な要素	シアン	#96f2d7
   デフォルトの線	ダーク	#1e1e1e

ステップ 5：保存して提示する

1. <descriptive-name>.excalidraw として保存します

2. 概要を提示します。

   Created: user-workflow.excalidraw
   Type: Flowchart
   Elements: 7 shapes, 6 arrows, 1 title
   Total: 14 elements
   
   To view:
   1. Visit https://excalidraw.com → Open → drag and drop the file
   2. Or use the Excalidraw VS Code extension
   3. Or open in Obsidian with the Excalidraw plugin
   

テンプレート

すぐに使えるよう、あらかじめ作成されたテンプレートが assets/ に用意されています。図の種類が一致する場合は、これらを使用してください。正しい構造とスタイルが備わっています。

テンプレート	ファイル
フローチャート	assets/flowchart-template.json
関係図	assets/relationship-template.json
マインドマップ	assets/mindmap-template.json
データフロー図（DFD）	assets/data-flow-diagram-template.json
スイムレーン	assets/business-flow-swimlane-template.json
クラス図	assets/class-diagram-template.json
シーケンス図	assets/sequence-diagram-template.json
ER 図	assets/er-diagram-template.json

その種類の図を初めて作成する際は、テンプレートを読んでください。テンプレートの構造をベースとして、ユーザーの要望に合わせて要素を変更します。

アイコンライブラリ

サービスアイコン（AWS、GCP、Azure など）を含むプロフェッショナルなアーキテクチャ図を作成するために、アイコンライブラリを設定できます。次の場合は references/icon-libraries.md を読んでください。

• ユーザーが AWS／クラウドアーキテクチャ図を依頼した場合
• ユーザーが特定のサービスアイコンを使いたいと述べた場合
• アイコンライブラリが利用可能か確認する必要がある場合

ベストプラクティス

要素数

図の種類	推奨数	最大数
フローチャートのステップ	3～10	15
関係図のエンティティ	3～8	12
マインドマップの枝	4～6	8
枝ごとのサブトピック	2～4	6

ユーザーの依頼が最大数を超える場合は、複数の図に分けることを提案してください。

「ご依頼には 15 個のコンポーネントが含まれています。分かりやすくするため、（1）主要コンポーネント 6 個を含む高レベルのアーキテクチャ図、（2）各サブシステムの詳細なサブ図に分けることをおすすめします。まず高レベルの図から始めましょうか？」

レイアウト

• フローの方向：プロセスは左から右へ、階層は上から下へ
• 間隔：要素間の水平間隔は200～300px、垂直間隔は100～150px
• グリッドへの整列：きれいに整列するよう、20pxの倍数の位置に配置します
• 余白：キャンバスの端から最低50px
• テキストサイズ：タイトルは28～36px、ラベルは18～22px、注釈は14～16px
• フォント：手描き風の一貫性を保つため、fontFamily: 5（Excalifont）を使用します。5がサポートされていない場合は、1（Virgil）を使用します。
• 背景ゾーン：アーキテクチャ図では、半透明の破線のゾーン矩形（opacity: 35、strokeStyle: "dashed"、roughness: 0）を配列の最初の要素として追加し、視覚的なグループ化領域を作成します。references/excalidraw-schema.md → Background Zonesを参照してください。
• 要素の順序：ゾーン → 図形 → 矢印 → テキスト要素（適切なz-indexを確保し、テキストが常に最前面に表示されます）

よくある間違いとその回避方法

• ❌ 図形や矢印でlabel: { text: "..." }の省略記法を使用する — Excalidrawパーサーではサポートされていません
• ❌ containerIdを指定せずに、図形要素に直接textを設定する
• ❌ 矢印のバインドにstart／endを使用する — elementId／focus／gapを指定したstartBinding／endBindingを使用してください
• ❌ 接続先の図形のboundElements配列に矢印を追加し忘れる
• ❌ コンテナー内のテキスト要素にoriginalText、lineHeight、autoResize、またはbackgroundColor: "transparent"を指定し忘れる
• ❌ 必須の基本プロパティ（angle、strokeStyle、opacity、groupIds、frameId、index、isDeleted、seed、version、versionNonce、updated、link、locked）を省略する — 要素が描画されません
• ❌ JSONの最上位に"files": {}を指定し忘れる
• ❌ 楕円にroundness: { "type": 3 }を使用する — 楕円ではroundness: nullを使用する必要があります
• ❌ 矢印にlastCommittedPoint、startArrowhead、endArrowheadを指定し忘れる
• ❌ 矢印より先にテキスト要素を宣言する — テキストが下に描画され、隠れてしまいます
• ❌ バインドされていない矢印を配置する（図形と一緒に移動しません）
• ❌ 要素を重ねる（間隔を広げてください）
• ❌ 色の使い方に一貫性がない（あらかじめパレットを定義してください）
• ❌ 1つの図に要素を詰め込みすぎる（複数の図に分割してください）

検証チェックリスト

図を提出する前に、次の項目を確認してください。

• すべての要素に一意のIDが設定されている
• すべての要素に必須の基本プロパティがすべて設定されている：angle、strokeStyle、opacity、groupIds、frameId、index、isDeleted、link、locked、seed、version、versionNonce、updated
• index値が順番に割り当てられている（"a0"、"a1"、…）。テキスト要素の値は図形／矢印より大きくなっている
• 最上位のJSONに"files": {}が含まれている
• テキストを含む図形にはboundElementsがあり、別個のテキスト要素にcontainerIdが設定されている
• コンテナー内のテキスト要素にcontainerId、originalText、lineHeight: 1.25、autoResize: true、roundness: null、backgroundColor: "transparent"が設定されている
• 図形を接続する矢印にはstartBinding／endBinding（elementId、focus、gapを含む）が使用され、さらにlastCommittedPoint: null、startArrowhead: null、endArrowhead: "arrow"が設定されている
• 接続された図形のboundElements配列に矢印が含まれている
• 要素の順序が図形 → 矢印 → テキスト要素になっている（テキストが常に最前面に表示されます）
• 楕円にroundness: nullが使用されている（{ "type": 3 }ではない）
• 座標によって要素の重なりが防がれている（間隔を確認してください）
• テキストが読みやすい（フォントサイズ16以上）
• 色に一貫した配色が使用されている
• ファイルが有効なJSONである
• 要素数が適切である（見やすさのため20未満）

トラブルシューティング

問題	解決策
図形内にテキストが表示されない	boundElements と、containerId、originalText、lineHeight を指定した別のテキスト要素を使用します
矢印の背後にテキストが隠れる	テキスト要素を elements 配列の末尾（すべての矢印の後）に移動します
矢印が図形と一緒に動かない	elementId、focus: 0、gap: 1 を指定して startBinding/endBinding を使用します
図形が矢印と一緒に動かない	矢印を図形の boundElements 配列に追加します
要素が重なっている	座標間の間隔を広げます
テキストが収まらない	図形の幅を広げるか、フォントサイズを小さくします
要素が多すぎる	複数の図に分けます
色に統一感がない	あらかじめカラーパレットを定義し、一貫して適用します

制限事項

• 複雑な曲線は、直線または基本的な曲線に簡略化されます
• 手描き風の粗さはデフォルト（1）に設定されています
• 自動生成では画像を埋め込めません（サービスアイコンにはアイコンライブラリを使用してください）
• 見やすさを保つため、図あたり最大20要素を推奨します
• 自動衝突検出には対応していません — 間隔のガイドラインに従ってください