サイオステクノロジー（Tech.Lab）の技術ブログ

全628件

2026/02/24

Mermaidの見た目、もうちょっとなんとかならんかども！Mermaidで図を作るたびに「構造は最高なんだけど、見た目がなぁ…」と思ってた龍ちゃんです。「 Claude CodeでMermaid図を作成する」でMermaid図の自動生成について書きました。Mermaidはコードで構造を書けるから、フローチャートやシーケンス図がサクッと作れます。AIに「こういう図作って」って言えば一発で出てくるんですよね。ただ、デフォルトのデザインがシンプルすぎるんですよね。設計書やブログに貼るにはちょっと素朴。 HTML+Tailwind CSSで図解を丸投げする方法も試したんですよ。装飾の自由度は高いんですけど、フロー図やシーケンス図をCSSで手動配置するのが辛い。特に矢印の表現が鬼の難易度です。Mermaidが自動でやってくれる部分を手で書くのはしんどいです。じゃあ合体させたらどうだ、と。 Mermaidの構造表現力 + Tailwind CSSの装飾力。Mermaidに図の構造を任せて、周りの見た目はTailwindで自由に作れます。これを1つのHTMLファイルにまとめてPNGに変換します。今回の内容です。コピペで使えるHTMLテンプレート2種（右サイド注釈型 / 下部グリッド注釈型）色を揃えるカスタマイズのコツ実際にぶつかった壁と対処法 PNG変換の手段3つまず完成形を見せますこういうのが作れます。左がMermaidで描画したシーケンス図、右がTailwind CSSで装飾した注釈パネル。これ、1つのHTMLファイルから出てきます。ポイントは、Mermaid図の色とTailwind装飾の色が揃ってるところですね。青系で統一してるから、「Mermaidの部分だけ浮いてる」みたいなことにならない。注釈パネルには設計ポイント、セキュリティ考慮、エラーハンドリングみたいな文脈情報を書けます。Mermaid図だけだと「何が起きてるか」は分かるけど「なぜこうしたか」は伝わらないんですよね。注釈パネルがその「なぜ」を補ってくれます。関連記事 : 仕様書の図でAIの理解と人間の視認性を両立する方法に関しては「仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン」で詳しく書いてます。AIに図の構造を正確に伝えたい人はこちらもどうぞ。テンプレートA: 右サイド注釈型ここからが本題です。コピペして使えるHTMLテンプレートを2種類用意しました。仕組みはシンプルで、1つのHTMLにTailwind CDNとMermaid CDN（ESM版）を同時に読み込んでるだけです。2つのCDNは競合しません（検証済み）。テンプレートをコピペすればそのまま動きます。色のカスタマイズについてはテンプレートの後で説明しますね。まずはテンプレートA。冒頭で見せた完成形がこれです。左にMermaid図、右に注釈パネルを並べるレイアウトですね。向いてる場面 : シンプルな図（ノード8個以下）に設計ポイントを3-4個添えたいときキャンバスサイズ : 1280x720px <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Level 2: Mermaid + Tailwind CSS Decoration</title> <script src="https://cdn.tailwindcss.com"></script> </head> <body class="w-[1280px] h-[720px] m-0 p-0 overflow-hidden bg-white"> <div class="w-full h-full flex gap-6 p-10">  <div class="flex-1 border-2 border-blue-300 rounded-lg p-6 bg-blue-50"> <h2 class="text-xl font-bold text-blue-900 mb-4">認証フローのシーケンス図</h2> <div class="mermaid"> sequenceDiagram participant C as クライアント participant S as サーバー participant DB as データベース C->>+S: ログインリクエスト S->>+DB: ユーザー照合 DB-->>-S: 認証結果 alt 認証成功 S-->>C: アクセストークン発行 else 認証失敗 S-->>C: エラーレスポンス(401) end </div> </div>  <div class="w-72 flex flex-col gap-3"> <div class="bg-yellow-50 border border-yellow-300 rounded p-3"> <h3 class="text-sm font-bold text-yellow-800">設計ポイント</h3> <p class="text-xs text-yellow-700">DB直接参照を避け、サービス層を経由させることで結合度を低減</p> </div> <div class="bg-green-50 border border-green-300 rounded p-3"> <h3 class="text-sm font-bold text-green-800">セキュリティ考慮</h3> <p class="text-xs text-green-700">トークンはJWT形式、有効期限15分で自動失効</p> </div> <div class="bg-red-50 border border-red-300 rounded p-3"> <h3 class="text-sm font-bold text-red-800">エラーハンドリング</h3> <p class="text-xs text-red-700">認証失敗時は具体的なエラー原因を返さない（セキュリティ対策）</p> </div> </div> </div> <script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true, theme: 'base', themeVariables: { primaryColor: '#dbeafe', primaryBorderColor: '#3b82f6', lineColor: '#6b7280', fontFamily: 'system-ui, sans-serif' } }); </script> </body> </html> 使い方はシンプルで、3箇所を差し替えるだけです。 Mermaid記法の部分（ <div class="mermaid"> の中身）を自分の図に差し替える注釈パネルの内容（右側の3つのパネル）を自分の設計ポイントに差し替える themeVariables で色を変えたければカラーコードを調整する注釈パネルは増減しても大丈夫です。3個が収まりいいですけど、2個でも4個でもレイアウトは崩れません。色の統一について完成形の画像を見て「Mermaid図と注釈パネルの色が揃ってるな」と思った人もいるかもしれません。これはテンプレート末尾の themeVariables でMermaid図の配色をTailwindのカラーパレットに合わせてるからです。 themeVariables: { primaryColor: '#dbeafe', // Tailwind blue-100 primaryBorderColor: '#3b82f6', // Tailwind blue-500 lineColor: '#6b7280', // Tailwind gray-500 fontFamily: 'system-ui, sans-serif' } 色を変えたいときはここのカラーコードを差し替えてください。 Tailwindのカラーパレットから持ってくると注釈パネル側と揃えやすいです。 1つ注意点として、 Mermaid図の中にTailwindクラスは効きません。Mermaid図はSVGとして生成されるんで、外部CSSが適用できないんですよね。色のカスタマイズは themeVariables 経由のみです。テンプレートB: 下部グリッド注釈型テンプレートAだと、図が複雑になったときに左側のスペースが足りなくなります。シーケンス図で参加者が4人以上いたり、メッセージが10本近くあると、右の注釈パネルに幅を取られて図が窮屈になるんですよね。そういうときはテンプレートBです。図を上部に全幅で配置して、注釈パネルは下部にグリッドで並べます。向いてる場面 : 複雑な図（10ステップ近いシーケンス、状態遷移図）で図に全幅を使いたいときキャンバスサイズ : 1280x1080px（縦に拡張） <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>OAuth 2.0 認可コードフロー</title> <script src="https://cdn.tailwindcss.com"></script> <style> .mermaid svg { transform: scale(3.2); transform-origin: center center; } </style> <script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true, theme: 'base', sequence: { diagramMarginX: 10, diagramMarginY: 10, actorMargin: 80, messageMargin: 40 }, themeVariables: { primaryColor: '#e0f2fe', primaryBorderColor: '#0284c7', primaryTextColor: '#0c4a6e', lineColor: '#64748b', fontFamily: 'system-ui, sans-serif' } }); </script> </head> <body class="w-[1280px] h-[1080px] m-0 p-0 overflow-hidden bg-white"> <div class="w-full h-full flex flex-col p-8 gap-6">  <div> <div class="text-lg font-bold text-gray-800">OAuth 2.0 認可コードフロー</div> <div class="text-sm text-gray-500">ソーシャルログイン実装の標準パターン</div> </div>  <div class="flex-1 border border-gray-200 rounded-lg p-6 bg-gray-50 flex items-center justify-center"> <div class="mermaid"> sequenceDiagram actor U as ユーザー participant App as Webアプリ participant Auth as 認可サーバー participant API as リソースサーバー U->>App: ログインボタンクリック App->>Auth: 認可リクエスト(client_id, redirect_uri, scope) Auth->>U: ログイン画面表示 U->>Auth: 認証情報入力 Auth->>App: 認可コード(code) App->>Auth: トークンリクエスト(code, client_secret) Auth->>App: アクセストークン + リフレッシュトークン App->>API: APIリクエスト(Bearer token) API->>App: リソースデータ App->>U: ユーザー情報表示 </div> </div>  <div class="grid grid-cols-4 gap-3"> <div class="bg-blue-50 border border-blue-200 rounded-lg p-3"> <div class="text-sm font-bold text-blue-800">フロー概要</div> <div class="text-xs text-blue-700 mt-1">RFC 6749準拠の認可コードグラント。SPAではPKCE拡張を推奨。</div> </div> <div class="bg-amber-50 border border-amber-200 rounded-lg p-3"> <div class="text-sm font-bold text-amber-800">セキュリティ要件</div> <div class="text-xs text-amber-700 mt-1 space-y-1"> <div>state パラメータでCSRF対策</div> <div>client_secret はサーバー側で保持</div> <div>redirect_uri の完全一致検証</div> </div> </div> <div class="bg-green-50 border border-green-200 rounded-lg p-3"> <div class="text-sm font-bold text-green-800">実装チェックリスト</div> <div class="text-xs text-green-700 mt-1 space-y-1"> <div>トークンの安全な保存（httpOnly cookie）</div> <div>リフレッシュトークンのローテーション</div> <div>スコープの最小権限原則</div> </div> </div> <div class="bg-gray-100 border border-gray-200 rounded-lg p-3"> <div class="text-sm font-bold text-gray-700">補足</div> <div class="text-xs text-gray-600 mt-1">アクセストークンの有効期限は15分〜1時間が一般的。期限切れ時はリフレッシュトークンで自動更新。</div> </div> </div> </div> </body> </html> テンプレートAとの違いは3つです。キャンバスが縦に拡張（720px → 1080px）。図に余裕ができます注釈パネルが下部グリッド。図が全幅を使えるんで、参加者が4人いても窮屈になりません CSS transformでMermaid図を拡大（ scale(3.2) ）。Mermaidは複雑な図を自動縮小するんで、それを補正してます scaleの調整についてテンプレートBの scale(3.2) は、上のOAuth 2.0の例（参加者4人・メッセージ10本）に合わせた値です。自分の図に差し替えたら、scaleも調整が必要です。 Mermaidは図の複雑度に応じて自動縮小するんですけど、その縮小率が図ごとに変わるんですよね。なので図を差し替えるたびにscaleを微調整するのが前提の設計です。調整の手順はシンプルで、HTMLファイルをブラウザで開いて、文字が読める大きさになるまで scale の数値を上げ下げするだけです。目安としてはこんな感じ。図の複雑度 scale目安シンプル（参加者2-3人、メッセージ5本以下） 1.5〜2.0 中程度（参加者3-4人、メッセージ8本前後） 2.5〜3.5 複雑（参加者4人以上、メッセージ10本以上） 3.0〜4.0 どっちを使う？条件テンプレート図がシンプル（ノード8以下） A: 右サイド注釈型図が複雑、横に広がる B: 下部グリッド注釈型注釈が少ない（2-3個） A 注釈が多い（4個以上） B 迷ったらまずテンプレートAで試して、図が窮屈ならBに切り替える、でいいと思います。ぶつかった壁と対処検証してて何度かハマったので、先に共有しておきます。ノード数には上限がある Mermaidは図の要素が増えると自動で縮小するんですよね。1280pxの幅に収めようとするから、ノードが多いと文字が潰れて読めなくなります。実際に検証して、このくらいが上限だなというラインが見えました。図の種類推奨上限超えるとどうなるかフローチャート 8-10ノード文字が小さくなって読めないシーケンス図 4参加者・8メッセージラベルが長いと自動縮小される状態遷移図 8-10状態縦に伸びてキャンバスからはみ出す上限を超えそうなときは、図を分割するか、テンプレートBでキャンバスを拡張するのがいいです。サイズ問題の対策3種実際にぶつかったサイズ問題と、それぞれの対処法です。症状対策やり方図がキャンバスからはみ出すキャンバスを拡張する h-[720px] → h-[1080px] に変更。PNG変換時も --height 1080 を指定図が小さすぎて読めない CSS transformで拡大 .mermaid svg { transform: scale(X); } を追加右の注釈パネルが図を圧迫する注釈を下部に移動テンプレートAからBに切り替えるこの3つの対策は組み合わせられます。テンプレートBはキャンバス拡張 + CSS transform + 下部グリッドの3つ全部入りですね。制約はあるけど対策は全部見つかってるんで、複雑な図はまずBを試してみてください。 PNG変換 — 3つの手段 HTMLファイルが完成したら、PNG画像に変換してブログや設計書に貼れます。手段は3つあって、好みと環境に合わせて選んでください。手段自動化セットアップ向いてる用途 CLIツール（html-screenshot）できる Python + Playwright 量産やCI/CD Playwright MCP できる MCP設定 Claude Code連携ブラウザで直接開く手動なし手軽に確認 CLIツール uv run html-screenshot --file template-a.html --output template-a.png 以前の記事で紹介したhtml-screenshotツールがそのまま使えます。改修なしでMermaid CDNの読み込みにも対応してました。Playwrightの wait_until="networkidle" がCDN読み込み完了を待ってくれるんで、Mermaid図の描画が終わってからスクリーンショットを撮ってくれます。テンプレートBのように高さを変えたい場合は --height 1080 を付けます。 Playwright MCP Claude CodeからPlaywrightのブラウザ操作を直接呼び出す方法もあります。HTMLファイルを開いてスクリーンショットを撮る操作がMCPのツールで完結します。 Playwright MCPの記事で詳しく書いてるんで、Claude Code使ってる人はこっちが楽かもしれません。ブラウザで直接開く一番手軽なのはHTMLファイルをブラウザで直接開くことですね。Mermaid CDNが読み込まれて図がそのまま描画されます。PNG変換は手動（ブラウザのDevToolsやOS標準のスクリーンショット）になりますけど、「ちょっと確認したい」くらいならこれで十分です。まとめノード数の上限やサイズ問題はありましたけど、全部対処法が見つかりました。制約を把握しておけばハマることはないです。今回のポイントです。「構造はMermaid、装飾はTailwind」の役割分担。Mermaidが得意な構造の自動レイアウト（矢印の接続、参加者の配置、分岐の描画）はMermaidに任せて、周りの装飾（注釈パネル、色統一、レイアウト）はTailwind CSSで自由に作る。テンプレートの使い分けはシンプルです。条件テンプレートシンプルな図 + 注釈少なめ A: 右サイド注釈型（1280×720）複雑な図 + 注釈多め B: 下部グリッド注釈型（1280×1080）あと、おまけとして1つ。このテンプレートで作った図はAI連携にも強いです。Mermaidのソースコードは宣言的な記法（ sequenceDiagram 、 graph TD とか）なんで、AIが構造を正確に読み取れます。注釈パネルに設計意図を書いておけば、人間が見ても、AIが読んでもどっちにも伝わる。この辺の話は仕様書の図にソースコードを添える設計パターンで詳しく書いてるんで、興味あれば読んでみてください。もう1つ。このテンプレートを毎回コピペするのも手ですけど、Claude Codeの SKILL機能にreference（参考例）として登録しておくと、「シーケンス図作って」と言うだけでテンプレートに沿った図が出てきます。テンプレートのクオリティがそのままSKILLのクオリティになるんで、良いテンプレートを貯める = 図解の品質を底上げする、という流れができます。コピペ用テンプレートとSKILL化、好きなほうで使ってください。 PlantUML編も書きました。Mermaidが苦手な図種（アクティビティ図、ユースケース図、コンポーネント図）をPlantUMLでカバーする話です。「 PlantUMLの表現力をTailwind CSSで設計書品質に仕上げる」をどうぞ。ほなまた〜関連ブログ今回の記事はシリーズの一部です。Mermaid図の生成からHTML図解、仕様書への活用まで、一連の流れで読めます。 ClaudeでMermaid図作成を自動化！プロンプトテンプレート集も公開 — 今回の出発点。Mermaid記法をAIで生成するところから始めたい人はここから。プロンプトテンプレートも載せてます。図解作成、AIに丸投げしたら「たまに自分より上手い」件 — HTML+Tailwind CSSで図解を丸ごとAIに作らせる方法。フロー図以外の図解（比較図、アーキテクチャ図とか）はこっちが向いてます。仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン — 仕様書をAIと共有してるチーム向け。図にソースコードと設計意図を添えて、AIの「推測」をなくす方法です。 Playwright MCPで始めるブラウザ自動化 — PNG変換の手段の1つとして紹介したPlaywright MCP。Claude Codeからブラウザ操作を直接呼び出せます。ご覧いただきありがとうございます！この投稿はお役に立ちましたか？役に立った役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post Mermaidのデザインが物足りない？Tailwindで拡張して設計書品質に first appeared on SIOS Tech Lab .

サイオステクノロジー（Tech.Lab） の技術ブログ

コンテンツ

サイオステクノロジー（Tech.Lab）の技術ブログ