visual-explainer

ビジュアル解説

技術図、ビジュアライゼーション、データテーブル用の自己完結型 HTML ファイルを生成します。結果は必ずブラウザーで開いてください。このスキルが読み込まれている場合、ASCII アートに切り替えないでください。

積極的なテーブルのレンダリング。 ターミナルで ASCII の罫線テーブルとして表形式データ（比較、監査、機能マトリクス、ステータスレポートなど、行と列で構成されるデータ）を提示しようとしている場合は、代わりに HTML ページを生成してください。基準は、テーブルが 4 行以上または 3 列以上ある場合は、ブラウザーで表示することです。ユーザーに頼まれるまで待たず、自動的に HTML としてレンダリングし、ファイルパスを伝えてください。チャットには簡潔な概要を記載してもかまいませんが、テーブル自体は HTML ページにしてください。

ワークフロー

1. 考える（5 秒。5 分ではありません）

HTML を書く前に、方向性を決めます。毎回「青のアクセントが効いたダークテーマ」に安易に頼らないでください。

誰が見るのか？ システムを理解しようとしている開発者でしょうか？ 全体像を把握しようとしている PM でしょうか？ 提案をレビューするチームでしょうか？ これによって情報密度やビジュアルの複雑さが決まります。

図の種類は？ アーキテクチャ、フローチャート、シーケンス図、データフロー、スキーマ／ER 図、状態遷移図、マインドマップ、データテーブル、タイムライン、ダッシュボードなどです。それぞれに適したレイアウトやレンダリング方法があります（以下の「図の種類」を参照）。

どんな美的スタイルにするか？ ひとつ選び、それに徹してください。

• モノクロのターミナル（黒地に緑／アンバー、すべて等幅フォント）
• エディトリアル（セリフ体の見出し、ゆったりした余白、落ち着いた配色）
• 設計図（技術図面の雰囲気、グリッド線、正確さ）
• ネオンのダッシュボード（深いダークカラーに彩度の高いアクセント、光るエッジ）
• 紙とインク（温かみのあるクリーム色の背景、手描き風、ラフな枠線）
• 手描き／スケッチ（Mermaid の handDrawn モード、波打つ線、気軽なホワイトボードの雰囲気）
• IDE 風（Dracula、Nord、Catppuccin、Solarized、Gruvbox、One Dark など、実在する配色を取り入れる）
• データ重視（小さな文字、狭い間隔、最大限の情報量）
• グラデーションメッシュ（大胆なグラデーション、グラスモーフィズム、モダンな SaaS の雰囲気）

選ぶスタイルは毎回変えてください。前回の図がダークで技術的だったなら、次は明るくエディトリアルなものにします。入れ替えテスト：スタイルを一般的なダークテーマに置き換えても誰も違いに気づかないなら、デザインできていません。

2. 構成する

生成する前に、参照テンプレートを読んでください。 暗記するのではなく、パターンを把握するために毎回読みます。

• テキスト中心のアーキテクチャ概要（トポロジーよりカードの内容が重要な場合）：./templates/architecture.html を読みます
• フローチャート、シーケンス図、ER 図、状態遷移図、マインドマップの場合：./templates/mermaid-flowchart.html を読みます
• データテーブル、比較、監査、機能マトリクスの場合：./templates/data-table.html を読みます

CSS／レイアウトのパターンや SVG のコネクターについては、 ./references/css-patterns.md を読んでください。

4 セクション以上のページ（レビュー、振り返り、ダッシュボードなど）では、デスクトップの固定サイドバー目次とモバイルの横スクロール可能なバーによるセクションナビゲーションについて、./references/responsive-nav.md も読んでください。

レンダリング方法の選択：

図の種類	アプローチ	理由
アーキテクチャ（テキスト中心）	CSS Grid のカード＋フロー矢印	説明、コード、ツール一覧など、カードに豊富な内容を含めるには CSS による制御が必要です
アーキテクチャ（トポロジー中心）	Mermaid	コンポーネント間の接続を見やすくするには、エッジの自動ルーティングが必要です
フローチャート／パイプライン	Mermaid	ノードの自動配置とエッジのルーティングが可能です。手描きモードも利用できます
シーケンス図	Mermaid	ライフライン、メッセージ、アクティベーションボックスには自動レイアウトが必要です
データフロー	エッジラベル付きの Mermaid	接続とデータの説明には、エッジの自動ルーティングが必要です
ER／スキーマ図	Mermaid	多数のエンティティ間のリレーション線には、自動ルーティングが必要です
ステートマシン	Mermaid	ラベル付きエッジによる状態遷移には自動レイアウトが必要です
マインドマップ	Mermaid	階層的な分岐には自動配置が必要です
データテーブル	HTML <table>	セマンティックなマークアップ、アクセシビリティ、コピー＆ペースト時の動作に優れています
タイムライン	CSS（中央線＋カード）	シンプルな線形レイアウトには、レイアウトエンジンは必要ありません
ダッシュボード	CSS Grid＋Chart.js	チャートを埋め込んだカードのグリッドです

Mermaid のテーマ設定： 色をページのカラーパレットに合わせるため、必ず theme: 'base' とカスタムの themeVariables を使用してください。スケッチ風にするには look: 'handDrawn'、すっきりした線にするには look: 'classic' を使用します。複雑なグラフには layout: 'elk' を使用してください（@mermaid-js/layout-elk パッケージが必要です。CDN のインポートについては ./references/libraries.md を参照してください）。Mermaid の SVG クラスを CSS で上書きすると、ピクセル単位で細かく制御できます。テーマ設定の詳細については ./references/libraries.md を参照してください。

Mermaid のズームコントロール： すべての .mermaid-wrap コンテナに、ズームコントロール（＋／−／リセットボタン）を必ず追加してください。複雑な図は小さく表示されるため、読みやすくするにはズームが必要です。コンテナ上での Ctrl／Cmd＋スクロールによるズームも実装してください。ズームコントロールのパターンについては ./references/css-patterns.md を、参照テンプレートについては ./templates/mermaid-flowchart.html を参照してください。

AI 生成イラスト（任意）。 surf-cli が利用できる場合は、Gemini で画像を生成し、創造的、説明的、教育的、または装飾的な目的でページに埋め込むことができます。which surf で利用可能か確認してください。利用可能な場合：

# Generate to a temp file (use --aspect-ratio for control)
surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9

# Base64 encode for self-containment (macOS)
IMG=$(base64 -i /tmp/ve-img.png)
# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)

# Embed in HTML and clean up
# <img src="data:image/png;base64,${IMG}" alt="descriptive alt text">
rm /tmp/ve-img.png

画像コンテナのスタイル（ヒーローバナー、インラインイラスト、キャプション）については ./references/css-patterns.md を参照してください。

使用する場面： ページの視覚的なトーンを決めるヒーローバナー。Mermaid では表現できない抽象的なシステム（物理インフラ、ユーザージャーニー、メンタルモデル）の概念図。芸術的またはフォトリアリスティックな描画が効果的な教育用の図。デザインの方向性を補強する装飾的なアクセント。

使用を避ける場面： Mermaid または CSS で適切に表現できるもの。意味を伝えない一般的な装飾。画像が目を散らす、データ量の多いページ。必ず適切にフォールバックできるようにしてください。surf が利用できない場合は、エラーを出さずに画像を省略します。ページは CSS とタイポグラフィだけでも十分に成立する必要があります。

プロンプトの作成： 画像の配色と美的な方向性をページに合わせてください。スタイル（3D レンダリング、技術イラスト、水彩画、アイソメトリック、フラットベクターなど）を指定し、CSS 変数で使われている主要な色に触れてください。ヒーローバナーには --aspect-ratio 16:9、インラインイラストには --aspect-ratio 1:1 を使用します。プロンプトは具体的にしてください。「暗いネイビーの背景にシアンのノードを配置した、メッセージキューのアイソメトリックイラスト」は「キューの図」よりも効果的です。

3. スタイル

すべての図に、次の原則を適用してください。

タイポグラフィが図の印象を決めます。 Google Fonts から個性のあるフォントの組み合わせを選んでください。特徴的な見出し用フォントと、技術的なラベル向けの等幅フォントを組み合わせます。Inter、Roboto、Arial、system-ui を主要フォントとして使用しないでください。<head> 内の <link> から読み込みます。オフラインでも表示できるよう、font-family のスタックにシステムフォントのフォールバックを含めてください。

色でストーリーを伝えます。 パレット全体に CSS カスタムプロパティを使用してください。最低限、--bg、--surface、--border、--text、--text-dim と、3〜5 個のアクセントカラーを定義します。各アクセントには、背景用の通常版と暗色版を用意してください。可能な場合は、--blue-3 ではなく --pipeline-step のように、意味が伝わる変数名を付けます。両方のテーマをサポートしてください。基本のデザインは :root に、もう一方のテーマはメディアクエリに記述します。

/* Light-first (editorial, paper/ink, blueprint): */
:root { /* light values */ }
@media (prefers-color-scheme: dark) { :root { /* dark values */ } }

/* Dark-first (neon, IDE-inspired, terminal): */
:root { /* dark values */ }
@media (prefers-color-scheme: light) { :root { /* light values */ } }

サーフェスは控えめに表現します。 大きく色を変えるのではなく、明度のわずかな差（レベルごとに 2〜4％）で奥行きを作ります。境界線には不透明度の低い rgba（ダークモードでは rgba(255,255,255,0.08)、ライトモードでは rgba(0,0,0,0.08)）を使用します。意識すれば見える程度で、普段は目立たないようにします。

背景で雰囲気を作ります。 ページの背景に単色を使わないでください。控えめなグラデーション、CSS による淡いグリッドパターン、または焦点となる領域の背後に柔らかな放射状の光を加えます。背景は何もない空間ではなく、ひとつの場として感じられるようにします。

視覚的な重みで重要性を示します。 すべてのセクションを同じように扱う必要はありません。エグゼクティブサマリーと重要な指標は、読み込み時のビューポートで目立つようにします（大きめの文字、広めの余白、アクセントカラーを薄く使った背景領域など）。ファイルマップ、依存関係の一覧、意思決定ログなどの参照セクションはコンパクトにし、目立ちすぎないようにします。主要な情報ではないものの役立つセクションには、<details>/<summary> を使用してください。折りたたみパターンについては ./references/css-patterns.md を参照してください。

サーフェスの奥行きで階層を作ります。 カードの奥行きを変えて、重要性を示してください。ヒーローセクションには、浮き上がったシャドウとアクセントカラーを薄く使った背景（node--hero パターン）を設定します。本文はフラットなままにします（標準の .node）。コードブロックや補足コンテンツは、奥まった印象にします（node--recessed）。奥行きの段階については ./references/css-patterns.md を参照してください。すべてを浮き上がらせないでください。すべてが目立つと、何も目立たなくなります。

アニメーションには役割を持たせます。 ページ読み込み時の段階的なフェードインは、図の階層に沿って視線を導けるため、ほとんどの場合に有効です。役割に応じてアニメーションの種類を使い分けます。カードには fadeUp、KPI とバッジには fadeScale、SVG コネクターには drawIn、ヒーローの数値には countUp を使用します。操作できるように見える要素にホバー時のトランジションを加えると、図に動きが生まれます。常に prefers-reduced-motion に対応してください。多くの場合、CSS トランジションとキーフレームで十分です。複数要素のシーケンスを連携させる場合は、CDN 経由で anime.js を利用できます（./references/libraries.md を参照）。

4. 出力

出力先： ~/.agent/diagrams/ に保存してください。内容に基づいた、分かりやすいファイル名を使用します。例：modem-architecture.html、pipeline-flow.html、schema-overview.html。このディレクトリの内容は、セッションをまたいで保持されます。

ブラウザーで開く：

• macOS：open ~/.agent/diagrams/filename.html
• Linux：xdg-open ~/.agent/diagrams/filename.html

ユーザーへの案内： ファイルを再度開いたり共有したりできるよう、ファイルパスを伝えてください。

図の種類

アーキテクチャ／システム図

どちらを重視するかに応じて、2つの方法があります。

テキスト中心の概要（接続よりもカードの内容を重視する場合）：行と列を明示的に配置する CSS Grid を使用します。セクションは、色付きの枠線と等幅フォントのラベルを備えた角丸カードにします。セクション間には縦方向のフロー矢印を配置します。サブシステムには入れ子のグリッドを使用します。./templates/architecture.html のリファレンステンプレートで、このパターンを確認できます。カードに説明、コード参照、ツール一覧など、Mermaid のノードには収まらない豊富なコンテンツが必要な場合に使用します。

トポロジー重視の図（カードの内容よりも接続を重視する場合）：Mermaid を使用します。 graph TD または graph LR にカスタムの themeVariables を指定すると、エッジが自動的にルーティングされ、適切な図を作成できます。カジュアルな雰囲気には look: 'handDrawn'、すっきりした線には look: 'classic' を使用します。各コンポーネントの詳細な説明よりも、コンポーネント同士の接続を示すことが主な目的の場合に使用します。

フローチャート／パイプライン

Mermaid を使用します。 ノードの自動配置とエッジの自動ルーティングにより、接続線、判断用のひし形、並列分岐を備えた適切な図を作成できます。矢印文字を使った CSS Flexbox よりもはるかに優れています。上から下への配置には graph TD、左から右への配置には graph LR を使用します。スケッチ風の見た目には look: 'handDrawn' を使用します。Mermaid の classDef でノードの種類を色分けするか、themeVariables による自動スタイル設定を使用します。

シーケンス図

Mermaid を使用します。 ライフライン、メッセージ、アクティベーションボックス、注記、ループには、いずれも自動レイアウトが必要です。Mermaid の sequenceDiagram 構文を使用します。.actor、.messageText、.activation クラスに CSS オーバーライドを適用して、アクターとメッセージのスタイルを設定します。

データフロー図

Mermaid を使用します。 データフロー図ではボックスよりも接続が重視されますが、これはまさに Mermaid が得意とする点です。データの説明をエッジラベルにして、graph LR または graph TD を使用します。主要なフローには、太く色の付いたエッジを使います。Mermaid の classDef で、ソース／シンクノードと変換ノードのスタイルを変えます。

スキーマ／ER 図

Mermaid を使用します。 エンティティ間のリレーションシップ線には、自動ルーティングが必要です。エンティティ属性を含めた Mermaid の erDiagram 構文を使用します。themeVariables と、.er.entityBox および .er.relationshipLine に対する CSS オーバーライドでスタイルを設定します。

状態マシン／決定木

Mermaid を使用します。 ラベル付きの遷移を持つ状態には stateDiagram-v2 を使用します。ネストされた状態、フォーク、ジョイン、注記に対応しています。カジュアルな状態図には look: 'handDrawn' を使用します。決定木には、ひし形の判断ノードを含む graph TD を使用できます。

stateDiagram-v2 のラベルに関する注意点： 遷移ラベルのパーサーは厳格です。コロン、括弧、<br/>、HTML エンティティ、その他ほとんどの特殊文字を含めると、エラーが表示されないまま解析に失敗します（「Syntax error in text」）。ラベルにこれらが必要な場合（例：cancel()、curate: true、複数行のラベル）は、代わりに角丸ノードと引用符で囲んだエッジラベル（|"label text"|）を使う flowchart LR を使用します。フローチャートではすべての特殊文字を扱え、改行には <br/> も使用できます。stateDiagram-v2 は、簡単な単語1つ、またはプレーンテキストのラベルに限定してください。

マインドマップ／階層的な内訳

Mermaid を使用します。 ルートノードから階層的に分岐させるには、mindmap 構文を使用します。Mermaid が放射状のレイアウトを自動的に処理します。themeVariables を使って、階層の深さごとのノード色を設定します。

データテーブル／比較／監査

テーブルには本物の<table>要素を使用してください。テーブルのように見せかけたCSS Gridは使わないでください。テーブルを使えば、アクセシビリティ、コピー＆ペーストの動作、列の配置がそのまま得られます。./templates/data-table.htmlのリファレンステンプレートでは、以下のパターンをすべて紹介しています。

積極的に使用してください。 ターミナルに罫線文字でASCII表を出力する場合は、代わりにHTMLテーブルを生成してください。対象には、要件監査（リクエストと計画の比較）、機能比較、ステータスレポート、構成マトリックス、テスト結果の概要、依存関係リスト、権限テーブル、APIエンドポイント一覧など、構造化された行と列を持つあらゆる情報が含まれます。

レイアウトパターン：

• 長いテーブルをスクロールするときもヘッダーが見えるよう、<thead>を固定する
• tr:nth-child(even)を使って行の背景色を交互にする（明度差は控えめに2～3％）
• 横幅の広いテーブルでは、必要に応じて先頭列を固定する
• ビューポートより幅の広いテーブルには、overflow-x: autoを指定したレスポンシブラッパーを使用する
• <colgroup>またはthの幅指定で列幅の目安を設定し、テキスト量の多い列に十分な幅を確保する
• スキャンしやすいよう、行にホバー時のハイライトを付ける

ステータスインジケーター（絵文字は使わず、スタイルを設定した<span>要素を使用）：

• 一致／合格／はい：緑色の背景に色付きの点またはチェックマーク
• 差分／不合格／いいえ：赤色の背景に色付きの点または×印
• 一部対応／警告：アンバー色のインジケーター
• 中立／情報：薄い色のテキストまたは控えめなバッジ

セルの内容：

• 長いテキストは自然に折り返し、省略したり一行に固定したりしない
• セル内の技術的な参照には<code>を使用する
• 補足情報には、色を薄くした<small>を使用する
• 数値列は右揃えにし、tabular-numsを指定する

タイムライン／ロードマップ表示

中央線をCSS疑似要素で作成した、縦向きまたは横向きのタイムライン。フェーズのマーカーは線上に円で配置します。コンテンツカードは左右交互に分岐させるか、すべて片側に配置します。日付ラベルは線上に配置します。過去は落ち着いた色、未来は鮮やかな色にして、色の変化で進行を表現します。

ダッシュボード／メトリクス概要

カードグリッドのレイアウトを使用します。主要な数値は大きく、目立つようにします。スパークラインはインラインSVGの<polyline>で作成します。プログレスバーは、divにCSSのlinear-gradientを指定して作成します。実際のチャート（棒、折れ線、円）には、CDN経由のChart.jsを使用してください（./references/libraries.mdを参照）。KPIカードには、トレンドインジケーター（上向き／下向きの矢印、パーセンテージの増減値）を付けます。

ファイル構成

すべての図は、自己完結した単一の.htmlファイルにしてください。外部アセットはCDNリンク（フォント、任意のライブラリ）以外使用しないでください。構成：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Descriptive Title</title>
  <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
  <style>
    /* CSS custom properties, theme, layout, components — all inline */
  </style>
</head>
<body>
  
  
  
</body>
</html>

品質チェック

納品前に、以下を確認してください。

• 目を細めて見るテスト：目を細めても階層構造を認識できますか？各セクションは視覚的に区別できますか？
• 置き換えテスト：フォントと色を汎用的なダークテーマに置き換えても、テンプレートと見分けがつかなくなりませんか？見分けがつかない場合は、デザインをさらに工夫してください。
• 両方のテーマ：OSのテーマをライトモードとダークモードに切り替えてください。どちらも意図した見た目になり、表示が崩れないようにします。
• 情報の完全性：図はユーザーの依頼内容を実際に伝えていますか？見た目が美しくても情報が不完全なら失敗です。
• はみ出しがないこと：ブラウザーの幅を変えて確認してください。コンテンツが切れたり、コンテナーからはみ出したりしてはいけません。すべてのグリッドとFlexの子要素にmin-width: 0を指定してください。横並びのパネルにはoverflow-wrap: break-wordを指定してください。マーカー文字のために<li>にdisplay: flexを指定しないでください。縮小できない匿名のFlexアイテムが作られ、多数のインライン<code>バッジを含む行がはみ出す原因になります。代わりに、マーカーには絶対配置を使用してください。./references/css-patterns.mdの「Overflow Protection」セクションを参照してください。
• Mermaidのズームコントロール：すべての.mermaid-wrapコンテナーに、ズームコントロール（＋／−／リセットボタン）、Ctrl／Cmd＋スクロールによるズーム、クリック＆ドラッグによるパンを実装してください。複雑な図は、コントロールがないと小さく表示されすぎます。ズームイン時はカーソルをgrabに、ドラッグ中はgrabbingに変更してください。実装全体のパターンについては、./references/css-patterns.mdを参照してください。
• ファイルが問題なく開くこと：コンソールエラー、フォント読み込みの失敗、レイアウトのずれがないようにしてください。