| name | diagram-craft |
| description | 報告書・説明文書で図を使うか判断する際、図を設計する際、frontmatter の figures 宣言を書く際に発火する。図トリガー表・定量上限・雛形で「認知負荷を減らす図」を設計する |
図示スキル（diagram-craft）
図は情報を「増やす装飾」ではなく「減らす道具」。1図1メッセージ。
読者がどこを見れば判断できるかを最短にすることだけが図の目的である。
発火条件
- 報告書・説明文書の執筆を開始する時（図プラン判断のため必ず一度発火）
- frontmatter の
figures: 宣言を書く時
- mermaid / SVG / DA 表のいずれかを書く時
§1 図プラン（執筆前・必須）
本文を書き始める前に、図トリガー表（§2）に当てて使う図を決め、frontmatter に宣言する:
figures: [da-table, where-map]
figures: none
figures_reason: <省略理由を 1 行で>
黙って図なしは禁止。省略にも理由 1 行のコストを払う（負の宣言）。
md2html.cjs --lint が宣言-実体一致を双方向に機械検査する: 宣言した図種の実体が本文に無い場合、および本文の mermaid/svg 図が未宣言（none 含む）の場合は exit 1 でブロック。数値列表のみ warning（任意の数値列にバーが自動描画されるため）。
§2 図トリガー表（Visual Decision Guide）
| 状況 | 推奨図 | 使う条件 | 使わない条件 |
|---|
| 選択肢比較 | DA 表＋比例バー (da-table) | 選択肢 2 件以上で判断を求める | 既に選択済みで比較不要 |
| 現在地・影響範囲 | mermaid ツリー＋現在地ハイライト (where-map) | 複数モジュール・複数層（3 領域以上） | 変更ファイル 1〜2 個で単純 |
| 手順・処理順 | mermaid flowchart LR (flow) | 3 ステップ以上 or 分岐あり | 直列 2 ステップ以下 |
| 状態遷移 | mermaid stateDiagram (state) | 状態 3 個以上、戻り・失敗・再試行あり | 単なる成功/失敗のみ |
| システム構成 | SVG (arch-svg) | 境界・責務・外部依存が主役 | mermaid で足りる場合 |
| 原因分析 | mermaid graph TD (flow) | 原因が分岐・階層化 | 原因が 1 つだけ |
| 実装差分・ファイル一覧 | 図にしない（テキスト） | — | 図はソースの劣化コピーになる |
図種選択の優先順位: ①比較→da-table ②状態→state ③手順/依存→flow ④境界/配置→arch-svg ⑤どれでもない→図なし（理由明記）。
§3 設計作法（定量上限）
- 1図1メッセージ: 図の直前に結論を 1 文書く。図はその 1 文を速く理解させるためだけに作る
- 上限: flowchart/graph ノード 7 個以内（最大 10）・分岐 3 本まで・深さ 4 階層まで / stateDiagram 状態 6・遷移 8 以内 / SVG 主役要素 3〜5・色 4 種以内 / DA 表 選択肢 2〜5 × 評価軸 3〜6・スコア粒度 1〜5 または 1〜10 固定
- ラベル: 名詞句・短い動詞句で 12 字前後（最大 18 字）。エッジラベルは条件分岐のみ。図中に説明文を入れない（説明は本文へ）
- 方向: 時間/手順 = 左→右（LR）、階層/原因 = 上→下（TD）。比較は図でなく表＋バー
- 強調は 1 図 1 箇所（現在地・推奨・リスクのいずれか）
- 削る手順: 結論 1 文に直接必要な要素だけ残す → 読者が既に知る前提を削る → 同種要素を束ねる → 8 ノード超なら現在地図と詳細フローに分割 → 本文だけで足りるなら図ごと削除
§4 配色
templates/palette.md の固定パレットのみ使用（ダークテーマ前提・決定論）。
役割区別を厳守: 意味色（推奨・リスク等 = 状態の意味）と、DA バーの値依存グラデ（値の大小位置のみ = 意味中立）は別系統。混用しない。
§5 雛形（templates/ — コピペして使う）
| ファイル | 図種 |
|---|
templates/palette.md | 意味色パレット + classDef 雛形 + バー値グラデ仕様 |
templates/where-map.md | 現在地ツリー |
templates/da-table.md | DA 表（評価軸方向の規約ポインタ付き） |
templates/flow.md | 手順フロー |
templates/state.md | 状態遷移 |
templates/arch-svg.md | 構成図 SVG スケルトン |
§6 図示チェックリスト（10 項）
- この報告に「比較 / 現在地 / 手順 / 状態遷移 / 構成境界」のいずれかがあるか。なければ図は不要
- 選択肢が 2 件以上あり判断・推奨・却下を述べるなら、DA 表＋比例バーを置く
- 影響範囲が 3 領域以上にまたがるなら、現在地図または影響範囲図を置く
- 状態・再試行・失敗・ロールバックを説明するなら flowchart でなく stateDiagram か遷移表
- 図を置く前に、図の結論を 1 文で書く
- ノードは原則 7 個以内（最大 10）、ラベルは最大 18 字
- 図中に長文説明を入れない。説明は本文、関係だけを図に
- 強調箇所は 1 つだけ（色・枠線・太さ）
- 本文の箇条書きを箱に入れただけの図は削除する。削除しても判断速度が落ちない図は不要
- 図を省略する場合は
figures: none + figures_reason: で理由を明記する
§7 不合格条件
- figures 宣言なしで報告書を書き始めた
- 宣言した図種の実体が本文に無い（
--lint exit 1 を放置）
- 1 図に強調が 2 箇所以上ある / 図が本文の箇条書きの焼き直し
- palette.md 外の色を図に使った（決定論・意味色体系の破壊）
