diagram

図表作成スキル（Diagram Skill）

要件を自然言語で説明するだけで、プロフェッショナルな PNG 図表を自動生成し、Markdown ドキュメントに直接埋め込めます。

---

ステップ 1：コンテンツのトポロジーを分析し、表現方法を選ぶ

理念：コンテンツのトポロジー形状によって表現できる図表の種類が決まり、読者と利用シーンによってその中からどれを選ぶかが決まります。 いきなり「これはどの種類の図か」と考えるのではなく、まずコンテンツがどのような形をしているかを見てください。

1.1 コンテンツのトポロジーを識別する

コンテンツを構造形状に基づいて分類します。同じトポロジーが複数の図表タイプに対応することがあります。

トポロジー形状	識別の手がかり	表現できる図表タイプ
線形シーケンス	A → B → C、単一路線、手順、段階、フロー	フローチャート（線形）、シーケンス図、タイムライン、ガントチャート
複数ソースの集約 / DAG	複数の入口・出口、依存関係、リソースの流れ	フローチャート（DAG）、データフロー図、ネットワーク図、サンキーダイアグラム
階層構造	階層、技術スタック、コンテナ化、抽象化レベル	アーキテクチャ図、C4 図
役割間の連携	複数の役割 / システム間 / サービス間のやり取り	スイムレーン図、シーケンス図、C4 システムビュー
エンティティ間の関係	データベーステーブル、オブジェクトの関係、フィールドのマッピング	ER 図、クラス図
状態遷移	ステートマシン、ライフサイクル、並行処理、git ブランチ	状態図、Git Graph
ツリー構造	意思決定、組織、知識の階層、メニュー階層	決定木、組織図、マインドマップ
マトリックス / 多次元評価	多次元の比較、四象限分類、網羅関係	ヒートマップ、レーダーチャート、SWOT、ベン図、ツリーマップ
数値比較	個別の比較、割合、累積増減	棒グラフ、円グラフ、ファネルチャート、ウォーターフォール図
トレンドの変化	時系列、バージョンの変遷、推移	折れ線グラフ、複合グラフ
分布関係	散布、クラスタリング、相関	散布図（バブルを含む）
段階的なタスク管理	カンバン、ToDo、段階の進行	カンバン、ガントチャート
根本原因分析	複数要因への帰属、欠陥の追跡	フィッシュボーン図
ユーザー体験のジャーニー	タッチポイント、感情曲線	ジャーニーマップ

1.2 同じトポロジーの場合、どの図表を選ぶか？

同じトポロジーでも複数の表現方法があります。読者 + 利用シーン + 強調するポイントに基づいて最終的に選択します。

判断基準	選択の傾向
読者が開発者	DAG 型のコンテンツにはフローチャート / データフロー図を優先（情報密度が高い）。サンキーダイアグラムは使わない
読者がレビュー担当者 / 管理職	フローを扱うコンテンツにはサンキーダイアグラム（視覚的インパクト）、階層にはC4 コンテナービューを選ぶ
スライドを使ったプレゼンテーション	視覚的インパクトを重視：サンキーダイアグラム、レーダーチャート、タイムライン、マインドマップ
ドキュメントへの埋め込み	情報密度を重視：フローチャート、ER 図、表形式の構造図
アクションの順序を強調	シーケンス図 > フローチャート
コンテナ化 / 境界を強調	C4 > アーキテクチャ図
層の関係を強調	アーキテクチャ図 > C4
データ比較が主目的	個別の値には棒グラフ、トレンドには折れ線グラフ、割合には円グラフまたはツリーマップ
データの次元が 3 以上	レーダーチャート、ヒートマップ、または散布図
複数分岐の意思決定ロジック	決定木 > フローチャート
単一分岐の線形フロー	フローチャート（線形）

1.3 Mermaid / Graphviz のマークアップ言語を変換する

Markdown に ```mermaid または ```dot のコードブロックがある場合：

1. 図の構造（ノード、エッジ、ラベル、タイプ、グループなど）を解釈する
2. 対応する図表タイプのテンプレートデータ構造にマッピングする
3. 統一されたデザイン仕様で PNG にレンダリングする
4. 元のテキストブロックを画像参照に置き換える

マッピングルール：

ソース形式	キーワード / 構文	マッピング先
Mermaid graph TD / flowchart	ノード + 矢印	flowchart テンプレート
Mermaid sequenceDiagram	参加者 + メッセージ	sequence テンプレート
Mermaid classDiagram	クラス + 関係	class テンプレート
Mermaid stateDiagram	状態 + 遷移	state テンプレート
Mermaid erDiagram	エンティティ + 関係	er テンプレート
Mermaid gantt	タスク + 日付	gantt テンプレート
Mermaid pie	ラベル + 数値	pie テンプレート
Mermaid journey	段階 + 評価	journey テンプレート
DOT digraph	有向グラフ	flowchart / state / class（構造に基づいて判断）
DOT graph	無向グラフ	er / network（構造に基づいて判断）

注意：Mermaid / Graphviz ツールを呼び出してレンダリングするのではありません。Claude がマークアップ言語で記述された図の構造を理解し、独自のテンプレートデータに変換して、統一されたデザイン仕様でレンダリングします。これにより、すべての図表でスタイルが統一されます。

1.4 图表类型 → 布局/规范索引

1.1-1.2 决定用哪种图表后，下面这张表是布局策略和专属规范的检索入口——不是"内容→选类型"的决策表（决策已在 1.1-1.2 完成）。

图表类型	典型场景	布局策略	专属规范
流程图（线性）	工作流程、决策逻辑（单路径）	手动布局	references/diagrams/flowchart.md
流程图（DAG）	多源汇聚、资源流转、关系图	ELKjs	references/diagrams/flowchart.md
泳道图	多角色协作流程	手动网格	references/diagrams/swimlane.md
时序图	API 调用、消息交互	自定义顺序堆叠	references/diagrams/sequence.md
架构图	系统分层、技术栈	手动层堆叠	references/diagrams/architecture.md
ER 图	数据库表结构	ELKjs	references/diagrams/er.md
类图	面向对象设计	ELKjs	references/diagrams/class.md
状态图	状态迁移	ELKjs	references/diagrams/state.md
网络图	网络拓扑	手动分层	references/diagrams/network.md
决策树	选型决策	树形布局	references/diagrams/decision-tree.md
数据流图	数据管道	手动分层	references/diagrams/dataflow.md
C4 图	C4 系统视图	手动分层	references/diagrams/c4.md
思维导图	知识结构	双侧树形	references/diagrams/mindmap.md
甘特图	项目排期	日期轴网格	references/diagrams/gantt.md
时间线	发展历程	纵向列表	references/diagrams/timeline.md
组织结构图	组织架构	树形	references/diagrams/orgchart.md
SWOT 图	优劣势分析	卡片四象限	references/diagrams/swot.md
鱼骨图	根因分析	鱼骨骨架	references/diagrams/fishbone.md
文氏图	集合关系	圆形交叠	references/diagrams/venn.md
旅程图	用户体验	卡片横向	references/diagrams/journey.md
柱状图	离散对比	笛卡尔坐标	references/diagrams/bar-chart.md
折线图	趋势变化	笛卡尔坐标	references/diagrams/line-chart.md
饼图	占比构成	径向	references/diagrams/pie-chart.md
雷达图	多维评估	径向	references/diagrams/radar-chart.md
热力图	矩阵数据	网格	references/diagrams/heatmap.md
桑基图	流量路径	流带分层	references/diagrams/sankey.md
散点图	分布关系	笛卡尔坐标	references/diagrams/scatter.md
矩形树图	数据占比/层级面积	Squarified	references/diagrams/treemap.md
柱线混合图	柱状+折线混合	笛卡尔双 Y 轴	references/diagrams/combo.md
Kanban	项目管理/任务看板	竖列卡片	references/diagrams/kanban.md
Git Graph	Git 分支工作流	横向分支线	references/diagrams/git-graph.md

---

第二步：读取规范，生成图表

2.1 规范体系

• 公共规范 references/design-system.md — 配色、字体、组件、间距
• 公共工具 references/diagram-utils.md — SVG 工具函数、文字测量、碰撞检测
• 专属规范 references/diagrams/<type>.md — 每种图表的数据结构、布局规则、渲染细节

2.2 布局策略

图表布局分两种：

ELKjs 自动布局（ER图、类图、状态图、流程图 DAG 模式）：

• 引用 lib/elk.bundled.js
• 定义 ELK 图结构（nodes + edges）
• elk.layout(graph).then(result => { /* 渲染 */ })
• 注意：ELKjs 是异步的，所有渲染代码放在 .then() 回调里

手动布局（流程图、泳道图、架构图、时序图等）：

• 根据图表类型的领域规则计算坐标
• 流程图：主路径向下，"否"分支向右
• 泳道图：列 × 行网格，泳道固定行序
• 架构图：预定义层级从上到下堆叠
• 时序图：参与者横排等距，消息纵向堆叠

2.3 生成流程

1. 读取专属规范 → 了解数据结构和布局规则
2. 定义数据（nodes/edges/steps/tables 等）
3. 计算布局坐标（ELKjs 或手动）
4. 渲染 SVG（节点 → 连线 → 标签，按层级顺序）
5. 写入 HTML 文件（含内联 JS + CSS）
6. 用 capture.py 截图 → PNG（禁止手动调用 Playwright）

2.4 HTML 模板结构

所有模板遵循统一结构：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body {
    font-family: -apple-system, system-ui, 'PingFang SC', sans-serif;
    background: #ffffff;
    padding: 24px;
    display: inline-block;  /* 关键：画布收缩包裹内容 */
  }
</style>

<script src="lib/elk.bundled.js"></script>
</head>
<body>
<svg id="canvas"></svg>
<script>
(function() {
  // 1. 数据定义（title, subtitle, nodes, edges 等）
  // 2. 主题定义（colors, fonts, spacing）
  // 3. 工具函数（el, measureText）
  // 4. 布局计算（ELKjs 或手动）
  // 5. 渲染（背景层 → 连线层 → 节点层 → 标签层）
})();
</script>
</body>
</html>

2.5 标题规范

标题默认行为取决于调用场景——但记住：标题、副标题、顶部标签条、底部图例、节点 icon 等都是可叠加的独立组件，不是"评审级必备"。完整组件清单和触发条件见 references/diagrams/review-grade.md。

调用场景	默认行为
用户直接请求画图	标题 + 副标题（普通尺寸）
deep-research 报告配图	不带标题，章节标题承担
writing skill 嵌入文档的配图	不带标题，章节标题承担
writing skill 路演 / 评审 HTML 配图	大字标题 + 副标题默认开，其他叠加组件按内容评估（见 review-grade.md）
用户明确说"画评审版 / 路演图"	进入 review-grade 评估流程，逐组件判断是否叠加
用户明确说"不要标题"	跳过标题渲染

渲染参数：

• title 为空字符串或 null 时跳过标题渲染，标题区高度设为 0
• 普通标题：左上角（x=0, y=18），16px bold，颜色 #1a1a2e，标题区 52px
• 普通副标题：12px，颜色 #888888，y=36
• 大字标题（review-grade.md 二.1）：22px Bold（投屏远距离可读），标题区 ≥ 70px
• 大字副标题（review-grade.md 二.2）：14px Regular

重要原则：被 writing 路演 HTML 调用 ≠ 必须开全部叠加组件。仍要按内容形态逐项评估，简单图就该简单画。

// 标题可选的标准写法
var TITLE_AREA_H = title ? 52 : 0;

// 渲染时条件判断
if (title) {
  nodeGroup.appendChild(el('text', { ... })).textContent = title;
  if (subtitle) nodeGroup.appendChild(el('text', { ... })).textContent = subtitle;
}

---

第三步：输出规范

3.1 ファイル形式

PNG（デフォルト） — Markdown ドキュメントの図版用：

• 背景：白色 #FFFFFF
• 周囲のパディング：最低 24px
• 拡大縮小：デバイスのネイティブ DPI（Retina デバイスでは自動的に 2x の高精細画像を出力）

HTML（任意） — リッチドキュメントへの埋め込み、インタラクティブな表示用：

• 自己完結型：すべての CSS/JS をインライン化し、外部依存なし。単一ファイルをブラウザーで直接開けます
• ベクター：SVG は劣化なく拡大縮小でき、テキストを選択／検索できます
• 適した用途：HTML レポートへの埋め込み、インタラクティブなアーキテクチャドキュメントの作成、後から編集する図表
• 生成方法：python scripts/capture.py input.html -f html

DSL（任意） — Markdown ドキュメントへの埋め込み用。テキストで差分確認でき、バージョン管理できます：

• 構造図と一部の統計図は Mermaid DSL で出力できます
• Mermaid 構文のプレーンテキストとして出力します
• 適した用途：MD ドキュメントの図版に PNG ファイルを管理したくない場合、preview-md でリアルタイムにレンダリングする必要がある場合、GitHub/GitLab のネイティブレンダリングを使う場合
• 生成方法：テキストを直接出力し、ユーザーが MD ファイルのコードブロックにコピーします

DSL の選択ルール：

図表タイプ	DSL	コードブロックのマーカー
flowchart / sequence / class / state / er	Mermaid	```mermaid
gantt / mindmap / timeline / c4 / sankey / journey	Mermaid	```mermaid
architecture / swimlane / network / dataflow / orgchart / decision-tree	Mermaid（flowchart + subgraph）	```mermaid
bar / line（棒グラフ、折れ線グラフ）	Mermaid（xychart-beta）	```mermaid
pie（円グラフ）	Mermaid	```mermaid
radar / heatmap / scatter / funnel / waterfall など	DSL 非対応	PNG を引き続き使用
quadrant / gitGraph / block	現時点では非対応	必要に応じて今後対応

DSL 出力形式の例：

用户：画一个用户登录的流程图，输出 mermaid

输出：
` ` `mermaid
flowchart TD
    A[用户访问登录页] --> B{已有账号?}
    B -->|是| C[输入用户名密码]
    B -->|否| D[跳转注册页]
    C --> E{验证通过?}
    E -->|是| F[跳转首页]
    E -->|否| G[提示错误]
    G --> C
` ` `

用户：画一个微服务架构图，输出 mermaid

输出：
` ` `mermaid
flowchart TD
    subgraph 网关层
        nginx[Nginx 负载均衡] --> api_gw[API Gateway]
    end
    subgraph 服务层
        user_svc[用户服务]
        order_svc[订单服务]
        pay_svc[支付服务]
    end
    subgraph 数据层
        mysql[(MySQL)]
        redis[(Redis)]
    end
    api_gw --> user_svc & order_svc & pay_svc
    user_svc --> mysql
    order_svc --> mysql
    pay_svc --> redis
` ` `

3.2 スクリーンショットの方法

必ず固定スクリプトを使用してください。Playwright MCP ツールを手動で呼び出してスクリーンショットを撮ることは禁止です。

# 结构图：HTML → PNG
python ~/.claude/skills/diagram/scripts/capture.py <HTML文件> <输出路径>.png

# 结构图：HTML → 自包含 HTML
python ~/.claude/skills/diagram/scripts/capture.py <HTML文件> <输出路径>.html -f html

# 统计图：JSON → PNG（bridge.py 内部自动截图）
python ~/.claude/skills/diagram/scripts/bridge.py -c <配置>.json -o <输出路径>.png

# 统计图：JSON → 自包含 HTML
python ~/.claude/skills/diagram/scripts/bridge.py -c <配置>.json -o <输出路径>.html -f html

手動でスクリーンショットを撮れないのはなぜですか？ capture.py / bridge.py には、HTTP サービスの起動、ELKjs の非同期処理の待機、Retina 2x 出力、body 要素の特定などのロジックがあらかじめ組み込まれています。手動で browser_run_code / browser_take_screenshot を使用すると、待機処理が漏れて、スクリーンショットが空白になったりぼやけたりするおそれがあります。

3.3 ファイル名

<图表类型>-<描述>.png（英語の小文字 + ハイフン）

3.4 保存場所

• デフォルト：呼び出し元の Markdown ファイルと同じ階層にある assets/ または images/ ディレクトリ
• deep-research から呼び出す場合：docs/research/assets/

---

ツールの依存関係

ツール	場所	用途
capture.py	scripts/capture.py	構造図 HTML → PNG/HTML（内部で Playwright を呼び出します）
bridge.py	scripts/bridge.py	統計図 JSON → PNG/HTML（内部で Playwright を呼び出します）
ELKjs	lib/elk.bundled.js（インライン化済み）	ER 図／クラス図／状態図／フローチャート DAG の自動レイアウト

Playwright は capture.py / bridge.py の内部実装としてのみ使用します。スクリーンショットの撮影に Playwright MCP ツール（browser_navigate、browser_take_screenshot、browser_run_code など）を直接呼び出さないでください。

ELKjs の使用方法

ELKjs は自由レイアウト（ノードとエッジの位置をアルゴリズムで最適化する必要がある場面）にのみ使用します。以下の図表タイプではELKjs を使用しません：

• フローチャートの線形モード（ドメインルール：メインパスは下向き、否定分岐は右向き）
• スイムレーン図（ドメインルール：レーンの行順は固定）
• アーキテクチャ図（ドメインルール：階層は事前定義）
• シーケンス図（ドメインルール：参加者は横並び、メッセージは縦方向）

理由：これらの図表には明確なドメインレイアウトルールがあり、ELKjs による自動最適化ではそのルールが崩れてしまいます（たとえば、レーンの順序が入れ替わったり、グループの位置が変わったりします）。

例外：フローチャートの DAG モード（複数の根ノード、合流、判断を伴わない分岐）では ELKjs を使用します。このようなトポロジーは、「メインパス + サイド分岐」の単純な手動レイアウトでは表現できないためです。詳しくは references/diagrams/flowchart.md を参照してください。

フローチャート DAG モードの注意事項

• トポロジーを忠実に再現する：存在しない接続は絶対に追加せず、複数の独立した入口を無理に同じ根ノードにまとめないでください
• ノードタイプは元の図に忠実にする：同じ階層／役割のノードには同じ type を使用します。highlight は、元の図で重要／中核と明示されているノードにのみ使用し、「異なるカテゴリ」を区別するためには使用しないでください。カテゴリの違いは process／external／datastore などの意味を表すタイプで示します

---