mermaid-diagramming

Mermaid による図解

技術ドキュメント向けに、明確でプロフェッショナルな Mermaid 図を作成します。基本バリエーションとスタイル付きバリエーションの両方で主要な図の種類を網羅し、レンダリング方法とエクスポートの推奨事項も説明します。

このスキルを使う場面

• プロセスのドキュメントや意思決定ツリー用のフローチャートを作成する
• API のやり取りやシステム間の通信を示すシーケンス図を描く
• データベーススキーマのドキュメント用に ERD を作成する
• ワークフローの状態を示すステートマシン図を設計する
• プロジェクトのタイムライン用にガントチャートを作成する
• C4 図やネットワーク図でシステムアーキテクチャをドキュメント化する
• README ファイル、ADR、設計ドキュメントに視覚資料を追加する

クイックリファレンス

リソース	目的	読み込むタイミング
references/diagram-types.md	すべての Mermaid 図の種類に関する構文、パターン、コード例	図を選択または作成するとき

---

ワークフローの概要

Phase 1: Scope     → Identify what to visualize, audience, and diagram type
Phase 2: Draft     → Write base Mermaid code with correct syntax
Phase 3: Style     → Add theming, colors, and accessibility annotations
Phase 4: Deliver   → Provide rendering instructions and suggest iterations

---

フェーズ 1：範囲の決定

コードを書く前に、以下を明確にします。

1. 何を伝えるのか？ 図はストーリーを伝えるか、質問に答えるものである必要があります。
2. 対象読者は誰か？ 開発者には詳細が必要ですが、ステークホルダーには概要が必要です。
3. どのようなエンティティと関係があるか？ 描画する前にノードとエッジを列挙します。
4. どの図の種類が適しているか？ 以下の選択ガイドを使います。

図の種類の選択

表示する内容	使用する図
プロセスの流れ、意思決定、分岐	flowchart
システムやアクター間の時間経過に伴うやり取り	sequenceDiagram
データモデルと関係	erDiagram
オブジェクトの構造と継承	classDiagram
状態と遷移	stateDiagram-v2
プロジェクトのスケジュールと依存関係	gantt
比率や分布	pie
階層的なアイデアのマッピング	mindmap
時間経過に伴うイベント	timeline
システムアーキテクチャのレイヤー	C4 コンテキスト図／コンテナー図
コードのバージョン履歴	gitGraph
ユーザー体験のフロー	journey

---

フェーズ 2：下書き

構成のルール

1. 図ごとに概念を 1 つにする — 複雑なシステムは複数のビューに分割します
2. ノード数を抑える — 図あたり 15 ノード未満にし、それ以上になる場合は分割します
3. 意味のあるラベルを付ける — 1 文字ではなく、説明的なテキストを使います
4. 方向を統一する — 上から下（TB）または左から右（LR）を優先します
5. 関連するノードをまとめる — subgraph を使って関連要素をグループ化します

コード規約

%% Always start with a comment describing the diagram's purpose
%% Use consistent quoting for labels with special characters
flowchart LR
    A["User Request"] --> B{"Auth Check"}
    B -->|Valid| C["Process Request"]
    B -->|Invalid| D["Return 401"]

• 特殊文字を含むラベルには二重引用符を使います
• 自明でない関係を説明するコメント（%%）を追加します
• 実線には -->、破線には -.->、太線には ==> を優先して使います
• 説明的なエッジラベルを使います：-->|"理由"| TargetNode

---

フェーズ 3：スタイルの適用

テーマ設定

%%{init: ...}%% ディレクティブを使って、統一感のあるスタイルを適用します。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9'}}}%%
flowchart TB
    A["Start"] --> B["End"]

ノードのスタイル設定

flowchart LR
    A["Normal"]
    B["Highlighted"]:::highlight
    classDef highlight fill:#f9f,stroke:#333,stroke-width:2px

アクセシビリティ

• コントラストの高い配色を使います
• 意味を伝える際に色だけに頼らず、ラベルや形状を追加します
• 埋め込む際は代替テキストを含めます：![図の説明](path)
• 複雑な図にはテキストによる要約を添えます

---

フェーズ 4：成果物の提示

必ず提示するもの

1. 基本バージョン — どこでもレンダリングできる、シンプルでスタイルなしの図
2. スタイル付きバージョン — 色と強調を加えたテーマ適用版
3. レンダリングに関する注記 — プレビューできる場所（GitHub、Mermaid Live、VS Code 拡張機能）
4. 提案 — 補完的な図や次の改善案

レンダリングの選択肢

プラットフォーム	サポート
GitHub markdown	.md ファイルでネイティブにレンダリング
GitLab markdown	ネイティブレンダリング
Mermaid Live Editor	インタラクティブな編集には https://mermaid.live
VS Code	プレビューには Mermaid 拡張機能
Docusaurus / MkDocs	プラグインによるレンダリング

エクスポート形式

• SVG：Web やドキュメントに最適（拡大縮小可能で、テキストを検索できます）
• PNG：Mermaid 非対応のプラットフォーム向けの代替形式
• PDF：印刷や正式なドキュメント向け

---

ベストプラクティス

• シンプルに始める — スタイルを追加する前に、構造を整えます
• レンダリングをテストする — コミットする前に、対象のプラットフォームで表示を確認します
• 図をバージョン管理する — 基盤となるシステムが変更されたら、図も更新します
• ドキュメントと同じ場所に配置する — 図は関連するドキュメントと同じディレクトリに置きます
• サブグラフを使う — 関連するノードをグループ化して、視覚的な複雑さを軽減します

アンチパターン

• 1つの図にノードを詰め込みすぎる（15個以上になったら分割します）
• ラベルを付けずに1文字のノード ID を使う
• 意味を伝えるために色だけに頼る
• レンダラーによって表示が崩れる、ピクセル単位の幅をハードコーディングする
• システムの変更後に図を古いままにしておく