xs-diagram-generator

スマート図表生成支援

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

判断フロー

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"}
  ]
}'