figure

図

このリポジトリのドキュメントページでは、手描き風の図で仕組みを説明します。 標準の形式は .mdx に直接記述するインライン SVG です。--jd-fig-* CSS 変数のみで描画するため、カラーモードの違いにかかわらずそのまま使えます。 このファイルの終盤では、HTML 図という別の選択肢も紹介します。

このファイルは索引です。図の形状の選び方と、すべての図に共通するルールを説明します。 各形状のレイアウト文法は references/forms/ にあり、形状ごとにファイルが分かれています。形状を選んだら該当ファイルを読み込み、すべてを一度に読み込むことはありません。 描画の技術は Claude Code に付属するスキルから得られ、最初の SVG の行を書く前に Skill ツールで読み込みます。

パレットは、プロジェクトのテーマをもとに調整した 13 個のトークンで構成されます。

トークン	用途
--jd-fig-ink	ラベル。foreground を使用
--jd-fig-muted	サブラベルや控えめなテキスト。ミュートされた前景色を使用
--jd-fig-line	ボックスの輪郭線や接続線
--jd-fig-line-soft	極細の線、区切り線、最も薄い輪郭線
--jd-fig-surface	ボックスの塗りつぶし
--jd-fig-accent、--jd-fig-accent-soft	図の主題となる 1〜2 個の要素。primary を使用
--jd-fig-p-ink、--jd-fig-p-bg	1 番目の色相。chart-1 を使用
--jd-fig-d-ink、--jd-fig-d-bg	2 番目の色相。chart-2 を使用
--jd-fig-i-ink、--jd-fig-i-bg	3 番目の色相。chart-3 を使用

図、チャート、それとも編集用イラスト

このスキルで描くのは図です。仕組みを構成する要素とそのつながりを、サイトの図用パレットに合わせて標準化して表します。ほかに、次の 2 つのスキルがあります。

• 実際の数値を示す棒、折れ線、面、円、またはレーダーチャートは、<Chart /> ブロックです。 chart スキルを使ってください。
• 雑誌が記事を開くように、各ページの冒頭を飾る絵は編集用イラストです。 editorial-illustration スキルを使ってください。このスキルは独自のスタイルで、ページ内ではなく専用の SVG ファイルに描画し、以下のルールには従いません。図は説明を担う章の中に配置します。

読み込む組み込みスキルを選ぶ

以下で決めた形状に応じて、すべてではなく 1 つを読み込んでください。

形状	読み込むスキル	対象
あらゆる仕組み：ボックスと矢印、フロー、階層、タイムライン	artifact-diagramming	図を使う価値がある場面、実際の仕組みの描き方、矢印のラベル付け
あらゆるチャート	dataviz	チャートの選び方、必要最小限のマーク、軸とラベルのルール、色の組み立て方
実際のタイポグラフィを使う HTML 図	frontend-design（プラグイン。常にインストールされているとは限りません）	テンプレート的に見えない文字、余白、レイアウトの選択

artifact-design、artifact-capabilities、design は読み込まないでください。これらは Artifact ページ全体を対象としています。 利用できるほかのビジュアルスキルは、自由に読み込んでかまいません。 それらの仕組みは単独のページを対象としているため、data-theme、currentColor、CDN、ページレイアウトに関する記述は無視してください。 引き継ぐのは描画に関するアドバイスだけです。マークアップと色はここで決めます。

まず形状を選ぶ

図を添える段落を読み、何について説明しているかを確認してください。 次に、表から該当するものを探します。 どの行を検討する場合でも、その前に簡単な基準で確認してください。文や 3 列の Markdown テーブルで同じ内容をすばやく伝えられるなら、そちらを書きます。

表の行は候補であって、最終判断ではありません。 長方形を配置する前に、該当するファイルを開き、先頭にある適用条件を読んでください。 その条件を満たさない形状は、表の行がどれほど適切に見えても誤りです。 「仕組み」表の最後の行は、実際に選べる行き先であり、妥協案ではありません。そこに行き着いても、分類に失敗したわけではありません。 複数の形状が同じファイルを共有している場合もあるため、開くファイルは参照列で確認してください。

Mermaid または図

ここで描画するもう一つの方法は```mermaidフェンスです。リポジトリのルールもすでに定められています。人が保守する決定論的な参照図には Mermaid、文章の横に添えるイラストには図を使います。ほぼ常に前者に該当する形式が4つあります。内容が後で編集されるデータセットだからです。ガントチャート、カンバンボード、ER図またはデータベーススキーマ、クラス図です。これらの行はフェンスを参照しており、フォームファイルはありません。それ以外は、どちらに該当するかを確認してください。APIを規定するシーケンスはフェンスです。キャッシュがある理由を説明する3者間のシーケンスは図です。

メカニズム

文章のテーマ	形式	参照
システムのコンポーネントと、どの組み合わせが接続されているか	何が何と通信するか	forms/what-talks-to-what.md
ソフトウェアの実行場所：ホスト、ゾーン、レプリカ、バージョン	デプロイメント	forms/what-talks-to-what.md
ソース、コア、コンシューマーを含むエンドツーエンドのデータプラットフォーム	プラットフォーム統合	forms/what-talks-to-what.md
レガシー環境、移行前の状態	現状	forms/what-talks-to-what.md
分岐のある判断、「すべきかどうか」	フローチャート	forms/flowchart.md
アクター間のメッセージを時間順に示すもの、リクエストのトレース	シーケンス	forms/sequence.md
状態と、あるものを状態間で遷移させるもの	ステートマシン	forms/state.md
リリース、マイルストーン、インシデントなど、時間上に配置されたイベント	タイムライン	forms/timeline.md
チームや役割間の引き継ぎを伴うプロセス	スイムレーン	forms/swimlane.md
同じプロセスを、各ステップが消費・生成するものとともに示すもの	プロセス	forms/swimlane.md
抽象化レベルの積み重ね、スタック、カスケード	レイヤースタック	forms/layers.md
品質レベルごとの、1つのデータセットのストレージ層	メダリオン	forms/layers.md
包含関係によるスコープ、信頼ゾーン、影響範囲	ネスト	forms/nested.md
親から子へ続く分類体系、ファイルツリー	ツリー	forms/tree.md
所有者、ルーティング、エスカレーション	組織図	forms/tree.md
共有依存関係や循環を含む、依存関係	依存関係グラフ	forms/dependency.md
最後のステップが最初に戻り、ハブが状態を保持する循環	ループ	forms/loop.md
エンティティ、フィールド、カーディナリティ、または実際のテーブルと外部キー	ER図、スキーマ	a ```mermaid fence, erDiagram
クラス、継承、コンポジション、操作	UMLクラス図	a ```mermaid fence, classDiagram
コミット、ブランチ、マージ	Gitグラフ	a ```mermaid fence, gitGraph
これらの名前のどれにも当てはまらないメカニズム	文章に記述されたものを描画する	ファイルなし。以下のルールを参照

比較と位置

文章のテーマ	形式	参照
2つの軸、優先順位付け、2x2	クアドラント	forms/quadrant.md
2つまたは3つの概念が重なる部分	ベン図	forms/venn.md
順位付けされた階層、またはコンバージョンの離脱	ピラミッドまたはファネル	forms/pyramid.md
バリューチェーンと各部分のコモディティ化の度合い	ウォードリーマップ	forms/wardley.md
役割別、コンポーネント別の権限	アクセスマトリックス	マークダウンテーブル

作業と人

文章のテーマ	形式	参照
各段階で人が行うことと、そのときの感情	ユーザージャーニー	forms/journey.md
リリースごとに区切られた、物語の骨格	ストーリーマップ	forms/story-map.md
1つの結果をもたらす原因を、カテゴリ別に分類したもの	フィッシュボーン	forms/fishbone.md
フェーズごとに開始日と終了日があるタスク	ガントチャート	a ```mermaid fence, gantt
状態ごとの進行中の作業、WIP制限、ブロックされた項目	カンバン	a ```mermaid fence, kanban

数値

チャート自体には dataviz を読み込みます。段落中の数値に関する3文は、次のいずれかの形式にするべきです。シンプルな棒、折れ線、面、円、レーダーチャートは chart スキルの <Chart /> ブロックで作成します。このブロックでは表現できない形式が必要な場合、または対応できない注釈が必要な場合に限り、ここで描画してください。

文章の内容	形式	参照
変化した値、カテゴリごとの数量、または順位	棒グラフ	forms/bar.md
各項目の値がちょうど2つで、その差が主題となるもの	ドットプロット	forms/bar.md
開始合計から符号付きの段階を経て終了合計に至るもの	ウォーターフォール	forms/waterfall.md
時系列の傾向	折れ線グラフ	forms/line.md
各項目について、2つの時点間での変化	スロープグラフ	forms/line.md
複数のスナップショット間での順位の推移	バンプチャート	forms/line.md
系列ごとに1つの分布	リッジライン	forms/line.md
2つの変数：相関、クラスター、外れ値	散布図	forms/scatter.md
3つの変数：x、y、量	バブルチャート	forms/scatter.md
1つの変数、項目ごとに1つのドット	ビースウォーム	forms/scatter.md
段階間で分割・統合される数量	サンキーダイアグラム	forms/sankey.md
全体の一部で、相対的な大きさが主題となるもの	ツリーマップ	forms/treemap.md
3〜5つの基準で評価した複数の対象	レーダーチャート	forms/radar.md
循環順序が重要なカテゴリにわたる1つの系列	極座標チャート	forms/radar.md

マークアップ

<figure className="jd-fig">
  <div className="jd-fig-frame">
    <svg viewBox="0 0 960 240" role="img" aria-label="One sentence describing what the figure shows">
      ...
    </svg>
  </div>
  <figcaption>The takeaway.</figcaption>
</figure>

フレームワークの jd-fig クラスが、枠、幅、狭い画面での縮小、および <text> の等幅フォントを処理するため、図自体でこれらを指定する必要はありません。

SVG 図のキャプションはページ上には表示されません。スクリーンリーダーと検索エンジンはキャプションを読み取り、読者が図を展開すると描画の下に表示されます。そのため、図の周囲の文章で要点を伝え、キャプションでは図だけを見る読者向けに要点を言い換えます。HTML 図は展開できず、キャプションは表示されたままになります。

ルール

• 色にはすべて var(--jd-fig-*) を使用します。 塗りつぶしも線も同様です。各トークンはプロジェクトのテーマから派生します。ニュートラルカラーはシェルから、アクセントは primary から、p、d、i の色相は chart-1 から chart-3 から取得します。図で独自の色を指定することはありません。
• これは JSX です。 属性はキャメルケースにします：fontSize、strokeWidth、strokeDasharray、textAnchor、markerEnd、letterSpacing。& は & としてエスケープします。コメントは {/* ... */} です。
• ラベルも Markdown として扱われます。 <text> 内の _category_.json は SVG 内で <em> に変換され、ブラウザーがそれを外に移動します。すると React は自身が送信していないツリーを見つけ、ページは破棄されてクライアント側で再描画されます。ラベル内の強調はエスケープする（\_category\_、\*）か、強調なしで単語を書いてください。単語の前のコロン（11:04:07）も同じ問題を起こしますが、こちらはフレームワークがすでにテキストとして復元します。
• マーカー ID はページ全体で共有されます。 ページ上のすべての図は1つの DOM を共有するため、図ごとに <marker> の ID に接頭辞を付け（lk-arrow、lk-arrow-accent）、図をまたいで arrow を再利用しないでください。
• 4px グリッド。 すべての x、y、幅、高さ、半径、間隔は4の倍数にします。1、2、3、5、6、7、9で終わる座標は誤りです。線幅とフォントサイズは対象外です。
• viewBox の幅は960です。 描画に合わせて高さを選び、無駄な余白を残さないでください。
• 文字のサイズ体系。 ノードラベルは12（名前には fontWeight="600"）、注釈と矢印ラベルは10、サブラベルは opacity="0.75" を指定して9.5にします。すべて大文字の小見出しと帯のタイトルは fontSize="10" letterSpacing="1.5" とします。writing-mode による縦書きは使わず、単語を行ごとに分けて積み重ねてください。
• アクセントを付けるのは1つ、多くても2つまでです。 --jd-fig-accent は、図の主題（追加するホップ、読者に注目してほしい状態、説明対象の経路）を示します。4つの要素にアクセントが必要なら、図の主題を決められていません。それ以外にはインク、ミュートカラー、レイヤーの色相を使います。

ノードの役割

形状と線で役割を示します。役割で指定されていない限り、塗りは控えめにします。

役割	塗り	線
図の中心となる1つまたは2つ	accent-soft	accent、strokeWidth="1.5"
ステップ、サービス、コンポーネント	surface	line、または図にレイヤーがある場合はレイヤーのインク色（p-ink、d-ink、i-ink）
ストア、静止状態、ファイル、レコード	レイヤーの背景色（p-bg、d-bg、i-bg）、またはレイヤーがない場合は line-soft	コンポーネントと同じ
管理対象外のもの：ベンダー、ブラウザー、サードパーティ	surface	line-soft、ラベルは muted
オプション、非同期、常に存在するとは限らないもの	surface	line、strokeDasharray="4 3"
ゾーン、境界、グループ	なし	line-soft、rx="8"、左上隅の内側に小見出しラベル

ノードは <rect rx="4"> です。

ゾーン

ゾーンは、階層、所有者、環境、または信頼境界を共有するノードをグループ化します。どの形式でも使用できます。いくつかの形式では使用しています。

• 塗りなし、線は line-soft の <rect rx="8"> を、ほかの要素より先に描画します。これにより、矢印やラベルがその上に配置されます。境界がグループではなくネットワークや信頼の境界（VPC、セキュリティグループ、環境など）の場合は、破線（strokeDasharray="4 4"）にします。
• 左上隅の内側に小見出しラベルを配置し、fontSize="10" letterSpacing="1.5"、色は muted にします。ラベルとその下にある最初のノードとの間には、16pxの余白を空けます。
• 最大3つまでにします。3つを超えるとスイムレーンのように見えるため、代わりにスイムレーンを描きます。
• ゾーンはノードではなく、矢印も持ちません。ゾーン内のノード同士をつなぎ、共通点はゾーンで示します。

コネクター

まずゾーンを描き、次に矢印、矢印のラベル、ノード、ノード内のテキストの順に描きます。 矢印の後にボックスを描くと、矢印のはみ出した部分が隠れます。ノードより先にラベルを描く場合は、ノードに覆われないよう、キャンバス上の空いている場所に置く必要があります。

ストロークの色ごとにマーカーを1つ定義し、図ごとにIDの接頭辞を付けます。

<marker id="lk-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
  <path d="M0,0 L10,5 L0,10 z" fill="var(--jd-fig-line)" />
</marker>

線	意味
実線のline、strokeWidth="1.5"、塗りつぶしの矢印先端	主なフロー、呼び出し、データの移動
実線のaccent、strokeWidth="1.5"、accentの矢印先端	図が焦点を当てる経路
破線のmuted、strokeDasharray="4 3"、strokeWidth="1"、塗りつぶしの矢印先端	戻り、二次的なフロー、任意のもの
破線のmuted、開いた矢印先端（fill="none"、マーカー内のストローク付きパス）	非同期、イベント、一方向の通知
矢印先端のない単純なline	方向のない関係、細線

ファイルで例外（データ曲線、サンキーリボン、ループの円とスポーク、フィッシュボーンの骨、Wardleyリンク）が明記されていない限り、すべての形式に次の6つのルールを適用します。

1. 直角に曲げ、角は丸めます。 <line>で結べるのは、x座標またはy座標を共有する2点だけです。それ以外は、半径8の4分の1円弧の角を持つ折れ線にします。(200,120)から(400,200)へ、x 300で曲がる右・下方向の例：

   <path d="M 200,120 H 292 Q 300,120 300,128 V 192 Q 300,200 308,200 H 400"
     fill="none" stroke="var(--jd-fig-line)" strokeWidth="1.5" markerEnd="url(#lk-arrow)" />
   

   破線も同じ経路をたどります。破線は線の意味を示すものであり、線の進み方を示すものではありません。
2. ラベルはストロークから6〜10px離し、決して重ねません。 セグメントの中央に配置し、水平線ならその上、垂直線ならその横に置きます。ラベルは最大3語です。マスキング用の長方形は使いません。ラベルはキャンバス上の空いている場所に置き、十分な余白がなければ図の情報量が多すぎます。
3. 複数のコネクターで同じ経路を共有しません。 平行に走る線は、始点から終点まで12px離します。交差が避けられない2本のうち、重要度の低い方を小さな弧で飛び越えさせ、弧を付けるのは片方だけにします。コネクターを重ねて配置する必要があるなら、2つのノードが近すぎます。
4. ボックスの辺を共有するコネクターには、それぞれ専用の接続点を設けます。 長さLの辺に沿って、N本中k本目の接続点をL · k / (N + 1)に配置し、間隔は12px以上にします。
5. コネクターは、始点でも終点でもないボックスの背後を通りません。 経路を変更してください。例外は、フッターバーなど、ボックスが物理的に唯一の直線経路上にある場合です。この場合、線は破線にし、ラベルは見えている端に配置して、交差するボックス上に矢印先端が重ならないようにします。
6. 後から描くボックスに隠れる場所にラベルを置きません。 自分のノード内に置くバッジは問題ありません。ゾーンは先に描画されるため、その上にラベルを置いても問題ありません。

チャート

• プロット領域はviewBox="0 0 960 480"内のx 80〜920、y 40〜420とし、左側の軸の値と下側のカテゴリ名のための余白を確保します。
• line-softとstrokeWidth="0.8"でグリッド線を4〜6本引き、軸線にはlineを使います。軸の値はfontSize="10"、mutedとし、x 72で右揃えにします。カテゴリ名はfontSize="12" fontWeight="600"にします。
• 焦点となるマークを1つ、アクセントカラーで示します。それ以外のマークはline-softで塗りつぶし、mutedのストロークを使います。
• マーク上の値はfontSize="10"にします。同じ表現が繰り返される場合に限り凡例を付け、その場合はプロットの下に、上部に細線を引いた帯として配置します。
• 大きさを表す軸はゼロから始めます。キャプションではマークが何を表すかを説明し、本文では数値の出典を説明します。

HTML 図

SVG を優先してください。実際のテキストの折り返し、長いリスト、図として装飾した比較表など、特定の種類の図で SVG より HTML のほうが適している場合に限り、HTML を使用してください。インタラクティブなものはページの範囲を超えます。ページではコードを実行できないためです。

HTML 図では同じ jd-fig ／ jd-fig-frame ラッパーを使い、図の中にある <style> タグでスタイルを設定します。MDX は { ... } を JSX 式として解析するため、CSS はテンプレートリテラルの子要素にする必要があります。そうしないとビルドに失敗します。

<figure className="jd-fig fig-checkout">
  <style>{`
    .fig-checkout .step { background: var(--jd-fig-surface); border: 1px solid var(--jd-fig-line); }
    .fig-checkout .step.active { background: var(--jd-fig-d-bg); color: var(--jd-fig-d-ink); }
  `}</style>
  <div className="jd-fig-frame">
    ...
  </div>
  <figcaption>...</figcaption>
</figure>

• 図の一意な fig-* クラスの下に、すべてのセレクターをネストしてください。.step のようなクラス名だけでは、ページの表示中はグローバルに適用され、テーマの要素のスタイルまで変えてしまいます。
• 色には引き続き --jd-fig-* トークンのみを使用してください。リポジトリ内のほかの場所と同様、インラインの style 属性は禁止です。
• ページ内に <style> タグを置けるのはここだけです。図のスタイルを新しい prose-block クラスに移してはいけません。記事の本文はプレーンな Markdown にしてください。

図の心得

図は特定の本文に添え、優れた教育者がホワイトボードに描くように、その本文で説明しているものを示します。比喩ではなく、描き方を工夫してください。段落に書かれていることと、何が変化しているかを図解します。

• 章の段落、コード、図は織り交ぜて配置します。図は周囲の段落で扱う概念を示します。
• 図ごとにアイデアは一つにしてください。凡例が必要な図は、たいてい二つに分けるべきです。
• 実際の仕組みを描いてください。ボックスは実際のコンポーネント、矢印は実際の呼び出しやデータを表し、すべての矢印に何が流れるかを示します。
• 最も効果的なのは、たいてい要素を削除することです。常に一緒に動く二つのノードは一つにまとめます。配置を見れば明らかな関係に線は不要です。ノードが九つを超えるなら、おそらく図を二つに分けるべきです。
• 図の中の語数は20語未満にしてください。詳細は本文に任せ、図は見て理解するためのものです。

描く前に計画を伝える

最初の SVG の行を書く前に、返信で一、二文を使って、選んだ形式、その図が何を扱うか（アクセントを付ける要素）、そして予算の都合で省くものがあればそれを伝えてください。読む人がいれば、図を作る手間をかけず、一文で方向を変えてもらえます。

この時点なら、形式の選択を誤っても低コストで修正できます。一方、二十分後に座標を配置し、かけたコストを理由にそのまま使うことになれば、修正には大きなコストがかかります。依頼の中ですでに形式と内容が指定されている場合に限り、これを省略してください。

レンダリングして確認する

SVG はソースを見ただけでは判断できません。ページの図をレンダリングし、画像を確認して、問題を修正したら再度レンダリングしてください。

export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix task)"
bun .agents/skills/figure/scripts/render.ts docs/index.mdx

ページ上のすべての jd-fig をプロジェクトのダークテーマとライトテーマで描画し、PNG のパスを出力します。ページの後に番号を指定すると、その図だけをレンダリングします。agent-browser をインストールしたうえで、リポジトリのルートから実行してください。node でも bun と同じように実行できます。

完了前の確認

• 図は、その形式のファイルで必須とされている要素をすべて含んでいますか？
• 描く前に形式と主張を伝えましたか？ 描いたものは、今もその内容を表していますか？
• 図を読み取れる状態を保ったまま、ノード、矢印、ラベルを削除できますか？
• アクセントが付いている要素は最大二つで、図が扱う内容を示していますか？
• すべての色がトークンで、すべての属性が camelCase で、すべてのマーカー ID に接頭辞が付いていますか？
• すべての座標が 4px グリッド上にあり、コネクターが直角または直線で、ラベルが線やボックスに重なっていませんか？
• 両方のモードでレンダリングし、画像を確認しましたか？
• aria-label は、図形の形状を説明せずに、図が示す内容を一文で伝えていますか？