blueprint-figure

ブループリント図

このスキルでは、実システムの仕組みを説明する静的な SVG 図を 1 つ描きます。図では、システム内で実際に使われている名前（ID、フィールド名、メソッド名、ステータスコード、シーケンス番号）を使います。明るい紙面パネルに配置し、意味を固定した少数の色相を使います。画面上でも印刷でも、幅 640 ユニットで読みやすさを保ちます。SKILL.md を読み込める Claude、Cursor、Codex、OpenClaw、Hermes、または任意のエージェントが使用できます。関連スキルの course-style には、コースで使うトークン一式が収録されています。このスキルは必要なトークンをコピーしているため、単独で動作します。

使用する場面

• レッスン、README、またはマニュアルに、システムの各部がどのように通信し、データを保存し、状態を変更するかを示す図が必要な場合。
• 実際の名前がわかるキャプチャ、ログ、仕様書、またはソースコードがある場合。
• 主張が、以下の 9 種類のいずれかに当てはまる場合。

使用しない場面

• 図を動かしたり、スライダーに反応させたりする必要がある場合。関連スキルの motion-figure を使用してください。
• 対象が、奥行きや操作部を備えた物理機械の解説である場合。関連スキルの isometric-explainer を使用してください。
• データが、多数の点にわたる数値のグラフである場合。グラフ作成ツールを使用してください。
• 各部分の実際の名前がわからない場合。まずキャプチャまたはソースを入手してください。

手順

1. まず主張を書きます。図で証明する内容を、最大 28 語の 1 文にまとめます。
2. 以下の表から種類を 1 つ選びます。2 種類が当てはまる場合は、図を 2 つ描きます。
3. ソースから実際の名前を集めます。関係者、フィールド、メソッド、コード、シーケンス番号を確認します。
4. 描画を始める前に、図一式で使用する色相の表を作成します（「色」を参照）。
5. 640 ユニットのグリッド上にレイアウトをスケッチします。内容は x 20 から x 620 の間に収めます。
6. スクリプトで図を描きます。templates/figure.mjs から始めてください。SVG を手作業で編集しないでください。
7. スクリプトを実行します。ラベルが小さすぎる、幅が広すぎる、または図の範囲外にある場合、スクリプトは停止します。
8. references/checks.md のチェックを実行します。指摘事項をすべて修正してください。
9. SVG を PNG に変換し、幅 100％ と 50％ の両方で確認します。
10. キャプションを書きます。太字の主張、図の読み方、出典の順に記載します。

9 種類

種類	用途
sequence	ライフライン上の関係者、下方向に進む時間、番号付きのやり取り
structure	1 つのレコード、オブジェクト、またはスキーマの構造
flow	データが通過する段階と、書き込みを行う側および読み取りを行う側
comparison	1 つの問いに対する 2 つの答えを並べて表示
timeline	コミットシーケンスや時刻など、番号付きの軸上のトラック
tree	所有、包含、または委譲
state	遷移を伴うステートマシン
decision	失敗する箇所と、それぞれの結果が意味する内容
layers	各層が所有する部分を示す、層の積み重ね

各種類のレイアウト数値は references/kinds.md に記載されています。

図に示す内容

• 実際の名前を使って、実際のシステムを示します。「コンポーネント A」のような汎用的なボックスは描かないでください。
• 統計カード、進捗バー、装飾用アイコンは描かないでください。
• 図 1 つにつき主張は 1 つにします。
• 対象の動作を 2 つ比較します。自分のプロジェクトの以前のビルドとは比較しないでください。
• シーケンスでは、キャプチャ内で発生する順に、やり取りに番号を付けます。

色

色相は 10 種類です。grey、blue、teal、violet、green、amber、plum、olive、indigo、rose です。各色相には、インクと塗りつぶしのトークンがあります。同じ図一式では、各色相の意味を統一します。

4 つの意味は固定されています。

色相	固定された意味
rose	失敗：エラー、クラッシュ、中断、作業の消失
grey	対象外：ホスト、オペレーター、対象範囲外
amber	ライフサイクル：タスク、フェーズ、ステートマシン
teal	永続状態：ストレージおよびコミット済みレコード

残り 6 色相は図一式ごとに割り当て、ページまたはマニュアルの前付けに表を記載します。

各色は var(--m-<token>, <light hex>) の形式で記述します。たとえば、var(--m-rose-ink, #b0344d) です。ホストページがダーク値を指定します。README にはライト値の 16 進数を表示します。ライト値とダーク値はすべて references/grammar.md に記載されています。

矢印

スタイル	意味
実線のインク色	呼び出しまたはリクエスト
破線のインク色	応答
実線のティール色	永続的な書き込み
破線のアンバー色	状態の変化
実線のプラム色	モデルの呼び出しまたは計算
破線のオリーブ色	システム外の作用
点線のインディゴ色	ストリームまたはイベント
破線のローズ色	失敗

• 線幅は 1.2 です。破線は 5 4 です。点線は丸い端で 1.5 3.5 です。
• 色相ごとに矢印ヘッドのマーカーを 1 つ使い、id は <figure-id>-head-<hue> にします。
• 各矢印の終端は、対象の境界から 1 単位手前にします。
• セット内の最初の図である図 0.1 には、そのセットで使われる各矢印スタイルを示します。

境界線

• インク色の実線の境界線：通常の要素または状態です。
• 破線の境界線：中断されている、任意である、または存在しないことを示します。
• 二重境界線（3 単位内側に 2 つ目の rect）：終端状態です。
• ハッチングの塗りつぶし：タイムラインバー上の待機時間です。中にテキストを入れてはいけません。

読みやすさのルール

• テキストのサイズは、幅 640 単位で少なくとも 11 単位にします。画面上では 11 ピクセル、印刷時には約 8 ポイントです。
• ボックスのタイトルは 12.5 の太字モノスペース、サブ行は 11 のセリフ、矢印ラベルは 11.5、注記は 11 のセリフにします。
• セリフ体の各行には、独自のフォント指定を含めます。class="m-serif" と font-family="Source Serif 4, Georgia, serif" を指定します。これにより、README 画像でもマニュアルでも、どのページにインラインで配置しても図の見た目が同じになります。
• キッカーは 11、大文字、文字間隔 1.2、インクミュート色にします。
• ラベルに省略記号を使ってはいけません。テキストを重ねてはいけません。ハッチングの塗りつぶしにテキストを載せてはいけません。テキストに線を通してはいけません。
• ラベルが収まらない場合は、引き出し線を付けて外側に置くか、番号付きキーに入れます。フォントサイズを小さくしてはいけません。
• 各矢印ラベルは、パネルの色のノックパッチに配置し、class="m-knock" を指定します。
• ノックパッチは線の後、ラベルの前に描画します。
• ノックパッチは線を隠します。ラベルが収まるべきボックスとして数えてはいけません。
• 配置前にテキストを計測します。モノスペースの幅は 文字数 × サイズ × 0.6、セリフの幅は 文字数 × サイズ × 0.54 です。

技術ルール

• ルート：viewBox="0 0 640 H" とし、H は 760 以下、role="img"、aria-labelledby="<id>-title <id>-desc" を指定します。
• ルートのフォントとインク色：font-family="JetBrains Mono, ui-monospace, monospace" と fill="var(--m-ink, #1a1a1a)" を指定します。セリフ体の行では、上記のとおり独自の font-family を指定します。
• ルートの直接の子要素として、40 文字以上の <title> と <desc> を指定します。
• desc では、すべての要素とやり取りを読み取り順に記述します。
• すべての id は、fig-4-1-head-amber のように図の id で始めます。
• 図の id は、fig-4-1 のように小文字の単語と数字をハイフンでつなぎます。
• references/checks.md に記載された要素と属性のみを使います。
• style、スクリプト、イベントハンドラー、リンク、画像は使用しません。
• transform は <g> の translate() のみ使用します。
• テキスト行ごとに <text> 要素を 1 つ使います。
• ファイルサイズは 40 KB 以下、描画要素数は 450 以下にします。

キャプション

キャプションは SVG の周囲のページに置きます。SVG の中に入れてはいけません。

1. 太字の主張から始めます。1 文で、28 語以内とし、ピリオドで終えます。
2. 「上から下へ読みます」のように、図の読み方を説明します。
3. キャプチャファイルなど、出典を記載します。

マニュアルでは、フェンス付きブロック内に図を宣言します。

```figure
id: fig-4-1
kind: state
title: the task lifecycle
claim: A task ends in one of four terminal states and never leaves one.
caption: Read left to right. Dashed borders are interrupted states. From capture/out/task-states.txt.
```

レッスンや README では、SVG を画像タグまたはインラインで配置し、その下に段落としてキャプションを記載します。

ソースと出力を一緒に保管する

• 図のスクリプトは SVG の隣に保存します。例：figures/src/fig-4-1.js と figures/fig-4-1.svg。
• SVG は毎回スクリプトから生成します。生成後に SVG を手作業で編集してはいけません。
• コミット前にもう一度ビルドし、コミットする SVG がスクリプトの出力と一致することを確認します。

完了前の確認

• 主張は28語以内の1文です。
• すべてのラベルは、ソースにある実在の名称です。「Component A」などは使いません。
• 図は9種類のいずれかです。
• ローズは失敗、グレーは対象外、アンバーはライフサイクル、ティールは永続状態を表します。
• すべての矢印は8種類のスタイルのいずれかを使い、表に記載された意味を表します。
• viewBox の幅は640、高さは760以下です。
• role="img"、aria-labelledby、<title>、40文字以上の<desc>が含まれています。
• すべてのidは図のIDで始まっています。
• すべての色は、正しい16進数カラーコードを使ったvar(--m-<token>, <light hex>)です。
• 11単位未満のテキスト、viewBoxの外にはみ出すテキスト、他のテキストと重なるテキスト、線に交差されるテキストはありません。
• ラベルに省略記号はありません。
• セリフ体の行すべてにfont-family属性があり、ルートにはインクのfillがあるため、図の表示にホスト側のスタイルシートは不要です。
• <g>のtranslate()以外に、style、script、link、image、transformはありません。
• ファイルサイズは40 KB以下です。
• PNGレンダリングは幅50％でも読みやすい状態です。
• キャプションには、太字の主張、読み進める順序、ソースが含まれています。
• コミットされたSVGはスクリプトの出力と一致しています。

ファイル

• references/kinds.md：9種類それぞれのレイアウト数値と、図0.1。
• references/grammar.md：ライト／ダークのトークン、色相の意味、矢印の線、マーカー、テキストサイズと寸法、形状、任意のビート。
• references/checks.md：すべてのチェック項目とそのテスト、使用可能な要素と属性、キャプションのルール。
• templates/figure.mjs：小さな図形キットとsequence図を備えた、自己完結型のNodeスクリプトです。node templates/figure.mjs out.svgを実行するとSVGを書き出し、パスを省略するとSVGを出力します。

AI Engineering from Scratchリポジトリ内では、manuals/_shared/figkit.js（完全版のキット）、manuals/_shared/templates/（種類ごとのスクリプト）、scripts/audit_manuals.js（図のリンター）も参照してください。