mermaid-diagrams

Mermaid 図

アーキテクチャ文書向けのポータブルな Mermaid.js による図の作成です。特定のブログプラットフォーム、テーマ、レンダリングエンジンには依存しません。図は CLI でレンダリングしたり、Markdown に埋め込んだり、HTML スニペットとして配信したりできます。

使用する場面

次の場合にこのスキルを読み込みます。

• C4 のレベルとモデルを選択した後に、C4 のフローチャート近似図をレンダリングする場合。C4 のモデル化の判断には c4-diagramming を使用します
• インタラクションフローのシーケンス図を作成する場合
• プロセス文書用のフローチャートを設計する場合
• 仕様策定用の状態図／クラス図／ER 図を作成する場合
• エージェント向けと人間向けの両方のコンテキストでレンダリングする必要がある図を作成する場合
• 構造上は有効な Mermaid 図が、対象読者や出力先に適したコミュニケーション成果物かどうかを確認する場合

次の場合は読み込まないでください。

• プレーンテキストの概要のほうが、関係性を図より明確に伝えられる場合。
• 出力先のレンダラーが Mermaid を実行できず、事前レンダリングの手段もない場合。

PDF 出力 — 事前レンダリングが必須

Mermaid コードブロック（mermaid）は、Pandoc → HTML → Puppeteer の PDF パイプラインではレンダリングされません。このパイプラインは JavaScript を実行せずに静的 HTML を生成します。

PDF 出力を予定している図については、必ず次の手順を実行してください。

1. 図を単独の .mmd ファイルとして作成します
2. SVG に事前レンダリングします：npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.svg --width 800
3. 埋め込み方法を 1 つ選びます。デフォルトではインライン SVG を使用し、レンダラーが生の SVG を破損する場合は base64 データ URI を使用します。
4. SVG タグからハードコードされた max-width のピクセル値を削除します
5. flowchart LR（横向き）ではなく flowchart TD（縦向き）を使用します。references/portrait-layout.md を参照してください
6. ページ全体を使う各図の前後にページ区切り用の div を追加します

Pandoc を通す Markdown に ```mermaid コードブロックを残さないでください。コードブロックは書式なしの等幅テキストとして表示されます。

Puppeteer のセットアップ、SVG のスタイル修正、QA チェックリストを含むパイプライン全体については、references/pdf-rendering-pipeline.md を参照してください。

コミュニケーションのレビュー

作成する前に、対象読者、読者の目的、出力先、意図する読み順を明示します。その目的を支える最小限の図の種類と範囲を選びます。抽象度、ノードの形、エッジの意味、ラベル、境界の扱い、視覚的な階層に一貫性を持たせます。構文検証と正常なレンダリングは必要ですが、それだけでは十分ではありません。Mermaid として有効な図でも、情報が過密である、主要な経路が見えにくい、表現上の慣例が混在している、不確実性の判断を読者に委ねている、といった理由で、コミュニケーション成果物として適切でないことがあります。

文法のテストだけでなく、人に伝えることを目的に図を作成、修正、レビューする場合は、references/diagram-communication.md を読み込みます。ナラティブ、情報量とノイズのバランス、ラベルと凡例、色に依存しない意味、アクセシビリティの代替手段、不確実性、レンダリング結果のレビュー証拠については、同ファイルのレビューレコードを使用します。C4 のレベルとモデルの決定は c4-diagramming の担当範囲です。アーキテクチャの決定は software-architecture の担当範囲です。アクセシビリティへの完全な準拠は web-accessibility の担当範囲です。

サポートする図の種類

種類	使用例	ファイル
フローチャート	プロセスフロー、C4 の代替表現、決定木	references/flowchart.md
シーケンス図	インタラクションプロトコルと API 呼び出し	references/sequence.md
C4 のレンダリング	c4-diagramming で選択済みの C4 ビューのフローチャート近似図	references/c4-mermaid.md
縦向きレイアウト	PDF／印刷向けの図の作成 — LR ではなく TD、ページ区切り、ページ全体を使う図	references/portrait-layout.md
PDF レンダリングパイプライン	.mmd → SVG → HTML → PDF の全パイプラインと QA チェックリスト	references/pdf-rendering-pipeline.md
mmdc 間隔設定	図の密度を調整し、ラベルの重なりを防ぐための設定	references/mmdc-spacing-config.md

C4 モデルのガイダンス

Mermaid には実験的なネイティブ C4 構文（C4Context、C4Container、C4Component）がありますが、GitHub およびほとんどの Markdown レンダラーではサポートされていません。 GitHub に組み込まれている Mermaid レンダラーには C4 プラグインが含まれていないため、C4 構文のブロックは図ではなく、そのままコードとして表示されます。代わりに、以下のいずれかの方法を使用してください。

1. フローチャートによる代替（GitHub 互換） — 境界にはサブグラフ、Person/System/Container/Db にはスタイルを設定したノードボックス、Rel にはラベル付きエッジを使用して、C4 図を標準の flowchart 構文に変換します。変換パターンの詳細は references/c4-to-flowchart.md を参照してください。
2. Structurizr DSL — 本格的な C4 図にはこちらを使用します。Structurizr CLI でレンダリングするか、Mermaid SVG にエクスポートします。GitHub の Markdown 上には置かない、正式なアーキテクチャドキュメントに最適です。
3. ハイブリッド方式 — Structurizr DSL で完全な C4 モデルを管理し、Markdown にはインラインで読みやすいようにフローチャートベースの近似図を含めます。

C4 からフローチャートへの変換パターン

C4 要素	フローチャートでの表現	例
Person()	[label]（標準の長方形）	U[Human User]
System()	スタイルを設定した [label]	GP[GroktoPlan] に style GP fill:#... を設定
System_Ext()	サブグラフの外側にある [label]	GIT[Git Providers]
Container()	[label with tech stack]	KG[Knowledge Graph<br/>Python + pgvector]
Db()	[(label)]（円柱形）	LS[(Live State DB)]
System_Boundary{}	subgraph System["Title"] ... end	入れ子のサブグラフ
Container_Boundary{}	subgraph Service["Title"] ... end	単一のサブグラフ
Rel()	-- label --> または -.->	AR -- gRPC --> GA
UpdateLayoutConfig()	省略 — flowchart LR または TB を使用	方向はヘッダーで設定

C4 の 3 つのレベルすべての具体例については、references/c4-to-flowchart.md を参照してください。

GitHub 互換性のリファレンス

図の種類	GitHub でレンダリングされますか？	備考
flowchart（TD/LR/BT/RL）	✅	C4 の代替にはすべてこちらを使用
sequenceDiagram	✅
classDiagram	✅
stateDiagram-v2	✅
erDiagram	✅
gantt	✅
pie	✅
quadrantChart	✅
requirementDiagram	✅
gitgraph	✅
mindmap	✅
timeline	✅
zenuml	✅
sankey	✅
xychart	✅
block	✅
packet	✅
C4Context	❌	C4 プラグインが必要 — そのままコードとして表示
C4Container	❌	C4 プラグインが必要 — そのままコードとして表示
C4Component	❌	C4 プラグインが必要 — そのままコードとして表示
C4Deployment	❌	C4 プラグインが必要 — そのままコードとして表示
C4Dynamic	❌	C4 プラグインが必要 — そのままコードとして表示

レンダリング

CLI（mmdc）— PDF/SVG/PNG 出力用

npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.svg
npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.png
npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.pdf

Puppeteer と Chromium が必要です（約 1.7GB）。分離された環境でレンダリングするには Docker イメージを使用してください。

docker run --rm -v $(pwd):/data ghcr.io/mermaid-js/mermaid-cli mermaid-cli -i /data/diagram.mmd -o /data/diagram.svg

CDN（HTML）— ウェブページ内でのレンダリング用

<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
<div class="mermaid">
flowchart LR
  A-->B
</div>

検証

// Node.js validation
import { parse } from 'mermaid';
try {
  parse('flowchart LR\n  A-->B');
  console.log('Valid');
} catch (e) {
  console.error('Invalid:', e.message);
}

スクリプト

スクリプト	目的
scripts/validate-mermaid.sh	Mermaid CLI で .mmd ファイルを検証

テーマ設定

Mermaid は base テーマを使用し、テーマ変数をカスタマイズできます。図の先頭に init ディレクティブを設定します。バージョンごとの変数一覧については、Mermaid のドキュメントを参照してください。

主なテーマ変数：

• primaryColor、primaryTextColor、primaryBorderColor
• secondaryColor、tertiaryColor
• lineColor、fontFamily、fontSize
• background（外側の背景）、mainBkg（要素の背景）

アンチパターン

アンチパターン	修正方法
フローチャートで小文字の end を使う	Mermaid のキーワードはすべて大文字と小文字を区別します。End は end ではありません。
空白を入れずにダッシュの後に o または x を置く	-->o には空白が必要です。--o を使うか、明示的なノード形状を使ってください。
括弧内で引用符を使う	('quoted text') ではなく ("quoted text") を使ってください。
非常に幅の広い図（ノードが100個超）	サブ図に分割するか、ELK レイアウトを使ってください。
タブとスペースの混在	スペースのみを使ってください。サブグラフのインデントはスペース2つにします。
改行のない長いラベル	ノード内の改行には <br/> またはパイプ `
SVG をデータ URI として埋め込む	代わりに生の <svg> タグを使ってください。データ URI の最大幅は CSS で上書きできません。
PDF 用の Markdown に Mermaid コードブロックを残す	先に SVG としてレンダリングしてください。Pandoc は ```mermaid をプレーンテキストとしてレンダリングします。

移植性

このスキルは、特定のホスト環境に依存しないように設計されています。ここに記載されているリファレンス、テンプレート、スクリプトの読み込みには、エージェントで通常使用している方法を使ってください。特定のプロファイルシステム、タスクオーケストレーター、メモリサービス、レスポンス引き継ぎ形式を前提にしないでください。

使用しない場合

• C4 のシステムコンテキスト、コンテナー、コンポーネント、またはコードレベルのモデルを選択または保守するタスクでは、c4-diagramming を使ってください。
• 図の構文やレンダリングではなく、アーキテクチャの推進要因、トレードオフ、意思決定、適合性の根拠を扱う場合は、software-architecture を使ってください。
• WCAG/ARIA への完全な準拠や支援技術の評価には、web-accessibility を使ってください。このスキルが提供するのは、図に特化したチェックと代替手段のみです。