mermaid

Mermaid 図スキル

このスキルでは、GitHub 上で正しく表示され、ライトモードとダークモードの両方で見やすい、美しくプロフェッショナルな Mermaid 図を作成するためのガイダンスを提供します。

基本原則

1. 暗い塗りつぶしと明るい線を使う — ライトモードとダークモードの両方で読みやすくなります
2. サブグラフの塗りつぶしを none に設定する — どのような背景にもサブグラフがなじみます
3. 角丸の図形を使う — スタジアム形状には ([text])、円には ((text)) を使います
4. Font Awesome アイコンは使わない — GitHub は fa:fa-* アイコンをサポートしておらず、テキストとして表示されます
5. サブグラフのラベルを引用符で囲む — subgraph Name["Label Text"] 構文を使います
6. classDef スタイルは先頭で定義する — 保守しやすいよう、すべてのスタイルをまとめます
7. レンダリングして自分で確認する — 自動レイアウトは独自に線の経路を決めるため、必ずレンダリング画像をプレビューし、線をたどりやすくなるまで調整します

レンダリング、確認、反復（毎回行ってください）

有効な Mermaid を書くことが目標ではありません。人が実際に理解できる図を作ることが目標です。Mermaid の自動レイアウト（dagre）はノードの配置とエッジの経路を決めるため、ソースでは問題なく見える図が、レンダリングすると線が絡み合った状態になることがあります。必ずレンダリングし、読者の視点で確認してから、公開する前に調整してください。

1. 画像にレンダリングして開きます。ダーク背景の Mermaid-cli を使うと、GitHub に近い表示を確認できます：

   npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -b "#0d1117"
   

   Mermaid コードだけを diagram.mmd に記述します（図のみを記述し、前後を囲むフェンス記号は含めません）。手軽に貼り付けてプレビューするには、mermaid.live も使えます。

2. 作成者ではなく、読者の視点で確認します：

   • 開始位置と終了位置はすぐにわかりますか？
   • 交差箇所で見失うことなく、すべての矢印を根元から先端までたどれますか？
   • 関連するノードは互いに近くにあり、孤立して浮いたノードはありませんか？

3. 線が絡まっている場合は、色だけでなくレイアウトを修正します。有効な手法は次のとおりです：

   • メインフローをレーンとして配置します（flowchart LR を使い、各サブグラフ内では direction TB を指定します）。こうすることで、一方向に開始から終了まで読めます。
   • 網目状になる副次的なエッジ（テストカバレッジの矢印や、すべての相互参照など）を削減します。主要なフローを示し、残りは文章で説明します。
   • ノードを、それを利用する要素のそばに配置します（データモデルは、それを構築するコードの直後に配置します）。矢印を短く保てます。
   • 孤立したグループが隅に流れてしまわないよう、単一のリンクで固定します（「後で消費される」エッジを1つ置くほうが、ノードを浮かせておくより効果的です）。
   • エラーやロギングなどの横断的関心事は、できるだけ少ないエッジで1つのノードに接続します。

4. たどりやすくなるまで再レンダリングと調整を繰り返します。凡例を見ないとたどれない図は、完成していません。

黄金律：暗い塗りつぶしと明るい線

ライトモードとダークモードの両方に対応するための重要なポイント：

classDef myStyle fill:#DARK_COLOUR,stroke:#LIGHT_COLOUR,stroke-width:2px,color:#fff

• 塗りつぶし：暗めの色合いを使います（ノードの背景）
• 線：同じ色系統の明るめの色合いを使います（枠線）
• 文字色：常に #fff を使います（暗い背景に白い文字）

この方法なら、ページの背景色にかかわらずノードを読みやすくできます。

GitHub 互換テンプレート

これは、GitHub でレンダリングする Mermaid 図の標準テンプレートです：

flowchart TD
    %% --- COLOUR PALETTE & STYLING ---
    %% Dark fills + light strokes = readable in both light and dark mode
    classDef user fill:#374151,stroke:#d1d5db,stroke-width:2px,color:#fff
    classDef primary fill:#5b21b6,stroke:#ddd6fe,stroke-width:2px,color:#fff
    classDef secondary fill:#1e40af,stroke:#bfdbfe,stroke-width:2px,color:#fff
    classDef accent fill:#c2410c,stroke:#fed7aa,stroke-width:2px,color:#fff
    classDef success fill:#047857,stroke:#a7f3d0,stroke-width:2px,color:#fff

    %% --- NODES ---
    User((User)):::user
    User --> Action(["Performs action"]):::user

    Action --> Primary

    subgraph Primary["Primary Component"]
        direction TB
        Step1(["Step 1"]):::primary
        Step2(["Step 2"]):::primary
        Step1 --> Step2
    end

    subgraph Secondary["Secondary Component"]
        direction TB
        Process(["Process"]):::secondary
    end

    Primary --> Secondary
    Secondary --> Output(["Output"]):::success

    %% --- SUBGRAPH STYLES ---
    %% fill:none allows subgraphs to adapt to any background
    style Primary fill:none,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:5 5,color:#8b5cf6
    style Secondary fill:none,stroke:#3b82f6,stroke-width:2px,color:#3b82f6

色の組み合わせ例

好きな色を選べます。暗い塗りつぶしと明るい線のパターンに従ってください：

塗りつぶし（暗）	線（明）	結果
#374151	#d1d5db	グレー
#5b21b6	#ddd6fe	紫
#1e40af	#bfdbfe	青
#c2410c	#fed7aa	オレンジ
#047857	#a7f3d0	緑
#b91c1c	#fecaca	赤
#0f766e	#99f6e4	ティール

これらはあくまで例です。図に合った色を使ってください。重要なのは原則です。

サブグラフの構文

❌ 誤り — パースエラーが発生します

subgraph MyGroup [Label With Spaces]

✅ 正しい — ラベルを引用符で囲みます

subgraph MyGroup["Label With Spaces"]

ノードの形状

❌ 誤り — 角括弧は角張った印象になります

A[Square Node]

✅ 正しい — 角丸の図形を使います

A(["Stadium shape"])     %% Rounded ends - use for most nodes
B((Circle))              %% Circle - use for users/actors
C{{"Decision"}}          %% Hexagon for decisions
D[(Database)]            %% Cylinder for databases/storage

サブグラフのスタイル

❌ 誤り — 色付きの塗りつぶしはダークモードで表示が崩れます

style MySubgraph fill:#f0f9ff,stroke:#3182ce

✅ 正しい — 透明な塗りつぶしはどの背景にも適応します

style MySubgraph fill:none,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:5 5,color:#8b5cf6

要点：

• fill:none にすると背景が透明になります
• stroke-dasharray:5 5 は破線の枠線を作成します（任意ですが、見た目がすっきりします）
• color:#... はサブグラフのラベルの色を枠線に合わせます

ノードラベルの改行

❌ 誤り — \n は文字列としてそのまま表示されます

A(["First line\nSecond line"])

✅ 正しい — 複数行のラベルには <br/> を使用します

A(["First line<br/>Second line"])
B[("Tips File<br/>(YAML/JSON)")]
C(["Tips Engine<br/>pick + cycle"])

リンクのスタイル設定

A --> B              %% Solid arrow
A -.-> B             %% Dashed arrow
A -.->|Label| B      %% Dashed arrow with label
A ==> B              %% Thick arrow

完全な例

flowchart TD
    classDef user fill:#374151,stroke:#d1d5db,stroke-width:2px,color:#fff
    classDef process fill:#5b21b6,stroke:#ddd6fe,stroke-width:2px,color:#fff
    classDef decision fill:#c2410c,stroke:#fed7aa,stroke-width:2px,color:#fff
    classDef success fill:#047857,stroke:#a7f3d0,stroke-width:2px,color:#fff

    User((User)):::user
    User --> Request(["Makes request"]):::user

    Request --> Process

    subgraph Process["Processing"]
        direction TB
        Validate(["Validate input"]):::process
        Execute(["Execute logic"]):::process
        Validate --> Execute
    end

    Execute --> Check{{"Success?"}}:::decision
    Check -->|Yes| Done(["Complete"]):::success
    Check -->|No| Request

    style Process fill:none,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:5 5,color:#8b5cf6

よくある間違い

❌ Font Awesome アイコン（GitHub はサポートしていません）

A[fa:fa-user User]  %% Renders as literal text

❌ 暗いテキストに明るい塗りつぶし

classDef bad fill:#ffffff,stroke:#000000,color:#000000  %% Invisible in dark mode

❌ 色付きのサブグラフの塗りつぶし

style Sub fill:#e0f2fe  %% Looks different in light vs dark mode

❌ スペースを含む、引用符で囲まれていないサブグラフのラベル

subgraph Sub [My Label]  %% Parse error!

クイックリファレンス

flowchart TD
    %% 1. Define styles: dark fill + light stroke + white text
    classDef myStyle fill:#DARK,stroke:#LIGHT,stroke-width:2px,color:#fff

    %% 2. Use rounded shapes
    Node(["Text"]):::myStyle

    %% 3. Quote subgraph labels
    subgraph Sub["My Label"]
        Inner(["Inner"])
    end

    %% 4. Style subgraphs with fill:none
    style Sub fill:none,stroke:#COLOR,stroke-width:2px,color:#COLOR

このスキルを使用する場面

次の作成時にこのスキルを呼び出します：

• PR 用のアーキテクチャ図
• システムフローのドキュメント
• データパイプラインの可視化
• プロセスフローチャート
• GitHub Markdown 内のあらゆる図

GitHub 固有の注意事項

1. Font Awesome は使用できません — GitHub の Mermaid レンダラーは fa:fa-* アイコンをサポートしておらず、テキストとして表示されます
2. 改行には <br/> を使用します — 複数行のノードラベルには \n（そのまま表示されます）ではなく、<br/> を使用します
3. スペースを含むラベルは引用符で囲みます — subgraph X["Label"] を使用し、subgraph X [Label] は使用しません
4. ローカルでテストします — コミット前に mermaid.live でプレビューします