mermaid-studio

Mermaid Studio

専門家レベルの Mermaid 図の作成、検証、複数形式へのレンダリングに対応します。説明やコード解析から図を作成し、構文を検証して、プロフェッショナルなテーマで SVG、PNG、または ASCII にレンダリングします。

基本ルール — デフォルトで洗練された図を作成

すべての図で、以下の原則に必ず従ってください。これらは任意ではありません。標準的な図と最高水準の図を分ける基準です。

ルール 1：プロフェッショナルなスタイル設定には必ず Init ディレクティブを使用する

%%{init} ディレクティブまたはフロントマター設定を使わずに図を作成してはなりません。Mermaid のデフォルトテーマでは、強すぎる黒い線とありきたりな色が使われます。必ず、厳選したパレットを適用してください。

一般的な図（フローチャート、シーケンス図、状態図、クラス図、ERD）の場合：

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'primaryTextColor': '#ffffff',
  'primaryBorderColor': '#3730a3', 'lineColor': '#94a3b8',
  'secondaryColor': '#10b981', 'tertiaryColor': '#f59e0b',
  'background': '#ffffff', 'mainBkg': '#f8fafc',
  'nodeBorder': '#cbd5e1', 'clusterBkg': '#f1f5f9',
  'clusterBorder': '#e2e8f0', 'titleColor': '#1e293b',
  'edgeLabelBackground': '#ffffff', 'textColor': '#334155'
}}}%%

⚠️ フォントに関する警告： テーマ変数で fontFamily を設定してはなりません。Mermaid のデフォルトフォント（trebuchet ms, verdana, arial, sans-serif）は、どこでも問題なく動作します。system-ui、Segoe UI、または -apple-system を設定すると、ヘッドレス Chromium（mmdc で使用）では Times New Roman としてレンダリングされます。

C4 図については、以下の専用 C4 スタイル設定セクションを参照してください。

architecture-beta 図については、以下の専用 AWS／Architecture セクションを参照してください。

ルール 2：柔らかな線を使い、強い黒は避ける

視覚的な印象を最も大きく改善する方法は、デフォルトの黒ではなく lineColor: '#94a3b8'（slate-400）を使うことです。これにより、モダンで見やすい図になります。ダークテーマでは、lineColor: '#64748b'（slate-500）を使ってください。

ルール 3：密度を抑え、余白を確保する

• 1 つの図あたりのノード数は最大 15 個にしてください（20 個ではありません。少ないほうが洗練されます）。
• subgraph または境界を使って、余白と視覚的なグループ分けを作成してください。
• プロセスフローには LR（左から右）を優先してください。より自然に読めます。
• レイアウトが窮屈な場合は、非表示リンク（A ~~~ B）を使って間隔を空けてください。

ルール 4：意味のあるラベルと一貫したスタイル

• ノード ID：キャメルケース（s1 や os ではなく、orderService）
• ラベル：短く、明確で自然な言葉（[Order Service]）
• 矢印：プロトコル情報を含む動作動詞（"Sends order via gRPC"）
• 説明：役割に焦点を当てた 1 行の文（"Handles order lifecycle"）

ルール 5：色数よりも色の調和を優先する

1 つの図で使う色は最大 3〜4 色にしてください。色を意味に対応させます。

• 青系（#4f46e5、#3b82f6）→ 主要システム、内部サービス
• 緑系（#10b981、#059669）→ 成功状態、データストア
• アンバー系（#f59e0b、#d97706）→ 外部システム、警告
• スレート系（#64748b、#94a3b8）→ 線、境界線、二次要素
• 赤系（#ef4444）→ エラー専用。装飾には使わないでください

動作モード

このスキルは、ユーザーの意図に基づいて 3 つのモードで動作します。

モード	起動条件	動作
作成	「図を描いて…」「…を可視化して」	.mmd コードのみを生成
レンダリング	「この Mermaid をレンダリングして」「SVG／PNG／ASCII に変換して」	既存の .mmd をレンダリング
フル	「作成してレンダリングして…」、意図が曖昧なリクエスト	作成 → 検証 → レンダリング

意図が明確でない場合は、デフォルトでフルモードにしてください。

ステップ 1：リクエストを理解する

Mermaid コードを書く前に、以下を確認してください。

1. 何を図にするか — システム、フロー、スキーマ、アーキテクチャ、コード構造のどれか
2. 図の種類 — 以下の判断マトリクスを使用
3. 出力形式 — コードのみ、SVG、PNG、ASCII のどれか
4. テーマの希望 — レンダリング時にのみ確認します。デフォルトでは、厳選したパレットを使った base テーマを使用します

ダイアグラム種別の判断マトリクス

ユーザーの説明内容	ダイアグラム種別	構文キーワード
プロセス、アルゴリズム、デシジョンツリー、ワークフロー	フローチャート	flowchart TD/LR
API 呼び出し、メッセージパッシング、リクエスト/レスポンス	シーケンス	sequenceDiagram
データベーススキーマ、テーブル間の関連	ERD	erDiagram
OOP クラス、ドメインモデル、インターフェース	クラス	classDiagram
ステートマシン、ライフサイクル、状態遷移	ステート	stateDiagram-v2
高レベルのシステム概要 (C4 レベル 1)	C4 コンテキスト	C4Context
アプリケーション、データベース、サービス (C4 レベル 2)	C4 コンテナ	C4Container
内部コンポーネント (C4 レベル 3)	C4 コンポーネント	C4Component
番号付きステップを含むリクエストフロー	C4 ダイナミック	C4Dynamic
インフラストラクチャ、クラウドデプロイ	C4 デプロイメント	C4Deployment
アイコン付きのクラウドサービス (AWS/GCP/Azure)	アーキテクチャ	architecture-beta
プロジェクトのタイムライン、スケジューリング	ガント	gantt
比例データ、パーセンテージ	円	pie
ブレインストーミング、階層的なアイデア	マインドマップ	mindmap
歴史的な出来事、年代順	タイムライン	timeline
ブランチ戦略、git 履歴	Git グラフ	gitGraph
フローの量、リソース配分	サンキー	sankey-beta
X/Y データの可視化	XY チャート	xychart-beta
優先度マトリクス、戦略的ポジショニング	クアドラント	quadrantChart
レイアウト制御、グリッド配置	ブロック	block-beta
ネットワークパケット、プロトコルヘッダー	パケット	packet-beta
タスクボード、かんばんワークフロー	かんばん	kanban
ユーザー体験、満足度スコアリング	ユーザージャーニー	journey
システム要件のトレーサビリティ	要件	requirementDiagram

ユーザーの説明が 1 つの種別に明確に対応しない場合は、それぞれに簡単な根拠を添えて 2〜3 の選択肢を提案し、その後ユーザーに選んでもらいましょう。

リファレンスを読み込むタイミング

リファレンスファイルは、特定のダイアグラム種別のために必要な場合にのみ読み込んでください。

• C4 ダイアグラム → コードを書く前に references/c4-architecture.md を読む
• AWS/クラウドアーキテクチャ → コードを書く前に references/aws-architecture.md を読む
• コードからダイアグラム → 分析する前に references/code-to-diagram.md を読む
• テーマ/スタイリング → ユーザーがカスタムテーマを要求したときに references/themes.md を読む
• 構文エラー → 検証が失敗したときに references/troubleshooting.md を読む
• あらゆるダイアグラム種別の詳細 → 網羅的な構文については references/diagram-types.md を読む

ステップ 2: ダイアグラムを作成する

2.1 — Mermaid コードを書く

以下の原則を優先順位の高い順に従ってください。

1. エレガンスを最優先 — すべてのダイアグラムは、init ディレクティブと厳選された色によってプロフェッショナルに見えなければなりません
2. 正確性 — エラーなくレンダリングされる有効な構文
3. 明確さ — 意味のあるラベル、論理的なフローの方向、明確な関係
4. シンプルさ — ダイアグラムごとに 15 ノード未満。複雑なシステムは複数に分割する
5. 一貫性 — 統一された命名 (ID には camelCase、説明的なラベルは角括弧内に)

2.2 — 構造ルール

%% Diagram: [Purpose] | Author: [auto] | Date: [auto]
%%{init: {'theme': 'base', 'themeVariables': { ... }}}%%
[diagramType]
    [content]

重要： %%{init} ディレクティブは、図の種類の宣言より前に、コメント以外の最初の行に必ず記述してください。または、ファイルの先頭に YAML フロントマターを使用してください。

命名規則：

• ノード ID：説明的なキャメルケース（s1 ではなく orderService）
• ラベル：角括弧で囲んだ自然言語（[Order Service]）
• 関係：動作を表す動詞（"注文を送信する", "読み取る"）

レイアウトのベストプラクティス：

• TD（上から下）は階層的なフローやプロセスに使用します
• LR（左から右）はタイムライン、パイプライン、順次処理に使用します
• RL は右から左へ読む文脈で使用します
• 関連するノードのグループ化には subgraph を使用し、サブグラフには意味のある名前を付けます
• フローの方向を変える必要がある場合は、サブグラフ内に direction を追加します

2.3 — クイックリファレンスの例

フローチャート（プロフェッショナルなスタイル設定あり）：

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'primaryTextColor': '#fff',
  'primaryBorderColor': '#3730a3', 'lineColor': '#94a3b8',
  'secondaryColor': '#10b981', 'tertiaryColor': '#f59e0b',
  'background': '#ffffff', 'mainBkg': '#f8fafc',
  'nodeBorder': '#cbd5e1', 'clusterBkg': '#f1f5f9',
  'clusterBorder': '#e2e8f0', 'titleColor': '#1e293b',
  'edgeLabelBackground': '#ffffff'
}}}%%
flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> End([End])

シーケンス図と ERD のスタイル設定例については、references/themes.md をお読みください。

C4 コンテキスト（洗練されたスタイル設定が必須）：

C4Context
    title System Context — E-Commerce Platform

    Person(customer, "Customer", "Places orders online")
    System(platform, "E-Commerce Platform", "Handles orders and payments")
    System_Ext(payment, "Payment Gateway", "Processes transactions")
    System_Ext(email, "Email Service", "Sends notifications")

    Rel(customer, platform, "Uses", "HTTPS")
    Rel(platform, payment, "Processes payments", "API")
    Rel(platform, email, "Sends emails", "SMTP")

    UpdateRelStyle(customer, platform, $textColor="#475569", $lineColor="#94a3b8")
    UpdateRelStyle(platform, payment, $textColor="#475569", $lineColor="#94a3b8")
    UpdateRelStyle(platform, email, $textColor="#475569", $lineColor="#94a3b8")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

アーキテクチャ（Iconify アイコンを使用した AWS）：

architecture-beta
    group vpc(logos:aws-vpc)[VPC]

    service api(logos:aws-api-gateway)[API Gateway] in vpc
    service lambda(logos:aws-lambda)[Lambda] in vpc
    service db(logos:aws-dynamodb)[DynamoDB] in vpc
    service s3(logos:aws-s3)[S3 Bucket]

    api:R --> L:lambda
    lambda:R --> L:db
    lambda:B --> T:s3

重要： architecture-beta 図で logos:* アイコンを使用するには、アイコンパックの登録が必要です。レンダースクリプトでレンダリングする場合は、--icons logos フラグを使用してください。アイコンパックに対応していない Markdown ビューアーでレンダリングする場合は、組み込みアイコン（cloud、database、disk、server、internet）を代わりに使用してください。アイコンの完全なカタログとレンダリング手順については、references/aws-architecture.md をお読みください。

すべての図の種類の構文について詳しくは、references/diagram-types.md をお読みください。

C4 図 — 必須のスタイル設定ガイド

C4 図には**固定の要素スタイル（システムは青いボックス、人物はグレーなど）**がありますが、関係線はデフォルトで強い黒色になり、視覚的なノイズが生じます。次のスタイル設定ルールを必ず適用してください。

C4 スタイル設定パターン

すべての C4 図には、末尾に次のディレクティブを必ず含めてください。

    %% === MANDATORY STYLING ===
    %% Apply soft line colors to ALL relationships
    UpdateRelStyle(fromAlias, toAlias, $textColor="#475569", $lineColor="#94a3b8")
    %% Repeat for each Rel() in the diagram

    %% Optimize layout spacing
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

C4 の色の値のリファレンス

用途	色	Hex	備考
ソフトな線の色	Slate-400	#94a3b8	強いデフォルトの黒色を置き換えます
線のテキスト色	Slate-600	#475569	読みやすく、目立ちすぎません
アクセント線	Blue-400	#60a5fa	強調表示または主要な関係に使用します
警告線	Amber-500	#f59e0b	外部接続またはリスクのある接続に使用します
カスタム要素の背景	Emerald	#10b981	データストアまたは成功の強調表示に使用します
カスタム要素の背景	Indigo	#4f46e5	主要システムの強調表示に使用します

C4 レイアウトのヒント

重要 — 1 つの図につき Rel() は最大 6 個です。 関係が 6 個を超えると、Dagre が矢印をノードの上に通すように配置し、読みにくく複雑になります。システムにさらに多くの接続が必要な場合は、焦点を絞った複数の図に分割してください。

• ほとんどの図では $c4ShapeInRow="3" を使用します（横方向の混雑を防ぎます）
• ラベルが長い図では $c4ShapeInRow="2" を使用します
• $c4BoundaryInRow="1" は常に使用します（境界を縦に積み重ねて見やすくします）
• ラベルが要素と重なる場合は、UpdateRelStyle に $offsetY="-10" を適用します
• メッシュ状のトポロジよりも、ツリー状のトポロジ（ノードあたり入力 1 つ、出力 1～2 つ）を優先します
• フローの順に要素を宣言します — Container() 宣言の順序はレイアウトに影響します
• 自動レイアウトで重なりが生じる場合に限り、最後の手段として方向を指定する Rel_D、Rel_R などを使用します

C4 の構文、例、パターンについて詳しくは、references/c4-architecture.md をお読みください。

ステップ 3：検証

レンダリングする前に、Mermaid の構文を必ず検証してください。

node $SKILL_DIR/scripts/validate.mjs <file.mmd>

検証に失敗した場合：

1. エラーメッセージを注意深く読みます
2. よくある修正方法については references/troubleshooting.md を参照します
3. 構文を修正して、再検証します
4. ユーザーに確認を求める前に修正を試みるのは最大 3 回までです

ステップ 4：レンダリング

4.1 — セットアップ（初回のみ）

bash $SKILL_DIR/scripts/setup.sh

レンダリングエンジンとアイコンパックの依存関係を両方とも自動インストールします。環境ごとに一度実行してください。

4.2 — 単一の図のレンダリング

# SVG (default — best quality)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.svg

# PNG (for documents/presentations)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.png --width 1200

# ASCII (for terminals/READMEs)
node $SKILL_DIR/scripts/render-ascii.mjs -i diagram.mmd

# With icon packs (architecture-beta with AWS/tech icons)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.svg --icons logos,fa

--icons フラグは、レンダリング前に Iconify パックを登録します。パック：logos（AWS／テクノロジー）、fa（Font Awesome）。AWS には logos を使用してください。

4.3 — 一括レンダリング

複数の図を一度にレンダリングするには：

node $SKILL_DIR/scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme default \
  --workers 4

4.4 — 利用可能なテーマ

beautiful-mermaid（15）： tokyo-night | tokyo-night-storm | tokyo-night-light | dracula | nord | nord-light | catppuccin-mocha | catppuccin-latte | github-dark | github-light | solarized-dark | solarized-light | one-dark | zinc-dark | zinc-light

mermaid-cli ネイティブ（5）： default | forest | dark | neutral | base

カスタムテーマ：--theme base --config '{"theme":"base","themeVariables":{"primaryColor":"#4f46e5","lineColor":"#94a3b8"}}'

テーマの全カタログについては、references/themes.md をお読みください。レンダリングスクリプトは最適なエンジンを自動選択します（mmdc を優先し、beautiful-mermaid をフォールバックとして使用し、アイコンパックには Puppeteer を使用します）。

ステップ 5：コードから図を作成する（依頼された場合）

既存のコードやアーキテクチャを可視化するようユーザーから依頼された場合：

1. 分析方法について references/code-to-diagram.md を読みます
2. コードベースを分析し、適切な図の種類を特定します：
   • モジュールの依存関係 → フローチャートまたはクラス図
   • API ルートとハンドラー → シーケンス図
   • データベースのモデル／スキーマ → ERD
   • サービスアーキテクチャ → C4 コンテナー図またはアーキテクチャ図
   • コード内のステートマシン → ステート図
3. 適切な init ディレクティブを含めて .mmd ファイルを生成します（ゴールデンルール 1）
4. 通常どおり検証してレンダリングします

トラブルシューティング早見表

症状	考えられる原因	対処方法
図がレンダリングされない	構文エラー	validate.mjs を実行し、括弧／引用符を確認します
ラベルが切れている	テキストが長すぎる	ラベルを短くするか、改行 <br/> を使用します
レイアウトがおかしい	方向が不適切	TD／LR／BT／RL を変更してみます
ノードが重なっている	ノードが多すぎる	サブグラフまたは複数の図に分割します
線が暗すぎる／太すぎる	init ディレクティブがない	lineColor: '#94a3b8' を指定した %%{init} を追加します
C4 の線が重なっている	スタイルが適用されていない	各 Rel にオフセットを指定した UpdateRelStyle を追加します
AWS アイコンが表示されない	アイコンパックがない	--icons logos フラグを使用するか、組み込みアイコンに切り替えます
mmdc が見つからない	インストールされていない	setup.sh を実行します
テーマが適用されない	エンジンが違う	beautiful-mermaid のテーマは、そのエンジンでのみ動作します

トラブルシューティングの詳細については、references/troubleshooting.md をお読みください。

出力規約

• レンダリング済みの出力と同じ場所に .mmd ソースファイルを保存します
• 命名規則：{purpose}-{type}.mmd（例：auth-flow-sequence.mmd）
• 一括処理の場合：入力ファイル名を維持し、拡張子を変更します
• .mmd ソースとレンダリング済みファイルの両方を必ずユーザーに提供します