D2 図
D2 は宣言型言語です。つまり、形状とそれらの間の接続を記述すると、レイアウトエンジンがすべての配置を自動的に決定します。座標を手動で指定する必要は一切ありません。そのため、D2 の図は短く、diff が取りやすく、後で編集しやすいのです。また、ほとんどのエラーはデザインではなく、構文とレイアウトエンジンの癖 に起因します。
このスキルは、実際のコンパイラで検証された、D2 v0.9.x の完全な実践的知識を提供します。references/ と assets/templates/ にあるすべての例はコンパイル可能です。
ワークフロー
- ツールを確認する
d2 --version（またはscripts/d2check.sh --version）を実行します。d2がない場合はユーザーに伝え、brew install d2またはcurl -fsSL https://d2lang.com/install.sh | sh -s --を提案します。サイレントインストールは行わないでください。 - 図の種類を選択し、対応するリファレンスを読んでください（下の表）。該当するテンプレートが
assets/templates/にある場合は、そこから始めてください。 .d2ファイルを作成します（ユーザーが希望する場所。デフォルト:diagrams/<name>.d2）。scripts/d2check.sh <file.d2> [outdir] [pdf|pptx|gif]でコンパイルおよびレンダリングします（フォーマット、コンパイル、SVG レンダリング、outdir/preview/に PNG プレビュー、およびその他の追加フォーマットを生成します）。d2 validateだけに依存しないでください。これは構文しか解析しません。不正な形状名、範囲外のスタイル、サポートされていないレイアウト機能、欠落したインポートはすべてvalidateを通過し、コンパイル時に失敗します。- 画像を確認します。
preview/内の PNG を開き（.pngファイルに Read ツールを使用）、ラベルの重なり、エッジのもつれ、フロー方向の誤り、不均衡なレイアウトなどを評価します。修正して再レンダリングします。コンパイルできても読めない図は完成ではありません。 - 成果物を納品します（
.d2ソースファイルとレンダリングされたファイル）。使用したレイアウトエンジン、テーマ、方向も併せて伝え、ユーザーが変更できるようにします。
ファイルを作成しない簡単な一回限りの場合: echo 'a -> b' | d2 - out.svg
ひと目でわかる構文
direction: right # up | down | right | left（ルートレベル。TALA のみコンテナごとに指定可能）
# 形状: キー、オプションのラベル、オプションの属性
web: Web App {shape: rectangle} # キー `web`、ラベル "Web App"
db: Postgres {shape: cylinder}
user: Customer {shape: person}
# 接続: -> <- <-> -- （常にキーを参照し、ラベルは参照しない）
user -> web: uses
web -> db: SQL {style.stroke-dash: 3}
web -> cache: reads # 宣言されていないキーはその場で作成される
# コンテナ: ドットまたはネストされたマップ
backend: {
api -> worker: enqueue
worker -> _.db: writes # _ = 親スコープ
}
web -> backend.api: HTTPS
# スタイルは属性に記述する
db.style.fill: "#e6f2ff" # # で始まるものは引用符で囲む
(web -> db)[0].style.stroke: red # インデックスで接続をスタイル指定
# 再利用: クラス、変数、グロブ
classes: {
store: {shape: cylinder; style.fill: "#e6f2ff"}
}
cache.class: store
vars: {env: prod}
note: Running in ${env}
*.style.border-radius: 8
セミコロンは1行内の項目を区切ります。# はコメント、""" ... """ はブロックコメントです。キーは大文字小文字を区別せず、繰り返し宣言はマージされます（API、api、Api: Gateway は1つの形状で、ラベルは "Gateway" になります）。
クォーティング: エラーの最大の原因
引用符なしの文字列は便利ですが、いくつかの文字には特別な意味があります。ラベルに以下の文字が含まれる場合は、ラベル全体を引用符で囲んでください（"..." または '...'）。そうしないと、コンパイラがエラーを出すか、さらに悪いことに、ラベルを静かに切り詰めてしまいます。
| 文字 | 引用符なしでの動作 | 修正例 |
|---|---|---|
# （どこでも） | 行の残りがコメントになる: a: C# language は "C" とレンダリングされる | a: "C# language" |
[ （先頭） | 配列として解析される: a: [JSON/HTTPS] は "a" だけをレンダリングする | a: "[JSON/HTTPS]" |
. （キー内） | コンテナを作成する: svc v1.2 は svc v1 > 2 になる | "svc v1.2" |
& または [ ] （キー内） | 解析エラー（& はグロブフィルターマーカー） | "R&D", "svc[0]" |
$ （{ 以外に続く場合） | "substitutions must begin on {" | シングルクォート: 'costs $5' |
{ } ` | ` （ラベル先頭） | マップまたはブロック文字列を開始する |
予約語を形状キーとして使用 (label, link, class, top, style, shape, icon, near, direction, vars ...) | "reserved keywords are prohibited in edges" | "link" -> b、または別のキーを選ぶ |
エッジラベル内の -> または : | 実際には問題ない (a -> b: Time: 10s は動作する) | 引用符は不要 |
：（全角コロン）などの非ASCII句読点 | コロンとして認識されない | ASCIIの : ; . を使用する |
16進数カラーは引用符で囲む必要があります（"#fff"）。# がコメントを開始するためです。シングルクォートは ${...} 置換も無効にします。
ラベル内の改行: 引用符あり/なしのラベル内での \n、またはリッチテキスト用のブロック文字列 |md ... |。
注意すべき点（デバッグ前に読むこと）
- デフォルトのレイアウトエンジン Dagre は、コンテナとその子孫との接続を描画できません (
a -> a.b)。コンテナのサイズを変更できません（width/height）。また、near: <object>を使用できません。コンパイル時にエラーになります。図を書き直す代わりに、--layout=elk（またはvars.d2-config.layout-engine: elk）に切り替えてください。 - 予約語は大文字小文字を区別せずに照合されます。
Shape、Label、Class、Style、Link、Icon... という名前の形状やUMLクラスはキーワードと衝突します（reserved field shape does not accept composite）。名前を変更してください。 - キーで接続し、ラベルでは接続しないでください。
be: Backendの後でBackend -> xとすると、新しい 形状 "Backend" が作成されます。be -> xを使用してください。 - 繰り返しの接続はマージされません。
a -> bを2回記述すると、2本の矢印が描画されます。(a -> b)[0]、(a -> b)[1]のように指定します。 d2-legendは変数であり、形状ではありません。vars: { d2-legend: { ... } }の中に配置します。トップレベルのd2-legend: ""は、単に "d2-legend" という名前の通常の形状になります。- シーケンス図: 宣言の順序が画面上の順序になります。アクターは最初に宣言し、グループ内ではトップレベルに存在するアクターのみを参照できます。
- SQLテーブルとUMLクラス: 行 を接続します（
orders.user_id -> users.id）。ELK または TALA を使用して、エッジが正確な行に着地するようにします。 - 矢印の形状は、矢印がある端点にのみレンダリングされます。
A -> Bでsource-arrowhead.shape: diamondとしても、A には何も描画されません（--はまったく形状を描画しません）。形状をターゲットに配置するようにエッジを反転するか、<->を使用します。 d2 fmtは予約語のラベルを書き換えます（lnk: Linkはlnk: linkになります）。scripts/d2check.shはファイルをその場で fmt します。そのようなラベルは引用符で囲んでください（lnk: "Link"）。- ブロック文字列
|md ... |は次の|で終了します。内部にリテラルのパイプ記号が必要な場合は、より長い区切り文字を使用します:|md ...|または||md ... ||。 - 数値スタイルの範囲が強制されます:
stroke-width0-15、opacity0-1、font-size8-100。text-transformはnone|uppercase|lowercase|capitalizeを取ります（ウェブサイトにはtitleとありますが、コンパイラは拒否します）。3dは rectangle、square、hexagon でのみ機能します。 animated: trueやdark-theme-idは、要求がない限り追加しないでください。 アニメーションはランタイムデータフローを意味します。ダークテーマは、OSがダークモードの閲覧者のために色をサイレントに反転させます。- 形状の塗りつぶし色はテーマを上書きします。 テーマと少数の
classesを優先し、色が意味を持つ場合（その場合は凡例を追加する）にのみ明示的な色を使用します。 - PNG/PDF/PPTX/GIF は v0.9+ ではブラウザなしでレンダリングされます。 古いバージョン（<0.8）では Playwright/Chromium が必要で、初回使用時にダウンロードされます。
d2 --versionを確認してください。 - TALA は v0.9 にバンドルされています（
--layout=tala）が、非決定的です。小さなラベルの変更でレイアウトが再シャッフルされる可能性があります。再現性が重要な場合は、data.tala-seedsで固定します。 - マルチボードファイル（
layers/scenarios/steps） は、SVG と PNG を ディレクトリ としてエクスポートします（x/index.svg、x/layers/a.svg）。同じ名前の PNG をレンダリングすると、SVG ディレクトリが置き換えられます。フォーマットは別々のフォルダに保持します（スクリプトはそのようにします）。ドリルダウン可能な成果物には PDF を使用します（1ページに1ボード、クリック可能なlink: layers.x）。「戻る」形状を手書きしないでください。エクスポーターが自動的にパンくずリストバーを追加します。references/composition.mdを参照してください。 - 出力ファイルが存在しても成功を意味しません。 D2 はエラー時に部分的なレンダリングを書き込む可能性があります。終了コードを確認してください（スクリプトは確認します）。
レイアウト、方向、テーマの選択
- レイアウトエンジン:
dagre（デフォルト、高速、曲線エッジ）→elk（直交ルーティング、アーキテクチャ図、SQLテーブル、コンテナ間エッジに最適）→tala（対称性、コンテナごとのdirection、near: object、固定top/left）。コンテナやテーブルがある場合は、デフォルトで ELK を使用します。 - 方向: パイプライン、リクエストフロー、ワイドスクリーンには
right。階層や組織図にはdown。ボード全体で1つを選択します。 - テーマ:
theme-id: 0デフォルト。4Cool classics と3Flagship Terrastruct はモダンな見た目。1Neutral grey は落ち着いたドキュメント向け。8は色盲セーフ。300/301はターミナル。303は C4。200/201はダーク。完全なテーブルはreferences/cli-and-rendering.mdにあります。 - レンダリング設定はファイルに記述すると、ファイルと一緒に持ち運べます:
vars: {
d2-config: {
layout-engine: elk
theme-id: 4
pad: 40
}
}
（CLI フラグと D2_* 環境変数はこのブロックを上書きします。）
デザインガイダンス
- 1ボードあたり 3 ～ 12 個の形状。 それを超える場合は、
layers（ズームイン）、scenarios（バリエーション）、steps（段階的表示）で分割するか、コンテナを使用してグループ化します。 - キーで名前を付け、ラベルは人間のために: 短く安定したキー（
pg、auth）、読みやすいラベル（pg: PostgreSQL）。 - エッジラベルは動詞またはプロトコルにします（
reads、publishes、HTTPS）。文やターゲットの名前ではありません。 - 形状を意味に合わせます:
cylinderはストア、queue、person、cloudは外部、diamondは決定、hexagonはサービス、document/page、package、step。すべてを rectangle のままにしないでください。 - 色は意味をコード化するか、何もしません。 多くても約5カテゴリまでにし、
classesを通じて適用します。色がラベルが伝えない情報を伝える場合にのみd2-legendを使用します。 - 1つのボードには1つの抽象度レベル。
- D2 は、ホワイトボード規模（最大数百個の形状）でソフトウェアとシステムを文書化するためのものです。ガントチャート、マインドマップ、ベン図、サンキー図、円グラフ/棒グラフ、地理的マップは意図的にサポートしていません。また、1つのオブジェクトが2つのコンテナに存在することはできません。D2 を無理に使うのではなく、その旨を伝えて別のツールを提案してください。
リファレンスマップ
タスクに必要なものだけを読んでください。
| タスク | 読むもの |
|---|---|
| 構文の疑問: キー、ラベル、接続、コンテナ、文字列、エスケープ、コメント、予約語 | references/language.md |
形状、すべてのスタイルキーとその範囲、矢印、テキスト/マークダウン/LaTeX/コード、アイコン、near による配置、サイズ、テーマ | references/shapes-and-styling.md |
| シーケンス図、SQLテーブル（ERD）、UMLクラス、グリッド、凡例、ツールチップ/リンク、C4 | references/diagram-types.md |
クラス、変数、グロブとフィルター、オーバーライドと null、インポート、suspend モデル | references/reuse-and-globs.md |
| レイヤー、シナリオ、ステップ、ボードのリンク、大規模図のインポート、マルチボードエクスポート | references/composition.md |
CLI フラグ、レイアウトエンジン、テーマテーブル、エクスポート形式、d2-config、ドキュメント/CI への埋め込み、D2.js | references/cli-and-rendering.md |
| 図ファミリーごとの既製パターン（アーキテクチャ、フローチャート、状態、ERD、C4、組織図...） | references/recipes.md + assets/templates/*.d2 |
| Mermaid / PlantUML / Graphviz からの変換 | references/recipes.md（変換セクション） |
| エラーメッセージや誤ってレンダリングされる図 | references/troubleshooting.md |
コンパイルが失敗した場合
scripts/d2check.sh file.d2 を実行します。エラーは file:LINE:COL: message の形式で出力されます。references/troubleshooting.md でメッセージを調べてください。よくある原因は、クォーティング（上記）、レイアウトエンジンの制限（ELK に切り替え）、未知の形状や範囲外のスタイル、ブロック文字列のインデントです。一度に1つのエラーを修正して再実行してください。後のエラーは最初のエラーの結果であることが多いです。