d2-diagram

d2-diagram

以下のパスでは、<skill> はこのスキルのディレクトリ、<skills> はスキルのインストール先ディレクトリです（mizchi/explainer では skills/、インストールしたプロジェクトでは .claude/skills/）。

D2 ファイルが図であり、画像はそのレンダリング結果です。書き手の役割はテキスト（ID、ラベル、コンテナー、接続）を記述すること、TALAの役割はボックスの配置と線の曲げ方を決めることです。ターミナルでレンダリングするのは、シェルから離れずに毎回図を確認できるようにするため、また図を README のコードブロック、PR コメント、--help のテキストにそのまま掲載できるようにするためです。

direction: right
web: Web frontend
api: API server
db: PostgreSQL {shape: cylinder}
web -> api: HTTPS
api -> db: SQL

                                                          .-‾‾‾‾‾‾-.
                                                         │╲-______-╱│
                    HTTPS                        SQL     │          │
┌─────────────┐──────────────▶┌───────────┐─────────────▶│          │
│Web frontend │               │API server │              │PostgreSQL│
│             │               │           │              │          │
└─────────────┘               └───────────┘               ╲-______-╱

（d2 --layout=tala x.d2 x.txt によるそのままの出力、D2 0.8.1-HEAD。）

このスキルは、成果物が D2 テキストである図を対象とします。後から誰かが編集し、TALAがレイアウトし、D2 が動作する場所ならどこでもレンダリングできます。手順を追う流れ（アルゴリズムやリクエスト）はアニメーションにせず、構造を一度描き、手順には本文中で番号を付けてください。D2 をコードに基づいたものにするには、まずコードからモジュールと依存関係（インポート、package.json）を列挙し、ファクトシートに記載して、それらだけを正確に描いてください。

実行方法

d2 layout                                   # must list `tala (bundled)`. That, not the version
                                            # string, is the gate: v0.8.1-HEAD already bundles it.

d2 --layout=tala arch.d2 arch.txt && cat arch.txt        # the terminal render (Unicode box drawing)
d2 --layout=tala --ascii-mode standard arch.d2 arch.txt  # plain ASCII (+ - | / < > v) for a README
d2 --layout=tala arch.d2 --stdout-format ascii -         # to stdout, for a pipe or a PR comment
d2 --layout=tala arch.d2 arch.svg                        # the figure for docs
d2 --layout=tala arch.d2 arch.png                        # a raster to LOOK at (see the loop, step 5)

d2 validate arch.d2                         # syntax only; exit 1 with file:line:col
d2 fmt --check arch.d2                      # formatted? exit 1 and names the file, changes nothing
d2 fmt arch.d2                              # ...and this rewrites it in place

node <skill>/assets/d2-facts.mjs arch.d2               # what the picture DRAWS
node <skill>/assets/d2-facts.mjs arch.d2 --expect f.json   # ...held to a sheet
LC_ALL=C.UTF-8 wc -L arch.txt               # the width in columns — the locale matters, see below

d2 が見つからない場合はインストールしてください。オンラインのプレイグラウンド経由で図を作成することは避けてください。

curl -fsSL https://d2lang.com/install.sh | sh -s --      # the installer; it rejects the obsolete --tala flag
brew install d2                                          # macOS
go install github.com/d2lang/d2@latest                   # Go 1.27+; what to do when the install script gets a 403 through a proxy

環境変数での D2_LAYOUT=tala はフラグと同じです。ファイル内の vars: { d2-config: { layout-engine: tala } } は .svg／.png では反映されますが、.txt では反映されません（計測に使用したビルド 0.8.1-HEAD では、テキストのレンダリングが dagre にフォールバックし、120 列ではなく 163 列になりました）。そのため、フラグも渡してください。次の人が同じエンジンで SVG を生成できるように、ファイル内の設定も残してください。例外は sequence_diagram です。これは自身でレイアウトするため、フラグの有無にかかわらず、テキストのレンダリング結果はバイト単位で同一になりました。

D2 には図が間違っていることを示すものがありません

validate が読み取るのは構文です。レンダラーはファイルの記述どおりに描画します。--expect もレイアウトレポートもなく、スコープ内にない ID への参照もエラーになりません。新しい図形が作成されます。 そのため、次の図は誤りがあっても気づかれません。

edge:    { cdn; gateway }
cluster: { orders; inventory }
gateway -> orders        # ← two NEW empty boxes at the root; the real ones keep no arrow

このスキル独自の検証ラウンドで、ある作成者がまさにこれをそのまま出荷しました。d2 validate は 0、d2 fmt は問題なし、94 列で、ログには「すべての接続をたどれる」と書かれていました。ところがレンダリング結果には重複したボックスが 4 つ、孤立した図形が 2 つあり、システムのエントリーコールはどの領域にも属さない浮遊するペアとして描かれていました （レポート）。

コンテナーをまたぐ接続は、完全パスを使ってルートに記述してください。 これが常に機能する唯一の形式であり、正しく記述できたラウンド参加者全員が使っていた形式です。

edge.gateway -> cluster.orders          # at the root: full path on both ends
cluster: {
  billing -> _.outside.stripe           # from INSIDE: `_` is this container's parent
}

_ が指すのは1 階層だけで、コンテナー内でのみ有効です。cluster の内部では、_ はルートを指すため、兄弟コンテナー内の図形は _.outside.stripe です。_.stripe ではありません。これはルートレベルの stripe を新たに作成します（これがラウンドで 4 つ目に現れた幻の図形です）。ルートでは、_ が指す親がありません。d2 は invalid underscore でコンパイルに失敗し、後の作成者はこれをエスケープが壊れていると解釈しました。

assets/d2-facts.mjs は、D2 にないチェック機能です。ファイルをレンダリングし、SVG から図を読み取ります。d2 はすべての図形と接続の完全修飾 ID を SVG に書き込むため、この機能が報告するのは、ソースが示しているように見える内容ではなく、読者が実際に目にする内容です。依存関係はありません。別のリポジトリでも、図の隣にコピーして使えます。

node assets/d2-facts.mjs arch.d2               # boxes, containers and their members, labels, edges, columns
node assets/d2-facts.mjs arch.d2 --expect arch.facts.json
node assets/d2-facts.mjs arch.d2 --seeds 4,5,6 # the seed the final render will use, so the width it reports is real
node assets/d2-facts.mjs --from-svg arch.svg --from-txt arch.txt   # read renders that already exist, no d2 run

最後の形式は、チェッカー自体の検証にも使われています。tests/d2/d2-facts.test.mjs は、d2 をインストールせずに tests/d2/fixtures/d2-scenario/ にコミットされたレンダリング結果を使ってチェッカーを実行します。そのため、幻のボックス、切り詰め、エッジの逆向き、幅の各チェックには、検出されなくなると失敗するテストがあります。また、他の人が作成したレンダリング結果や、レビュー中の PR にある .svg を検査する方法でもあります。

シートがなくても、常に欠陥となる次の 3 つの問題は単独で検出されます。同じ名前が 2 回描画されている（上記のスコープに関する問題）、ボックスが兄弟と重なるかコンテナーからはみ出している、そしてターミナルレンダリングが切り詰められている場合です。top / left のピンによって図形が ASCII キャンバスの外に押し出されることがあり、断片だけを含むテキストファイルでも d2 は終了コード 0 を返します。ある作成者の 5 つのテーブルを含むスキーマは「71 列」として検証を通過しましたが、その直前に測定したレンダリング結果では 5 つのテーブルのうち 3 つが欠けていました。これがボックスごとの比較を導入した理由です。どの図形とも接続されていないボックスは警告されます。シートを指定すると、さらに次の項目もチェックします。

{
  "boxes": ["gateway", "orders", "broker"],
  "deps": ["gateway->orders", "orders->broker"],
  "forbidden": ["orders->billing"],
  "containers": { "cluster": ["orders", "inventory"] },
  "order": ["browser->gateway", "gateway->orders"],
  "exhaustive": true,
  "maxColumns": 100,
  "allowOrphans": ["legend"]
}

• deps は方向も含めてチェックされます。逆向きの矢印は ✗ edge reversed: the sheet says broker->billing, the picture draws billing->broker と表示されます。
• exhaustive を指定すると、シートに記載されていないエッジは警告ではなくエラーになります。
• order は、シーケンス図のメッセージを y 座標の位置から読み取ります。D2 で順序が見える唯一の場所です。
• 名前は、ID の最後のセグメントまたはラベルと一致します。そのため、ファイルで gw: API gateway と記述されていても、シートには gateway と記載できます。
• sql_table の内部は確認できません。列レベルのエッジ（orders.customer_id -> customers.id）は orders->customers として報告されます。制約バッジもチェックされません。grep -o '>FK</text>' arch.svg | wc -l で数えてください（grep -c は行数を数えますが、SVG は 1 行なので、バッジがいくつあっても 1 と出力されます）。また、どの行から矢印が出ているかは PNG を確認してください。

テストを先に書くのと同じように、図を作成する前に要件からシートを作成してください。TALA のリフロー後も残る唯一の成果物です。

シート名から図形を特定する方法

シート内の名前は ID だけで照合されるのではなく、完全に一致する図形が 1 つ見つかるまで検索範囲が広がります。

1. ID の最後のセグメント — orders は cluster.orders に一致します
2. 完全一致する ラベル — gateway は gw: API gateway に一致します
3. 完全に一致する図形が 1 つだけの場合、ID またはラベルの 部分文字列

ステップ 3 は意図的に幅広く一致するため、驚くことがあるでしょう。pg という名前のボックスに Postgres orders (authoritative until cutover) というラベルが付いている場合、これもシートの orders に一致するため、そのボックスに入るエッジに対して forbidden: ["checkout->orders"] が発動します。これはシートと図のどちらかのバグではありません。名前が一致していないのです。そのため、あいまいな一致を使うすべての行で、どの一致が使われたかを表示するようになりました。

✗ forbidden edge drawn: checkout->orders (orders matched no id — it is a
  substring of box pg's label "Postgres orders (authoritative until cutover)")

何かを編集する前に、その条件を読んでください。条件がある場合は、シートの範囲を限定するか、図を修正するかを選べます。条件がなければ、作成者はチェックを通すため、正しいボックスのラベルを変更してしまうでしょう （tests/d2/fixtures/d2-scenario/v2/label-substring/）。

TALA を使う理由と、使わないほうがよい場合

TALA（Terrastruct の AutoLayout Algorithm）は、ソフトウェアアーキテクチャ図向けの D2 独自のエンジンです。MPL-2.0 のもとでオープンソース化され、D2 にバンドルされています（告知で名前が挙がっているリリースは 0.9.0 ですが、ここで測定した 0.8.1-HEAD ビルドにも含まれています。バージョンではなく d2 layout に問い合わせてください）。dagre と ELK が有向グラフをレイヤー状に配置するのに対し、TALA はホワイトボードの図のようにボックスを配置します。直交配置が可能で、できる限り対称にし、コンテナごとにまとめます。また、すべての D2 機能に対応する唯一のエンジンです。コンテナごとの direction、コンテナの width ／ height、near: <other shape>、そしてエンジンが残りを配置する間に図形を固定する top ／ left に対応しています。

図の特徴	エンジン
複数の方向に接続するコンテナ内のボックス（アーキテクチャ、デプロイメント、データモデル）	tala
明確な方向に沿って多数のホップがある 1 つのフロー（パイプライン、DAG）	direction: right を指定した tala。それでも見づらければ elk を使います。告知では、TALA はフローグラフの配置があまり得意ではないと明言されています
図形が 30 個以上	コンテナごとに分割して 2 つのファイルにします。TALA の実行時間はサイズに対して非線形です。ここでは 30 ノードの配置に 0.94 秒かかったのに対し、ELK は 0.05 秒でした。また、この規模のレイアウトは、どのエンジンを使っても読みづらくなります

ランダム性を再現可能にする。 TALA は 3 つのシード（--tala-seeds、デフォルトは 1,2,3）を試し、最良の完全な結果を採用するため、同じファイルを 2 回描画すると同じ図になります。測定でも同一でした。ラベルを変更すると配置が連鎖的に変わることはあるため、文章では「左側のボックス」のように形状を説明せず、ID を指定してください。シードを使う前に、測定で確認された注意点が 2 つあります。

• シードセットを変えても、何も変わらないことがよくあります。 ある作成者は 5 テーブルのスキーマで 12 種類のシードセットを試しましたが、毎回 109 列のまったく同じレイアウトになりました。別の作成者は --tala-seeds 4,5,6 で 113 列から 100 列に減らしました。一度試して、測定した数値を記録し、それに頼らないようにしてください。
• シードはファイルに保存できません。 d2 layout tala には「tala-seeds 以下の図データがコマンドラインフラグより優先されます」とありますが、vars.d2-config.tala-seeds はコンパイル時に拒否されます。シードに依存する図をコミットしても、すべての描画でフラグを渡さなければ、そのレイアウトにはなりません。そのため、フラグをスクリプトまたは Makefile のターゲットに記述するか、シードに依存しないようにしてください。

タスクに応じた選択

タスクの形	記述内容
「アーキテクチャ／サービスの構成を描く」	領域ごとにコンテナを使います（cluster: our cluster { orders; inventory }）。子要素間の接続はルートで (edge.gateway -> cluster.orders)、または内部から _. を使って記述します。ルートに direction: right を指定し、最も要素の多いコンテナにコンテナごとの direction を指定する方法が幅を調整するコツです。詳しくは後述します
「データモデル／テーブルを描く」	shape: sql_table を使い、id: int {constraint: primary_key} と customer_id: int {constraint: foreign_key} の行を記述します。列を接続します（orders.customer_id -> customers.id）
「コンポーネント間のリクエスト／呼び出しフローを描く」	ルートに shape: sequence_diagram を指定し、アクターは最初に使用する順に並べます。各行にラベル付きのメッセージを1つずつ記述します。D2 には戻り矢印も非同期矢印もなく、ターミナルでのレンダリングではすべてのスタイルが失われるため、その違いはラベルで表します。図の前に説明を記載したうえで、ラベルの先頭または末尾に句読点を含まない4文字以内の単独のマーカーを置きます（ret 201 Created、order.placed async）。reserved (ret) は保持されません。レンダリング時に括弧が線の文字で上書きされ、レーンいっぱいにラベルを置くと矢印に矢じりがまったく表示されません。図の中に凡例を置く方法も使えません。shape: text は空のボックスとしてレンダリングされます
「クラスを描く」	shape: class を使い、+method(): type ／ -field: type の行を記述します
「デプロイメント／ネットワークを描く」	ホストとゾーンにはコンテナを使い、ストアには shape: cylinder、外部サービスには shape: cloud、ブローカーには shape: queue を使います
「すでに .d2 がある」	既存のファイルを編集し、d2 fmt --check を実行して、変更前後をレンダリングします。理由を説明せずにエンジンやテーマを切り替えないでください
「README／コードブロック／PR コメントに載せる」	フェンス付きブロック内に standard の ASCII レンダリングを置きます。幅は後述の方法で測定し、.d2 ファイルも隣に置いてください
「コードと照合する必要がある」	まずコード（インポート、package.json）からモジュールと依存関係をシートに書き出し、それだけを正確に描いてから d2-facts --expect を実行します

反復作業

1. write arch.facts.json                             the boxes, edges and width the brief asks for
2. write arch.d2                                     ids ASCII; the label after the colon is what the reader sees
3. d2 fmt --check arch.d2 && d2 validate arch.d2     syntax; exit 1 names file:line:col
4. node assets/d2-facts.mjs arch.d2 --expect arch.facts.json
                                                     duplicates, missing / reversed / invented edges,
                                                     container members, overlaps, order, width
5. d2 --layout=tala arch.d2 arch.png                 then READ arch.png with your file-reading tool — you can
                                                     look at an image, and this is the only step that shows
                                                     labels, shapes, key badges and which row an arrow leaves.
                                                     Both writers who skipped it reported the same thing:
                                                     "a PNG read would have answered this"
6. d2 --layout=tala arch.d2 arch.txt && cat arch.txt the deliverable, if it is going in a terminal
7. fix the text; go to 3

最大5ラウンドです。各ステップで異なる問いに答えます。3は「コンパイルできるか」、4は「意図した内容になっているか」、5は「読みやすいか」、6は「掲載先に収まるか」です。コンパイルエラーは1行で表示されます。 arch.d2:2:9: invalid style keyword: "colour"、2:1: connection missing destination のように表示されるので、指定された行を修正します。

完了条件

• d2 validate と d2 fmt --check がどちらも終了コード0で終了する。
• d2 layout に tala (bundled) が表示され、レンダリングにも使用されている。
• d2-facts --expect が終了コード0で終了する。名前の重複やレンダリングの切り詰めがなく、一覧にあるすべてのボックスとエッジが方向指定付きで描画され、禁止されたエッジがなく、幅が予算内に収まっていること。幅は、最終レンダリングで使うものと同じ --seeds を使って測定します。
• PNG を一度確認し、成果物の1つとして含める。
• 説明文にあるすべてのシェイプと接続が ID で指定され、説明文にあるすべての ID がファイル内に存在する。
• .d2 を SVG と同じ場所にコミットする。SVG はビルド出力にするか、.d2 の隣にコミットします。貼り付けただけの状態にはしません。

幅：ターミナルでの見え方に合わせて測定する

LC_ALL=C.UTF-8 wc -L arch.txt      # 122 — correct, and CJK-aware
wc -L arch.txt                     # 120 in the C locale: an undercount, and 87 vs 111 on a Japanese figure
awk '{if(length($0)>m)m=length($0)}END{print m}' arch.txt   # 338 — BYTES. Never this.

d2-facts.mjs は columns と同じ数値を出力します。引用するのはこちらの数値です。 2 人の執筆者がそれぞれ独立して過小カウントに遭遇しました。そのうち 1 人は、すでに予算内に収まっていたレンダリングを縮小するために、1 ラウンドを費やしました。

調整手段によって結果が単調に変化するわけではありません。毎回、測定してください。 同じラウンドで、異なる 2 つの図を測定した結果です。

調整手段	図 A	図 B
ルートの direction: right → down	144 → 145（悪化）	148 → 109（改善）
ラベルを短くする	144 → 146（悪化）	109 → 135（悪化）
最も要素の多いコンテナに direction を設定	146 → 113（改善）	—
--tala-seeds 4,5,6	113 → 100	12 セットのシードを試しても変化なし
1 つの図形に top / left を指定	113 → 74	102 → 75

つまり、まずルートの direction を設定し、次に最も多くのボックスを含むコンテナ自身の direction を設定してください。これは最後ではなく、最初に試すべきことです。それぞれの設定後に再測定してください。TALA は図全体を再配置するため、ラベルを短くすると幅が広がることも同じくらいよくあります。--scale はテキストのレンダリングにまったく影響しません。これらは sequence_diagram には当てはまりません。sequence_diagram は自動でレイアウトされるため、調整できるのはラベルの長さだけで、幅はどちらの方向にも 1～2 列変わる程度です。

回避策には、次の 2 つの注意点があります。

• コンテナごとの direction は無視されることがよくあります。 2 つのコンテナに設定しても、バイト単位で同一のレンダリング結果になりました。最も要素の多いコンテナでは、幅が 33 列変わりました。TALA は、コンテナ内部の流れが曖昧な場合に限って、この設定を尊重するようです。
• top / left の単位は列ではなく SVG のピクセル数で、両方を同時に設定する必要があります（TALA のみ）。幅 100 列の図では、ターミナルの 1 列あたり約 11.5px ですが、これを使った執筆者はみな、3～5 個の値を試して数値を見つけていました。位置が重要な 1～2 個の図形に固定位置を指定し、その理由をコメントに残してください。次にラベルを変更したら、固定位置を再調整する必要があると考えてください。
• 固定位置の指定によってターミナルでのレンダリングが切り詰められ、それが改善に見えることがあります。 ある執筆者がテーブルの位置を固定したところ、幅が 113 → 71 に減りました。しかし、その数値は断片的なものでした。固定位置によって図形が ASCII キャンバスの外にはみ出し、SVG は大きくなった一方で、テーブル 5 つのうち 3 つがテキスト表示から消えていたのです。この状態でも d2 は終了コード 0 を返します。d2-facts はこの状態をエラーとして報告するようになりました。固定位置を指定した場合は、レンダリング結果を読み直してください。
• 固定位置を指定しなければ、予算を達成できない場合があります。 5 つの sql_table では、文書化されている調整手段を使っても 100 列未満になりませんでした。direction: down で 113 列、ラベルを短くして 127 列、折り返し用のコンテナで 121 列となり、さらに小さくできたのは安全でない固定位置の指定だけでした。その場合は、コンテナごとに図を 2 つのファイルへ分割するか、図を広いままにして、ターミナル版は 113 列だと本文で説明してください。読み直していない固定位置の指定で数値を小さく見せてはいけません。

ターミナル表示の読み方

0.8.1-HEAD で計測しています。ここでは構造を確認し、ラベルと図形は PNG で確認してください。

• エッジラベルは線の上に書き込まれ、その空白は線の文字になります（vlmkit check integrity─page─html、201─Created）。ターミナル表示向けのエッジラベルは、1〜2 語にしてください。
• 接続スタイルはすべて失われます。 stroke-dash、stroke、bold は通常の線として表示されます。ある書き手がスタイル付きの表示とスタイルなしのコピーを比較したところ、まったく同じでした。破線で非同期を示す方法は残らないため、その違いはラベルに含めてください。
• ラベルが長いと矢印の先端が正しく表示されません。 レーンいっぱいになるほど長いラベルでは矢印の先端が完全に消えることがあり、ラベル内の << もそのまま消えます。どの文字が線に吸収されるかも一定ではありません。同じファイルで、あるときはラベルの括弧が、次のときはピリオドが消えました（order.placed → order─placed）。最終的に使う表記を試し、句読点のない短い単語を 1 つ使うのがおすすめです。
• shape: text と |md …| ブロックは空のボックスとして表示されます。 タイトル、凡例、段落は、表示の周囲の本文に含めるか、SVG のみを出力するファイルのバリエーションに含めてください。
• sql_table の行は表示されますが、制約バッジは表示されません。 PK / FK マーカーは SVG / PNG でのみ確認できます。また、列レベルのエッジはテキスト表示で誤った行に接続されることが多く、その表示から読み取ることはできません。
• エッジラベルがボックスやコンテナの境界線に重なることがあります（┌────sync call────┐│）。ボックスが 2 つつながったように見えます。重なる位置は長さではなく位置関係で決まります。接続がすでにルートにあったある書き手は、ラベルを短くしても長くしても、同じ幅のまま同じ境界線の行に表示されました。位置を変えられるのは、コンテナの direction や別のシード値など、図の再配置を引き起こす要素です。そのため、ラベルを短くするのではなく、PNG で確認するレイアウト結果として扱ってください。
• CJK ラベルでは各文字に空白が追加され（ウ ェ ブ）、ラベルを囲むボックスの配置がずれます。ID は常に ASCII にしてください。ターミナルで読む図ではラベルも ASCII にし、日本語は周囲のテキストに記載してください。SVG と PNG では日本語は正しく表示されます。
• standard モードでは、同じレイアウトを + - | / < > v のみで表示します。これは、コードブロック内の罫線文字の表示が閲覧者のフォントに左右される GitHub で README を読む場合向けのバージョンです。
• アイコンと画像は表示されません。シーケンス図、sql_table、class の図形は、その行も含めて表示されます。

書き手が守るルール

• ID は ASCII で安定したものにし（API server ではなく api）、ラベルはコロンの後に記述します。ID の省略は問題ありません。d2-facts はラベルでも一致しますが、次の編集者はまず ID を読みます。
• コンテナをまたぐ接続はルートに記述するか、_. を使います。 _ は 1 階層を表します。cluster 内から見るとルートは _ なので、兄弟コンテナ内の図形は _.outside.stripe のように指定します。スコープ外の名前をそのままにしないでください。新しいボックスになってしまいます（上記を参照）。
• ルートの direction は 1 つだけにします。逆方向に配置する必要があるコンテナでは、そのコンテナ独自の direction を設定します（TALA のみ対応し、反映されるのも場合によります）。
• 接続は文のように読み取れる形にします。a -> b: verb。-- は無向、<-> は双方向です。接続に設定したスタイル（{style.stroke-dash: 3}）はターミナルでは表示されません。違いが重要な場合はラベルに記載してください。
• すべてのファイルの先頭に vars: { d2-config: { layout-engine: tala } } を記述し、フラグなしで表示した場合も SVG で TALA が使われるようにします。
• 図形の位置を固定する必要がない限り、座標は指定しないでください。固定する場合は、その図形にのみ top と left の両方を指定し、理由をコメントで説明してください。

提出物

• チャットの場合：フェンス付きブロック内のターミナルレンダリング（ターミナル内の画像です）、本文で指定した ID、.d2 ファイルと PNG / SVG ファイル（利用可能な場合は SendUserFile を使用）。
• PR または issue の場合：フェンス付きブロック内の standard レンダリング、またはコミットしてリンクした SVG。diff 内の .d2 がレビュー対象です。
• ドキュメントの場合：ページの隣にコミットした .d2 ファイルと、ビルドで生成した SVG（スクリプト内で d2 --layout=tala docs/arch.d2 docs/arch.svg を実行）、またはサイトにビルド手順がない場合はコミットした SVG。

失敗時の対処

• d2: command not found → インストールしてください（上記参照）。別のツールで描画しないでください。
• d2 layout に tala が表示されない → 古いリリースです。アップグレードしてください。インストーラーの --tala フラグは廃止され、指定すると拒否されます。
• ボックスが二重に表示される、または記述した矢印が見当たらない → スコープ外の参照によってファントムが作成されています。d2-facts で名前を確認できます。修正には完全なパスか _. を使い、別の矢印を追加しないでください。
• テキストのレンダリングが dagre 風で横長になったのに、ファイルには layout-engine: tala と書かれている → 一部のビルドでは .txt のパスがファイル内の設定を無視します。--layout=tala を指定してください。
• "tala-seeds" needs a value / is not a valid config → seeds はフラグとしてのみ指定できます。
• connection missing destination、maps must be terminated with } → 該当する行と列が示されています。通常は末尾の ->、または閉じられていない波括弧が原因です。
• invalid style keyword → D2 で使えるキーワードは color、stroke、stroke-dash、fill、font-size、bold、opacity、shadow、3d、multiple です。
• ラベルを 1 つ変更しただけなのに、毎回ボックスの位置が変わる → TALA が再配置しました。位置が重要な図形だけ固定するか、位置の説明をやめてそのまま受け入れてください。
• 2 つのボックスが接しているように見えて判別できない → d2-facts は兄弟要素間の重なりを px² 単位で報告します。D2 自体には衝突レポート機能がありません。

assets/vlmkit-workspace.d2 は vlmkit のワークスペース（mizchi/vlmkit）を D2 ファイルで表したもので、assets/vlmkit-workspace.txt はその TALA ターミナルレンダリングです。適切に整った状態の例です。上記の数値を生成した検証ラウンドは tests/d2/fixtures/d2-scenario/ と docs/reports/2026-09-14-d2-diagram-v1.md にあります。