excalidraw

Excalidraw 図

概要

.excalidraw JSON ファイルを生成し、PNG/SVG にエクスポートします。

エクスポート方法は 2 つあります：

• Kroki API（curl）— インストール不要、SVG のみ出力
• excalidraw-brute-export-cli — Firefox を使ったローカル実行、PNG と SVG に対応

対応形式： PNG（ローカル CLI のみ）、SVG（どちらの方法にも対応）。PDF には対応していません。

使用するタイミング

明示的なトリガー： ユーザーが「画图」、「diagram」、「visualize」、「flowchart」、「draw」、「架构图」、「流程图」と言った場合

積極的に使用するトリガー：

• 3 つ以上のコンポーネントが連携するシステムを説明する場合
• 複数ステップのプロセスや決定木を説明する場合
• アーキテクチャやアプローチを並べて比較する場合

使用を避ける場合： 簡単なリストや表で十分な場合、またはユーザーが簡潔な Q&A を求めている場合

使用しない場合 — 別のツールに振り分ける：

• 洗練された精密な図、厳密な UML、またはブランド化されたベンダーアイコン → drawio。
• Git で管理する図としてのコード、テキストからの自動レイアウト → mermaid（一般用途）または plantuml（UML）。
• 無限キャンバスのホワイトボード、またはプログラムによるフリーハンド描画 → tldraw。

前提条件

オプション A：Kroki API（推奨 — インストール不要、SVG のみ）

# Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)
curl --version

追加の設定は不要です。SVG は https://kroki.io を通じてレンダリングされます。

オプション B：ローカル CLI（PNG に必要）

CLI は Chromium ではなく Firefox を使用します。確認してインストールしてください：

npm install -g excalidraw-brute-export-cli
npx playwright install firefox

macOS のパッチ（初回のみ、必須）：

CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"

Windows/Linux： パッチは不要です。

ワークフロー

1. 依存関係を確認 — SVG には Kroki（curl）、PNG にはローカル CLI を使用します
2. 計画 — 視覚的な比喩（関係性とレイアウトの対応表を参照）を選び、次に図の種類とカラーパレットを決めます
3. 生成 — .excalidraw JSON ファイルを作成します（大きな図はセクションごとに作成）
4. エクスポート — Kroki または CLI のコマンドを実行します
5. レンダリングを確認 — エクスポートした PNG を表示し、不備があれば修正して再エクスポートします（レンダリングの確認を参照）
6. レビューを繰り返す — 画像をユーザーに見せ、依頼に応じて必要最小限の .excalidraw 編集を行い、承認されるまで再エクスポートします（レビューの繰り返しを参照）
7. 報告 — 出力ファイルのパスをユーザーに伝えます

デザイン原則

デフォルトのスタイル

• roughness: 0 — すべての技術図で、すっきりとしたモダンな見た目にします（手描き風やカジュアルなスタイルをユーザーが希望する場合のみ 1 を使用）
• fontFamily: 2（Helvetica）— プロフェッショナルな見た目にします。カジュアルなスケッチ風には 1（Virgil）、コードスニペットには 3（Cascadia）を使用します
• fillStyle: "solid" — デフォルトの塗りつぶし

コンテナー：ボックスよりタイポグラフィを優先

すべてのラベルをボックスで囲むと、図がワイヤーフレームのように見えます。最もすっきりとした Excalidraw の図では、構造を表すために 独立したテキストと線を使い、実際に コンポーネントである要素にのみ塗りつぶしボックスを使用します。

• コンテナーは使わないことを基本とする — ボックスを使う必要がなければ、単独の text 要素を使用します。
• 次の場合にのみボックスを追加する — 要素が実際のシステムコンポーネントである、矢印が要素につながる、形状自体に意味がある（判断を表すひし形、開始／終了を表す楕円）、または領域をグループ化する場合。
• ボックス内に収めるテキスト要素は、約 30% 未満を目安にします。
• タイムライン、ツリー、階層では、四角形を積み重ねるのではなく、線／コネクターと独立したラベルを使います。サイズ、太さ、色で階層を表現できます。

フォントサイズの階層

レベル	サイズ	用途
タイトル	28px	図のタイトル
見出し	24px	セクション／グループの見出し
ラベル	20px	主な要素のラベル
説明	16px	補足テキスト、説明
注記	14px	注釈、細則

カラーパレット

60-30-10 ルールに従います。60% を余白・ニュートラルカラー、30% をプライマリアクセント、10% をハイライトにします。

意味別の塗りつぶし色（strokeColor には1段階濃い色を使用します）：

カテゴリ	塗りつぶし	線	用途
プライマリ／入力	#dbeafe	#1e40af	エントリーポイント、API、ユーザー向け要素
成功／データ	#dcfce7	#166534	データストア、成功状態
警告／判断	#fef9c3	#854d0e	判断ポイント、条件
エラー／重大	#fee2e2	#991b1b	エラー、アラート、重大な経路
外部／ストレージ	#f3e8ff	#6b21a8	外部サービス、データベース、AI/ML
プロセス／デフォルト	#e0f2fe	#0369a1	標準的なプロセスのステップ
トリガー／開始	#fed7aa	#c2410c	開始ノード、トリガー、イベント
ニュートラル／コンテナー	#f1f5f9	#475569	グループ、スイムレーン、背景

テキストの色：

レベル	色
タイトル	#1e293b
ラベル	#334155
説明	#64748b

ルール：新しい色を独自に追加しないでください。 このパレットから選択します。

矢印の意味

スタイル	意味
実線（strokeStyle: "solid"）	プライマリフロー、メイン経路
破線（"dashed"）	応答、非同期、コールバック
点線（"dotted"）	任意、参照、弱い依存関係

Excalidraw JSON の構造

ファイルの基本構成

{
  "type": "excalidraw",
  "version": 2,
  "source": "claude-code",
  "elements": [],
  "appState": { "viewBackgroundColor": "#ffffff" }
}

要素の種類

type	用途
rectangle	ボックス、コンポーネント、モジュール
ellipse	開始／終了ノード、データベース
diamond	判断ポイント
arrow	有向接続
line	無向接続
text	独立したラベル

image、frame、embeddable は、このスキルの対象外です。image には別途 files マップと fileId が必要で、フレームや埋め込み要素はエクスポート経路で一貫して描画されません。上記の6種類のみを使用してください。これらのプリミティブで作成された既製のアイコンについては、以下のコミュニティの図形・アイコンライブラリを参照してください。

コミュニティの図形・アイコンライブラリ

単純なボックスではなく、AWS／Azure／GCP／ネットワーク／UML／BPMN の実際のアイコンが必要ですか？Excalidraw のコミュニティライブラリ（200以上の .excalidrawlib ファイル）は、ほぼすべて上記と同じベクタープリミティブで作成されています。そのため、image 要素や files マップを使わずに、項目をKroki とローカル CLI で描画できます。scripts/excalidraw_lib.py のヘルパーを使用してください。

# 1. Find a library (matches name / description / item names)
python scripts/excalidraw_lib.py search aws

# 2. List its items (index, name, element count; flags any image-based item)
python scripts/excalidraw_lib.py items slobodan/aws-serverless.excalidrawlib

# 3. Build your base scene first, then drop an item in at (x, y). IDs are
#    namespaced and coordinates translated, so it merges without collisions:
python scripts/excalidraw_lib.py merge scene.excalidraw \
    slobodan/aws-serverless.excalidrawlib 0 455 257 --scale 0.9 --prefix lambda

ルール：

• ベクターのみ。 merge は image 要素を含む項目を拒否します（エクスポート経路で描画できません）。items は該当項目を事前に通知します。
• 控えめに使用してください。 アイコンもラベル付きノードにすぎません。デザインシステムの間隔、ラベル、矢印の意味を保ってください。アイコンは図を引き立てるものであり、図の代わりにはなりません。
• 矢印はライブラリのグループにバインドされません。端から端までを明示した points でコネクターを描画してください（バインドは静的エクスポートに影響しません）。
• ライブラリは MIT ライセンスです。クレジット表記は歓迎しますが、必須ではありません。
• その後も必ず描画を検証するを実行してください。アイコンの境界ボックスはそれぞれ異なるため、位置合わせと間隔を確認します。

要素のサイズ

ラベルの切り詰めを防ぐため、ラベルテキストから要素の幅を計算します。

Latin text:  width = max(160, charCount * 9)
CJK text:   width = max(160, charCount * 18)
Mixed text:  estimate each character individually, sum up

高さ：1行のラベルには 60 を使用し、行が増えるごとに 24 を加えます。

独立した text は自動で折り返されません。複数行の独立したラベルでは、手動で \n の改行を挿入してください。16px では1行あたりラテン文字約30文字以下（CJK文字約15文字以下）を目安にし、行ごとに高さを 24 加えます。（containerId を介して図形内にバインドされたテキストは、コンテナーの幅に合わせて自動的に折り返されるため、\n を追加する代わりにコンテナーのサイズを調整してください。）

必須プロパティ（すべての要素）

{
  "id": "auth_service",
  "type": "rectangle",
  "x": 100, "y": 100,
  "width": 160, "height": 60,
  "angle": 0,
  "strokeColor": "#1e40af",
  "backgroundColor": "#dbeafe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 0,
  "opacity": 100,
  "seed": 100001,
  "boundElements": [
    { "id": "arrow_to_db", "type": "arrow" },
    { "id": "label_auth", "type": "text" }
  ]
}

ランダムな文字列ではなく、説明的な文字列 ID（例："api_gateway"、"arrow_gw_to_auth"）を使用してください。

各要素には一意の seed（整数）を指定します。セクションごとに名前空間を分けてください：100xxx、200xxx、300xxx。

JSON フィールドのルール

• boundElements：空の場合はnullを使用し、[]は使用しないでください
• updated：常に1を使用し、タイムスタンプは使用しないでください
• 含めないでください：frameId、index、versionNonce、rawText
• 矢印のpoints：必ず[0, 0]から開始してください
• seed：要素ごとに異なる正の整数を指定してください

プロパティ値

以下の値のみ使用してください。すべてKrokiとローカルCLIで描画できることを確認済みです。

プロパティ	有効な値
fillStyle	"solid"、"hachure"、"cross-hatch"、"zigzag"
strokeStyle	"solid"（または省略）、"dashed"、"dotted"
fontFamily	1（Virgil、手描き風）、2（Helvetica）、3（Cascadia、コード用）
textAlign	"left"、"center"、"right"
verticalAlign	"top"、"middle"、"bottom"
startArrowhead / endArrowhead	null、"arrow"、"triangle"、"bar"、"dot"、"circle"、"diamond"、"crowfoot_many"

矢印のデフォルトはendArrowhead: "arrow"、startArrowhead: nullです。標準の一方向矢印では両方を省略してください。UMLの継承には"triangle"、コンポジションには"diamond"、ERのカーディナリティには"crowfoot_many"を使用します。

コピー＆ペースト用テンプレートや、プロパティ／矢印の先端形状の全カタログが必要ですか？ references/schema-reference.mdを参照してください。完全な要素テンプレート（コンポーネント＋ラベル、バインドされた矢印、矢印ラベル、スイムレーンのゾーン、マインドマップのコネクター）と、検証済みのすべてのプロパティ値を掲載しています。

図形内のテキスト（内包されたテキスト）

テキストを図形の内側に配置する場合は、双方向にバインドしてください。

{
  "id": "label_auth",
  "type": "text",
  "text": "Auth Service",
  "fontSize": 20,
  "fontFamily": 2,
  "textAlign": "center",
  "verticalAlign": "middle",
  "strokeColor": "#1e293b",
  "containerId": "auth_service"
}

重要：テキストのstrokeColorは文字色です。 テキストの色パレットから濃い色を選び、必ず明示的に設定してください。省略しないでください。テキストのstrokeColorを省略すると、テキストが見えなくなり、図形の背景に溶け込むことがあります。

親図形のboundElementsにテキストを含める必要があります。

"boundElements": [{ "id": "label_auth", "type": "text" }]

矢印のバインド（双方向）

矢印は図形にバインドし、図形からもバインドされた矢印を参照する必要があります。

{
  "id": "arrow_gw_to_auth",
  "type": "arrow",
  "points": [[0, 0], [200, 0]],
  "startBinding": { "elementId": "api_gateway", "gap": 5, "focus": 0 },
  "endBinding": { "elementId": "auth_service", "gap": 5, "focus": 0 }
}

api_gatewayとauth_serviceの両方のboundElementsに、以下を含める必要があります。

"boundElements": [{ "id": "arrow_gw_to_auth", "type": "arrow" }]

端点は図形の境界に届く必要があります。 startBinding／endBinding（およびそれらのgap）が影響するのは、excalidraw.comでのインタラクティブな編集のみです。KrokiまたはローカルCLIでエクスポートする際、線はクリップされません。エクスポーターはpointsをそのまま描画します。そのため、端点が図形の境界から境界まで届くように計算してください。矢印のx／yを始点側の図形の境界（対象側を向いた辺）に設定し、最後の点を対象側の図形の境界に設定します。中心から中心への点を指定すると、線が両方の図形をまっすぐ貫通して描画されます。

矢印ラベル

矢印にラベルを付けるには、図形内テキストと同じ方法でtext要素をバインドします。ラベルのcontainerIdに矢印のIDを設定し、矢印のboundElementsにラベルを追加してください。Excalidrawはラベルを矢印の中央に配置し、テキストの背後の線をマスクするため、ラベルを読みやすく保てます（線が文字に重なりません）。

{
  "id": "arrow_valid_to_grant",
  "type": "arrow",
  "points": [[0, 0], [0, 120]],
  "boundElements": [{ "id": "lbl_yes", "type": "text" }]
}

{
  "id": "lbl_yes",
  "type": "text",
  "text": "Yes",
  "fontSize": 14,
  "width": 36,
  "strokeColor": "#1e293b",
  "containerId": "arrow_valid_to_grant"
}

重要：ラベルのwidthは矢印の長さではなく、テキストに合わせる必要があります（charCount * 9）。 Excalidrawはラベルのバウンディングボックス全体にわたって背後の線をマスクします。ラベルの幅を矢印と同じにすると、矢印全体がマスクされ、線が消えて浮いたテキストだけが残ります。ラベルの幅は小さく保ってください。

矢印のルーティング

L字型（エルボー）矢印 — 3点以上を使った直交ルーティング：

"points": [[0, 0], [100, 0], [100, 150]]

エルボー矢印 — 直角に曲がる自動ルーティング：

{
  "type": "arrow",
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

曲線矢印 — 経由点を使った滑らかなルーティング：

{
  "type": "arrow",
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": { "type": 2 }
}

グループ化

関連する要素ではgroupIdsを共有します。ネストされたグループでは、IDを内側のグループから順に並べます。

"groupIds": ["inner_group", "outer_group"]

図のパターン

図の種類ごとに、適切な視覚パターンを選んでください。

関係性に応じたレイアウトの対応表

図の種類を決める前に、アイデアの関係性に合った視覚的な比喩を選びます。図の種類のラベルよりも、比喩のほうがレイアウトに大きく影響します。

アイデア内の関係性	視覚的な比喩	作成方法
1 → 多（ブロードキャスト、ディスパッチ）	放射状の分岐	1つのノードから、外側へ放射状に矢印を伸ばす
多 → 1（集約、統合）	収束	複数の入力から、1つのノードへ矢印を向ける
親 → 子（階層）	ツリー	幹と枝の線、独立して配置するテキスト
繰り返すサイクル（ループ、フィードバック）	サイクル	ノードを輪状に配置し、開始点に戻る曲線の矢印を付ける
入力 → 変換 → 出力	組み立てライン	左から右へ流れる工程のパイプライン
A 対 B（比較）	並列配置	共通の基準線上に2つの列を並べる
前／後、フェーズの区切り	間隔	グループ間に空白または破線の仕切りを設ける
曖昧／重なり合う状態	雲	楕円を重ね、明確な境界線は設けない

間隔の目安

場面	間隔
ラベル付き矢印の間隔（図形間）	150～200px
ラベルなし矢印の間隔	100～120px
列の間隔（ラベル付き矢印）	400px（220px のボックス + 180px の間隔）
列の間隔（ラベルなし矢印）	340px（220px のボックス + 120px の間隔）
行の間隔	280～350px（150px のボックス + 130～200px の間隔）
ゾーン／コンテナの内側の余白	子要素の周囲に 50～60px
ゾーン／コンテナの不透明度	25～40
要素間に必要な最小間隔	40px

フローチャート（LR または TB）

• 開始／終了には楕円、判断にはひし形、処理には長方形を使います
• 水平方向に 200px、垂直方向に 150px の間隔を空けます
• 判断の分岐：「はい」は先へ進み、「いいえ」は下へ進みます
• 3～10 個のステップ（最大 15 個）

アーキテクチャ／システム図

• 上の表に従って列の間隔を設定します。接続にラベルがある場合は、ラベル付き矢印の間隔を使います
• 関連するサービスは、破線の Neutral コンテナ（不透明度：30、余白：50px）にまとめます
• ゲートウェイ／入口は左または上に、データベースは右または下に配置します
• 3～8 個のエンティティ（最大 12 個）

シーケンス図

• 参加者（上部の長方形）間の間隔は 200px にします
• 垂直のライフラインは破線にします
• メッセージには水平方向の矢印を使い、垂直方向に 60px の間隔を空けます
• 実線の矢印 = リクエスト、破線の矢印 = レスポンス

マインドマップ

• 中央ノード：最大サイズ（200x100）、Trigger カラー
• レベル 1：150x70、Primary カラー、中央の周囲に放射状に配置
• レベル 2：120x50、Process カラー
• レベル 3：90x40、Neutral カラー
• 接続には矢印ではなく線を使います
• 4～6 個の枝（最大 8 個）、各枝に 2～4 個のサブトピック
• レベル 1 の枝は、中心 (cx, cy) を囲む半径 R ≈ 280 の円上に配置します。枝 i の数を n とすると、angle = 2π·i/n、x = cx + R·cos(angle)、y = cy + R·sin(angle) です。間隔を均等にすると、場当たり的に配置したときに生じる線の交差や絡まりを防げます。

スイムレーン

• レーンの境界には、大きな透明な長方形（Neutral の塗りつぶし、"dashed" の線、不透明度：30）を使います
• レーンのラベルは、レーンの左上に独立したテキストとして配置します（長方形に紐付けない）。フォントサイズは 28px です
• レーン内の要素は左から右へ流れるように配置します
• 引き継ぎを表す矢印はレーンをまたぐようにします

セクションごとの作成

要素が 10 個以上の図では、JSON 全体を一度に生成しないでください。セクションごとに作成します。

1. まずすべてのセクションを計画します — 要素 ID、位置、セクションをまたぐバインディングを列挙します
2. セクション 1 を作成します — 初期要素を含むファイルを作成します
3. セクション 2 を追加します — ファイルを読み込み、新しい要素を elements 配列に追加します
4. 繰り返します — すべてのセクションが終わるまで続けます
5. 最後に確認します — すべての boundElements と startBinding／endBinding の参照に整合性があることを確認します

衝突を避けるため、セクションごとに要素シードの名前空間を分けます（100xxx、200xxx、300xxx）。

エクスポート

オプション A：Kroki API（SVG のみ — インストール不要）

# SVG via Kroki API
curl -s -X POST https://kroki.io/excalidraw/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.excalidraw" \
  -o diagram.svg

# Via local Kroki Docker (offline)
curl -s -X POST http://localhost:8000/excalidraw/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.excalidraw" \
  -o diagram.svg

オプション B：ローカル CLI（PNG + SVG）

# PNG at 2x scale, with background baked in (recommended)
excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.png -f png -s 2 -b true

# PNG at 1x scale
excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.png -f png -s 1 -b true

# SVG
excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.svg -f svg -s 1 -b true

必須フラグ： -f（形式：png または svg）および -s（スケール：1、2、または 3）。

オプションのフラグ： -b true は viewBackgroundColor を画像に焼き込みます。デフォルトではエクスポートは透過されるため、透明な背景にしたい場合は -b を省略するか、-b false を渡してください。 -d true はダークモードでエクスポートします。-e true はシーンを埋め込み、PNG/SVG を excalidraw.com で再度開いたときに編集可能な描画として表示します。（長い形式も使用できます：--background、--dark-mode、--embed-scene、--format、--scale、--input、--output。）

レンダリングを確認する

JSON から図の良し悪しを判断することはできません。 JSON が完璧に見えても、画像ではテキストが切れていたり、ボックスが重なっていたり、矢印が図形を貫通していたりすることがあります。エクスポート後は、結果を目で確認して修正してください。これが最も効果の大きい手順です。

1. PNG にレンダリングします（最終的にユーザーが SVG を希望していても、画像は表示可能な形式にする必要があります。SVG ではなく PNG を使用してください）。

   excalidraw-brute-export-cli -i diagram.excalidraw -o /tmp/check.png -f png -s 2 -b true
   

   /tmp/check.png を表示します（Claude は PNG を直接読み取れます）。目視確認にはローカル CLI が必要です。Kroki のみ（SVG）の場合は、以下の構造チェックを行ってください。

2. 画像を確認します。

   確認項目	修正方法
   テキストが図形からはみ出している、または切れている	図形の幅を広げます（max(160, charCount * 9)、CJK 文字では ×2）または \n で事前に折り返します
   ボックスまたはラベルが重なっている	間隔のリファレンスに従って、間隔を取り直します（40px 以上）
   矢印が図形をまっすぐ貫通している	矢印の端点を中心ではなく、図形の境界に移動します
   矢印が見えず、ラベルだけが表示されている	テキストに収まるよう、ラベルの width を小さくします
   要素がキャンバスからはみ出している、または接続なしで浮いている	位置を調整するか、接続します
   同型性テスト： すべてのテキストを頭の中で削除したとき、構造だけで意味が伝わりますか？	伝わらない場合、問題はラベルではなく レイアウト にあります。構成を見直してください

3. JSON を修正して再エクスポートします。 問題がなくなるまで繰り返します。通常は 1～3 回で完了します。要素が 2～3 個の単純な図の場合に限り、省略できます。

レビューループ

レンダリングの確認では 不具合 を修正し、レビューループでは ユーザーの 希望を反映します。レンダリングに問題がないことを確認したら、図を提示してフィードバックを集め、各要望に対して 最小限の .excalidraw 編集 を行って再エクスポートします。

ユーザーの要望	編集内容
ラベルを変更する	text（またはバインドされたラベル要素）を編集します
色を変更する	要素の backgroundColor / strokeColor を更新します
要素を追加／削除する	要素を追加または削除します（boundElements / バインド参照も修正してください）
移動／サイズ変更	x / y / width / height を更新します
構成変更／経路変更	パターンの間隔と経路設定のルールを再適用するか、再生成します

• 各回で同じ diagram.excalidraw / 出力ファイルを上書きします。v1、v2、…のようなファイルは作成しないでください。
• 編集のたびに レンダリングを確認する を再実行します（変更によって新たな切れや重なりが生じることがあります）。
• 最終手段： 5 回繰り返したら、ユーザーに excalidraw.com で微調整するよう提案します。出力では矢印のバインドが保持されるため、完全に編集可能な状態で開けます。

アンチパターン

大きな背景／ゾーン用の長方形に text を配置しないでください。 Excalidraw はテキストを図形の中央に配置するため、内部に配置した要素と重なります。代わりに、ゾーンの上部に配置した独立した text 要素を使用してください。

ゾーンをまたぐ矢印は避けてください。 長い斜めの矢印は、視覚的にごちゃついた印象になります。矢印はゾーン内、またはゾーンの端に沿って配置してください。ゾーンをまたぐ接続が避けられない場合は、外周に沿って配置してください。

矢印ラベルは控えめに使用してください。 ラベルを矢印にバインドすると（矢印ラベルを参照）、線がテキストの背後でマスクされ、テキストに重なりません。ただし、ラベルの width は矢印の長さではなく、テキストに合わせてください。ラベルは12文字以下にし、接続された図形の間に120px以上の空間を確保してください。接続の意味が文脈から明らかな場合は、ラベルを省略してください。

ほかの要素を含むコンテナには、塗りつぶした背景を使用しないでください。 ゾーン／コンテナ用の長方形には opacity: 30（または25～40の範囲）を設定し、内部の要素が見えるようにしてください。

テキスト要素には必ず明示的に strokeColor を設定してください。 テキストの strokeColor は、描画されるテキストの色です。省略すると、テキストが親図形の背景色を継承して見えなくなる場合があります。テキストカラーのパレットから #1e293b（タイトル）、#334155（ラベル）、または #64748b（説明）を使用してください。

よくある間違い

間違い	修正方法
Kroki が HTTP 400 を返す	-H "Content-Type: text/plain" を送信してください（application/json は使用しないでください。Kroki は {"diagram_source": ...} のラッパーとして読み取り、拒否します）。"type": "excalidraw" と "elements" 配列を含む有効な JSON であることを確認してください
Kroki の出力が SVG のみ	PNG にはローカル CLI（excalidraw-brute-export-cli）を使用してください
「Missing required flag」エラーでエクスポートに失敗する	必ず -f png と -s 2 を渡してください
「Executable doesn't exist」エラーでエクスポートに失敗する	npx playwright install firefox を実行してください
macOS：ファイル選択ダイアログの待機がタイムアウトする	上記の macOS Meta パッチを適用してください
矢印の points が原点を基準にしていない	points は常に [0,0] から始まります
要素に id がない	各要素に内容がわかる文字列 ID を使用してください
要素が重なっている	間隔の参考表を使用し、最低40pxの間隔を確保してください
excalidraw.com で矢印が操作できない	バインドされたすべての矢印／テキストを参照する boundElements を図形に追加してください
矢印／線が図形をまっすぐ貫通する	中心ではなく図形の境界で端点を計算してください。バインドは静的エクスポートで線をクリップしません
矢印が見えず、ラベルだけ表示される	バインドされたラベルの width が矢印全体に及び、線をマスクしています。ラベルの width をテキストに合わせて設定してください（charCount * 9）
エクスポートした PNG／SVG に背景がない	CLI のエクスポートはデフォルトで透明です。viewBackgroundColor を適用するには -b true を渡してください
図形内のテキストが中央揃えにならない	テキストに containerId を設定し、図形の boundElements にテキストを追加してください
すべてのテキストが同じサイズ	フォントサイズの階層を使用してください：28 → 24 → 20 → 16 → 14
図が単調に見える	パレットから意味に合った色を適用し、60-30-10のルールに従ってください
テキストが見えない／背景と同じ色	テキスト要素には必ず濃い色の strokeColor（#1e293b、#334155、または #64748b）を設定してください
ゾーン／コンテナ内でテキストが重なる	テキストをゾーン用の長方形にバインドせず、上部に独立したテキストを配置してください
図形内のテキストが途中で切れる	幅の計算式 max(160, charCount * 9) を使用してください。CJK では2倍にしてください
boundElements: [] が問題を引き起こす	空の boundElements には [] ではなく null を使用してください