xs-diagram-generator

name	xs:diagram-generator
description	内容に応じて最適な図表形式を自動選択し、ローカルで画像生成（Pillow）またはコード出力（Mermaid/PlantUML）。フローチャート、アーキテクチャ図、階層図などを生成。資料作成、システム設計時に使用。

スマート図表生成支援

内容に応じて最適な図表形式を自動選択し、画像を生成する。

判断フロー

Mermaidコードがすでにある？
  ├─ YES → Docker mermaid-cli で画像化（最優先）
  └─ NO  → 内容に応じて選択
              ├─ フロー/シーケンス → Mermaidコード作成 → Docker mermaid-cli
              └─ アーキテクチャ/階層 → Pillow（uv run）で直接生成

---

1. Mermaid → 画像化（Docker mermaid-cli）

Mermaidコードがある場合はこれを最優先で使う。

# 1. Mermaidファイルを作成
cat > /tmp/diagram.mmd << 'EOF'
flowchart TB
    A[開始] --> B[処理]
    B --> C{判断}
    C -->|Yes| D[完了]
    C -->|No| B
EOF

# 2. Docker版 mermaid-cli で画像生成
docker run --rm -u $(id -u):$(id -g) \
  -v /tmp:/data \
  minlag/mermaid-cli \
  -i /data/diagram.mmd -o /data/diagram.png -b white

ポイント:

• -u $(id -u):$(id -g) でパーミッション問題を回避
• -b white で白背景（スライド向け）
• 日本語・絵文字も表示可能
• SVG出力: -o /data/diagram.svg

⚠️ Mermaid記法の注意（よく間違えるやつ）

改行は <br> を使う！ \n は使わない！

# NG（\n がそのまま表示される）
A["Gateway\nRust / Axum"]

# OK（ちゃんと改行される）
A["Gateway<br>Rust / Axum"]

subgraphのタイトルが長いと途中で改行される:

• タイトルは短くする（15文字以内推奨）
• 補足は中のノードに書く

線の交差を減らすコツ:

• direction LR / direction TB をsubgraph内で使い分ける
• 関連するノードを近くに配置する
• 包含関係はsubgraphのネストで表現する（矢印より明確）

subgraphのネスト例（包含関係の表現）:

subgraph outer["親システム"]
    subgraph inner["子システム"]
        A["コンポーネントA"]
    end
    B["コンポーネントB"] --> A
end

複数ファイルを一括変換

for f in /tmp/*.mmd; do
  docker run --rm -u $(id -u):$(id -g) \
    -v /tmp:/data \
    minlag/mermaid-cli \
    -i /data/$(basename "$f") -o /data/$(basename "$f" .mmd).png -b white
done

---

2. Pillow で直接画像生成（uv run）

Mermaidを経由せず、直接画像を生成したい場合に使用。

スクリプト実行

uv run --with pillow python [SKILL_DIR]/draw_diagram.py <type> -o <output.png> -d '<json>'

対応する図の種類

アーキテクチャ図 (architecture)

uv run --with pillow python [SKILL_DIR]/draw_diagram.py architecture \
  -o /tmp/arch.png -d '{
  "title": "システム構成",
  "boxes": [
    {"id": "api", "label": "API Server", "color": "blue", "row": 0, "col": 1},
    {"id": "db", "label": "Database", "sublabel": "PostgreSQL", "color": "green", "row": 1, "col": 0},
    {"id": "cache", "label": "Cache", "sublabel": "Redis", "color": "orange", "row": 1, "col": 2}
  ],
  "arrows": [
    {"from": "api", "to": "db", "label": "query"},
    {"from": "api", "to": "cache", "label": "read/write"}
  ]
}'

パラメータ:

• boxes[].id: 識別子（矢印の接続に使用）
• boxes[].label: メインラベル
• boxes[].sublabel: サブラベル（オプション）
• boxes[].color: blue/orange/purple/green/red/gray/teal
• boxes[].row, boxes[].col: グリッド位置
• arrows[].from, arrows[].to: 接続元・先の id
• arrows[].label: 矢印のラベル（オプション）

フローチャート (flowchart)

uv run --with pillow python [SKILL_DIR]/draw_diagram.py flowchart \
  -o /tmp/flow.png -d '{
  "title": "ユーザー登録フロー",
  "steps": [
    {"id": "s1", "label": "開始", "type": "start"},
    {"id": "s2", "label": "フォーム入力", "type": "process"},
    {"id": "s3", "label": "バリデーション", "type": "decision"},
    {"id": "s4", "label": "DB保存", "type": "process"},
    {"id": "s5", "label": "完了", "type": "end"}
  ],
  "connections": [
    {"from": "s1", "to": "s2"},
    {"from": "s2", "to": "s3"},
    {"from": "s3", "to": "s4", "label": "OK"},
    {"from": "s4", "to": "s5"}
  ]
}'

ステップの type: start（緑）/ end（赤）/ process（青）/ decision（オレンジ）

階層図 (hierarchy)

uv run --with pillow python [SKILL_DIR]/draw_diagram.py hierarchy \
  -o /tmp/org.png -d '{
  "title": "組織図",
  "root": {
    "label": "CEO",
    "color": "purple",
    "children": [
      {"label": "CTO", "color": "blue", "children": [
        {"label": "Dev Team", "color": "green"},
        {"label": "Infra Team", "color": "green"}
      ]},
      {"label": "CFO", "color": "orange", "children": [
        {"label": "Finance", "color": "gray"}
      ]}
    ]
  }
}'

---

利用可能な色

色名	用途の目安
blue	技術系、API、サーバー
green	正常系、開始、データベース
orange	条件分岐、警告、キャッシュ
purple	重要、トップレベル
red	終了、エラー、削除
gray	補助、外部システム
teal	その他

---

使用例

Mermaidコードを画像化したい場合

「このMermaidを画像にして」
→ .mmdファイルに保存 → docker mermaid-cli → PNG送信

ゼロから図を作りたい場合

「APIサーバー、DB、キャッシュの構成図を作って」
→ Pillow architecture で JSON 生成 → uv run → PNG送信

「ユーザー登録の流れをフローチャートにして」
→ Mermaidコード作成 → docker mermaid-cli → PNG送信

---

⚠️ 注意事項

• ローカル mermaid-cli (npx): ARM64環境ではPuppeteerが動作しないため非推奨。Docker版を使うこと。
• Mermaid記法の落とし穴は上の「⚠️ Mermaid記法の注意」セクションを参照