Mermaid Studio

エキスパートレベルのMermaidダイアグラム作成、検証、マルチフォーマットレンダリング。説明またはコード解析からダイアグラムを作成し、構文を検証して、プロフェッショナルなテーマでSVG、PNG、またはASCIIにレンダリングします。

ゴールデンルール — デフォルトでエレガントなダイアグラムを

すべてのダイアグラムは、これらの原則に従う必要があります。オプションではありません — これらは凡庸なダイアグラムと金標準的なダイアグラムの違いを定義します。

ルール1: プロフェッショナルなスタイリングのための初期化ディレクティブを常に使用する

決して %%{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スタイリングセクションを参照してください。

アーキテクチャベータダイアグラムの場合 — 以下の専用AWS/アーキテクチャセクションを参照してください。

ルール2: 柔らかい線、厳しい黒は避ける

単一の最大の視覚的改善は、デフォルトの黒の代わりに lineColor: '#94a3b8'(スレート400)を使用することです。これは現代的で通気性の良いダイアグラムを作成します。ダークテーマの場合は、lineColor: '#64748b'(スレート500)を使用してください。

ルール3: 密度を制限 — 余白を確保する

• 最大15ノード/ダイアグラム(20ではなく — 少ないほうがエレガント)
• subgraph または境界線を使用して、余白と視覚的グループ化を作成
• プロセスフローの場合はLR(左から右)を推奨 — より自然に読めます
• レイアウトが窮屈な場合は、目に見えないリンク(A ~~~ B)を使用して間隔を追加

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

• ノードID: キャメルケース(orderService。s1やosではなく)
• ラベル: 短い、明確な自然言語([Order Service])
• 矢印: アクション動詞とプロトコル情報("Sends order via gRPC")
• 説明: ワンライン、役割に焦点("Handles order lifecycle")

ルール5: 色彩の多様性より調和を優先

ダイアグラムあたり最大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. エレガンスを最優先 — すべてのダイアグラムは初期化ディレクティブと調整されたカラーでプロフェッショナルに見える必要があります
2. 正確性 — エラーなくレンダリングされる有効な構文
3. 明確性 — 意味のあるラベル、論理的なフロー方向、明確な関係
4. シンプルさ — ダイアグラムあたり15ノード未満。複雑なシステムは複数に分割
5. 一貫性 — 統一的な命名(IDのキャメルケース、括弧内の説明的なラベル)

2.2 — 構造規則

%% Diagram: [目的] | Author: [自動] | Date: [自動]
%%{init: {'theme': 'base', 'themeVariables': { ... }}}%%
[ダイアグラムタイプ]
    [コンテンツ]

重要: %%{init} ディレクティブはダイアグラムタイプ宣言の前に、非コメント行の最初に配置する必要があります。または、ファイルの最初の絶対位置でYAMLフロントマターを使用します。

命名規則:

• ノードID: キャメルケース、説明的(orderService。s1ではなく)
• ラベル: 括弧内の自然言語([Order Service])
• 関係: アクション動詞("Sends order to"、"Reads from")

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

• 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

重要: アイコンパック登録が必要なlogos:*アイコン付きアーキテクチャベータダイアグラム。renderスクリプトでレンダリングする場合は、--icons logos フラグを使用してください。アイコンパックをサポートしていないマークダウンビューアーでレンダリングする場合は、フォールバックとして組み込みアイコン(cloud、database、disk、server、internet)を使用してください。完全なアイコンカタログとレンダリング指示については、references/aws-architecture.md を参照してください。

すべてのダイアグラムタイプの包括的な構文については、references/diagram-types.md を参照してください。

C4ダイアグラム — 必須スタイリングガイド

C4ダイアグラムは固定要素スタイリング(システムは青ボックス、人物はグレー等)を備えていますが、その関係線はデフォルトで厳しい黒で視覚的なノイズを作成します。これらのスタイリング規則を適用する必要があります:

C4スタイリングパターン

すべてのC4ダイアグラムは、末尾に以下のディレクティブを含む必要があります:

    %% === 必須スタイリング ===
    %% すべての関係に柔らかい線色を適用
    UpdateRelStyle(fromAlias, toAlias, $textColor="#475569", $lineColor="#94a3b8")
    %% ダイアグラム内のすべてのRel()に対して繰り返す

    %% レイアウト間隔を最適化
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

C4カラー値リファレンス

目的	色名	Hex	備考
柔らかい線色	スレート400	#94a3b8	厳しいデフォルト黒を置き換え
線テキスト色	スレート600	#475569	読みやすいが支配的ではない
アクセント線	ブルー400	#60a5fa	ハイライトまたはプライマリ関係向け
警告線	琥珀500	#f59e0b	外部/リスク接続向け
カスタム要素背景	エメラルド	#10b981	データストアまたは成功強調向け
カスタム要素背景	インディゴ	#4f46e5	プライマリシステム強調向け

C4レイアウトのコツ

重要 — ダイアグラムあたり最大6つのRel()。 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

これは両方のレンダリングエンジンとアイコンパック依存関係を自動インストールします。環境ごとに1回実行します。

4.2 — 単一ダイアグラムレンダリング

# SVG(デフォルト — 最高品質)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.svg

# PNG(ドキュメント/プレゼンテーション向け)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.png --width 1200

# ASCII(ターミナル/README向け)
node $SKILL_DIR/scripts/render-ascii.mjs -i diagram.mmd

# アイコンパック付き(AWSテックアイコン付きアーキテクチャベータ)
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 を参照してください。renderスクリプトは最適なエンジン(mmdc優先、beautiful-mermaidフォールバック、アイコンパック用Puppeteer)を自動選択します。

ステップ5: コードからダイアグラムへ(リクエストされた場合)

ユーザーが既存のコードまたはアーキテクチャを可視化するよう求める場合:

1. 分析方法については references/code-to-diagram.md を読む
2. コードベースを分析して適切なダイアグラムタイプを特定:
   • モジュール依存関係 → フローチャートまたはクラス図
   • APIルートとハンドラー → シーケンス図
   • データベースモデル/スキーマ → ERD
   • サービスアーキテクチャ → C4コンテナまたはアーキテクチャ図
   • コード内のステートマシン → ステート図
3. 適切な初期化ディレクティブ付き .mmdファイルを生成(ゴールデンルール1)
4. 通常通り検証とレンダリングを実行

トラブルシューティングクイックリファレンス

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

包括的なトラブルシューティングについては、references/troubleshooting.md を参照してください。

出力