visual-explainer

ビジュアル解説

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

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

利用可能なコマンド

詳細なプロンプトテンプレートは ./commands/ にあります。Claude Code では名前空間付きのコマンドです（/visual-explainer:diff-review）。Pi ではスラッシュコマンドです（/diff-review）。Codex では /prompts:diff-review（~/.codex/prompts/ にインストールされている場合）を使用するか、$visual-explainer を呼び出してワークフローを説明してください。

コマンド	内容
generate-web-diagram	任意のトピックの HTML 図を生成します
generate-visual-plan	機能のビジュアル実装計画を生成します
generate-slides	雑誌品質のスライドデッキを生成します
diff-review	アーキテクチャ比較とコードレビューを含む、ビジュアル差分レビューです
plan-review	リスク評価を行い、計画をコードベースと比較します
project-recap	プロジェクトに戻る際のコンテキスト切り替え用メンタルモデルスナップショットです
fact-check	ドキュメントの正確性を実際のコードと照らし合わせて検証します
share-page	HTML ページを Vercel にデプロイし、公開 URL を取得します

ワークフロー

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

HTML を書く前に、方向性を決めてください。毎回「青をアクセントにしたダークテーマ」を選ぶのはやめましょう。

ビジュアル表現を常に基本とします。 エッセイ、ブログ記事、記事であっても、視覚的にデザインし、構造をカード、図、グリッド、表に落とし込みます。

文章のパターン（導入段落、引用文、コールアウトボックス）は、ビジュアルページの中で使うアクセント要素であり、独立したモードではありません。重要なポイントを強調したり、余白を設けたりするために使いますが、ページの構成はビジュアル表現を基本とします。

文章のアクセントについては、./references/css-patterns.md の「文章ページの要素」を参照してください。それ以外は、以下のデザインの方向性に沿った標準的な自由形式のアプローチを使います。

誰が見るのでしょうか？ システムを理解しようとしている開発者でしょうか？ 調査を振り返る記者でしょうか？ 記事を確認する編集者でしょうか？ 全体像を把握する PM でしょうか？ 手法を監査する研究者でしょうか？ こうした点が、情報密度や視覚的な複雑さを左右します。

コンテンツの種類は何でしょうか？ アーキテクチャ、フローチャート、シーケンス、データフロー、スキーマ／ER 図、状態遷移図、マインドマップ、クラス図、C4 アーキテクチャ、データテーブル、タイムライン、ダッシュボード、ソースネットワーク、調査マップ、編集ワークフロー、ストーリー構成、または文章を中心としたページでしょうか。それぞれに適したレイアウトと描画方法があります（下記の図の種類を参照）。

デザインの方向性は何でしょうか？ ひとつ選び、一貫して適用してください。制約のあるデザイン（Blueprint、Editorial、Paper/ink）は、一般的な仕上がりを避けるための具体的な要件があるので、より安全です。柔軟なデザイン（IDE に着想を得たもの）は、より慎重に取り組む必要があります。

制約のあるデザイン（こちらを優先）：

• Blueprint（テクニカルドローイングの雰囲気、控えめなグリッド背景、濃いスレート／ブルーの配色、等幅フォントのラベル、精密な境界線）
• 新聞のエディトリアル（Playfair Display や Crimson Pro のようなセリフ体の見出し、ゆとりのある余白、落ち着いたアースカラー、または濃紺とゴールド）
• 紙とインク（温かみのあるクリーム色の背景 #faf7f5、テラコッタ／セージのアクセント、気取らない雰囲気。ニュースルームの特集に適しています）
• 雑誌の特集（大きなディスプレイ用セリフ体、軸をずらした構成、印象的な引用文、写真を中心としたデザイン）
• 学術論文／研究論文（Libre Baskerville または Source Serif、抑制された配色、脚注風の細部、ゆとりのある余白）
• ニュースルームのボード（コルク／画びょうの質感、手書き風のメモ、カードを貼り付けたレイアウト。編集計画やストーリーマップ向け）
• 調査ボード（赤い糸の美学、つながるエンティティ、方眼紙の背景、赤をアクセントにしたモノクロ。関係性マップ向け）
• モノクロのターミナル（ほぼ黒の背景に緑／琥珀色、すべて等幅フォント、必要に応じて CRT の光彩）

柔軟なデザイン（慎重に使用）：

• IDE に着想を得たデザイン（Dracula、Nord、Catppuccin Mocha/Latte、Solarized Dark/Light、Gruvbox、One Dark、Rosé Pine など、実在する名前付き配色を採用し、実際のパレットを忠実に使います。近似させるだけではいけません）
• データ密度の高いデザイン／通信社風（小さな文字、詰めた間隔、最大限の情報、落ち着いた色）
• 手描き風のスケッチ（Mermaid look: 'handDrawn'、気軽な注釈、ホワイトボードや初期段階の検討向け）

明確に禁止されているもの：

• ネオンのダッシュボード（暗い背景にシアン＋マゼンタ＋パープル。AI っぽい粗雑な仕上がりになりがちです）
• グラデーションメッシュ（ピンク／パープル／シアンのぼかし。ありがちなデザインです）
• Inter フォント＋バイオレット／インディゴのアクセント＋グラデーションテキストの組み合わせ

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

2. 構成

生成する前に参考資料を読んでください。 パターンを暗記するのではなく、その都度読み、傾向を把握してください。

• テキスト中心のアーキテクチャ概要（トポロジーよりカードの内容が重要）の場合は、./templates/architecture.html を読んでください
• フローチャート、シーケンス図、ER 図、ステートマシン、マインドマップ、クラス図、C4 の場合は、./templates/mermaid-flowchart.html を読んでください
• データテーブル、比較、監査、機能マトリックス、出典検証グリッドの場合は、./templates/data-table.html を読んでください
• スライドデッキのプレゼンテーション（--slides フラグがある場合、または /generate-slides が呼び出された場合）は、./templates/slide-deck.html と ./references/slide-patterns.md を読んでください
• 文章中心の公開用ページ（README、記事、ブログ記事、エッセイ）の場合は、./references/css-patterns.md の「Prose Page Elements」と ./references/libraries.md の「Typography by Content Voice」を読んでください

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

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

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

コンテンツの種類	方法	理由
アーキテクチャ（テキスト中心）	CSS Grid カード＋フロー矢印	説明、コード、ツール一覧など、カードに豊富な内容を含めるには CSS の制御が必要です
アーキテクチャ（トポロジー重視）	Mermaid	コンポーネント間の接続を見せるには、自動エッジルーティングが必要です
フローチャート／パイプライン	Mermaid	ノードの配置とエッジルーティングを自動化できます
シーケンス図	Mermaid	ライフライン、メッセージ、アクティベーションボックスには自動レイアウトが必要です
データフロー	エッジラベル付き Mermaid	接続とデータの説明には、自動エッジルーティングが必要です
ER 図／スキーマ図	Mermaid	多数のエンティティ間の関係線を自動でルーティングできます
ステートマシン	Mermaid	ラベル付きエッジによる状態遷移には自動レイアウトが必要です
マインドマップ	Mermaid	階層的な分岐を自動配置できます
クラス図	Mermaid	継承、コンポジション、集約の線を自動でルーティングできます
C4 アーキテクチャ	Mermaid	C4 には graph TD と subgraph を使用してください（テーマが無視されるネイティブの C4Context は使用しないでください）
データテーブル／比較／監査	HTML <table>	セマンティックなマークアップ、アクセシビリティ、コピー＆ペースト時の挙動に優れています
タイムライン／時系列	CSS（中央線＋カード）	シンプルな線形レイアウトにはレイアウトエンジンは不要です
ダッシュボード／指標	CSS Grid＋Chart.js	埋め込みチャート付きのカードグリッドです
出典ネットワーク	Mermaid または CSS Grid カード	調査やストーリーにおける出典間の関係を示します
編集ワークフロー	Mermaid フローチャート	企画から公開・配信までのストーリーのライフサイクルを示します
調査マップ	CSS Grid カード＋Mermaid	調査作業におけるエンティティ、文書、出来事をつなぎます
ストーリー構成	CSS Grid	公開前に、物語の展開、セクション、情報源の配分を視覚化します

Mermaid のテーマ設定。 色をページの配色に合わせるため、常にカスタムの themeVariables とともに theme: 'base' を使用してください。複雑なグラフには layout: 'elk' を使用してください（ローカルにバンドルされた @mermaid-js/layout-elk パッケージが必要です。./references/libraries.md を参照してください）。ピクセル単位で正確に制御できるよう、CSS で Mermaid の SVG クラスを上書きしてください。テーマ設定の詳細については、./references/libraries.md を参照してください。

Mermaid のコンテナー。 Mermaid 図は常に display: flex; justify-content: center; で中央に配置してください。すべての .mermaid-wrap コンテナーにズームコントロール（拡大／縮小／リセット／展開）を追加してください。図（または ⛶ ボタン）をクリックすると、新しいタブで全サイズ表示する JavaScript も含めてください。 <pre class="mermaid">をそのまま使わないでください。 描画はされますが、ズーム／パンの操作コントロールがなく、図が小さくなって使いものになりません。必ず、mermaid-flowchart.htmlのジャーナリズム向けパターンを使ってください。.zoom-controls（＋／−／リセット／拡大ボタン）を含む.mermaid-wrapコンテナーで.mermaid要素を囲みます。コンテナーのCSSがオーバーフローとパン操作のヒントを処理し、同梱のJSがズームボタン、Ctrl＋スクロールホイールによるズーム、クリック＆ドラッグによるパン、新しいタブで開くクリック操作を設定します。パターンを再構成せず、テンプレートをそのままコピーし、固定バージョンのMermaidインポートを解決できるよう、同階層のtemplates/vendor/ディレクトリもコピーしてください。

Mermaidの拡大縮小。 ノードが10個以上ある図は、デフォルトでは小さく表示されます。ノードが10～12個の場合は、themeVariablesのfontSizeを18～20pxに増やし、INITIAL_ZOOMを1.5～1.6に設定します。要素が15個以上の場合は、拡大縮小で対応せず、代わりにハイブリッドパターン（シンプルなMermaidの概要図＋CSS Gridカード）を使ってください。下記の「アーキテクチャ／システム図」を参照してください。

Mermaidのレイアウト方向。 複雑な図では、flowchart LR（左から右）よりもflowchart TD（上から下）を優先してください。LRは横方向に広がるため、ノードが多いとラベルが読めなくなります。LRは、ノードが3～4個のシンプルな直線フローに限って使ってください。./references/libraries.mdの「レイアウト方向：TDとLRの比較」を参照してください。

フローチャートのラベル内でのMermaidの改行。 引用符で囲んだラベル内では<br/>を使ってください。\nのようなエスケープされた改行は使わないでください（MermaidはHTML出力でこれをリテラルテキストとして表示します）。例：A["Pitch desk<br/>weekly intake"]。

MermaidのCSSクラスとの衝突に関する制約。 ページレベルのCSSクラスとして.nodeを定義しないでください。Mermaid.jsは位置指定に使うtransform: translate(x, y)を指定したSVGの<g>要素に、内部的に.nodeを使用しています。ページレベルの.nodeスタイル（ホバー時のtransform、box-shadow）は図に漏れ出し、レイアウトを崩します。カードコンポーネントには、代わりに名前空間付きの.ve-cardクラスを使ってください。Mermaidの.nodeを安全にスタイル設定する唯一の方法は、.mermaidの内側にスコープを限定することです（例：.mermaid .node rect）。

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. スタイル

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

タイポグラフィが図そのものです。 ./references/libraries.mdの一覧から、特徴的なフォントの組み合わせを選んでください。各ページでは、最近の生成で使われたものとは異なる組み合わせを使用してください。ジャーナリズム向けのフォントの組み合わせ（編集新聞向けのPlayfair Display＋Source Serif Pro、学術向けのLibre Baskerville＋Fira Code、ニュースルーム向けのBitter＋Inconsolata）は、上流のテクニカル向けの組み合わせと並んで掲載されています。 --font-body として使用禁止： Inter、Roboto、Arial、Helvetica、単独の system-ui。これらは AI 生成の低品質なデザインの兆候です。

おすすめの基本的な組み合わせ（以下を使用してください）：

• DM Sans + Fira Code（技術的で正確）
• Instrument Serif + JetBrains Mono（編集的で洗練）
• IBM Plex Sans + IBM Plex Mono（信頼感があり、読みやすい）
• Bricolage Grotesque + Fragment Mono（大胆で個性的）
• Plus Jakarta Sans + Azeret Mono（丸みがあり、親しみやすい）

おすすめのジャーナリズム向けの組み合わせ（編集・学術・報道の文脈で使用してください）：

• Playfair Display + Source Serif Pro（伝統的な新聞）
• DM Serif Display + DM Sans（現代的な雑誌）
• Libre Baskerville + Fira Code（研究論文）
• Bitter + Inconsolata（報道現場の作業文書）
• Instrument Serif + JetBrains Mono（通信社／データ）

<head> 内の <link> で読み込んでください。オフラインでの堅牢性を確保するため、font-family のフォールバックにはシステムフォントを含めてください。

色はストーリーを伝えます。 パレット全体には CSS カスタムプロパティを使用してください。最低限、--bg、--surface、--border、--text、--text-dim と、3～5色のアクセントを定義してください。各アクセントには、背景用の通常版と淡色版を用意してください。可能であれば、変数名には意味を持たせてください（--blue-3 ではなく --pipeline-step）。両方のテーマに対応してください。

使用禁止のアクセントカラー： #8b5cf6 #7c3aed #a78bfa（インディゴ／バイオレット）、#d946ef（フューシャ）、シアン・マゼンタ・ピンクの組み合わせ。これらは Tailwind のデフォルトであり、デザインの意図がまったく感じられない印象を与えます。

おすすめのアクセントパレット（以下を使用してください）：

• テラコッタ + セージ（#c2410c、#65a30d）、温かみがあり、自然な印象（報道、紙とインク）
• ティール + スレート（#0891b2、#0369a1）、技術的で正確（アーキテクチャ、設計図）
• ローズ + クランベリー（#be123c、#881337）、編集的で洗練（検証監査）
• アンバー + エメラルド（#d97706、#059669）、データ重視（ダッシュボード）
• ディープブルー + ゴールド（#1e3a5f、#d4a73a）、高級感があり、洗練（学術、経営層）

基本のスタイルは :root に、もう一方のテーマはメディアクエリ内に記述してください。

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

/* Dark-first (terminal, IDE-inspired): */
: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 にあります。

サーフェスの奥行きで階層を作ってください。 カードの奥行きを変えて、重要度を示してください。ヒーローセクションには、浮き上がった影とアクセントカラーをほのかに反映した背景を適用します（ve-card--hero パターン）。本文コンテンツはフラットなままにします（デフォルトの .ve-card）。コードブロックや補助コンテンツは、奥まって見えるようにします（ve-card--recessed）。奥行きの段階については ./references/css-patterns.md を参照してください。すべてを浮き上がらせないでください。すべてが目立てば、何も目立たなくなります。

アニメーションには役割を持たせてください。 ページ読み込み時に段階的にフェードインさせる方法は、ほとんどの場合に効果的です。図の階層に沿って視線を誘導できます。役割に応じてアニメーションの種類を使い分けてください。カードには fadeUp、KPI とバッジには fadeScale、SVG コネクターには drawIn、ヒーローの数値には countUp を使用します。インタラクティブに見える要素にホバー時のトランジションを加えると、図に生き生きとした印象が生まれます。prefers-reduced-motion を必ず尊重してください。ほとんどの場合、CSS のトランジションとキーフレームで対応できます。複数要素を順序立てて動かす場合は、./references/libraries.md にあるローカルにベンダー化された anime.js アセットを使用してください。 禁止されているアニメーション：

• アニメーションする発光ボックスシャドウ（@keyframes glow { box-shadow: 0 0 20px... }）。これはAIが生み出す粗悪なコンテンツです
• 静的コンテンツに対する点滅・呼吸のようなエフェクト
• ページ読み込み後も実行され続けるアニメーション（進行状況インジケーターを除く）

アニメーションは目的を持たせてください。表示時の演出、ホバー時のフィードバック、ユーザーが開始する操作に使います。何も勝手に発光したり点滅したりしてはいけません。

アクセシビリティ。 生成するすべてのページは、最低限WCAG 2.1 AAに準拠する必要があります。具体的には、次のとおりです。

• 色のコントラスト比：テキストは4.5:1、大きなテキストとUIコンポーネントは3:1
• ステータスインジケーターには色とともに形状やテキストも使用します（色だけに頼るのは不可）
• テーブルには適切な<thead>、<th scope>、<caption>要素を使用します
• チャートにはデータテーブルによる代替手段を用意します
• キーボード操作時にフォーカスインジケーターが見えるようにします
• 言語を<html lang="en">で宣言します

4. 成果物

出力先。 ~/.agent/diagrams/に保存します。内容に基づいたわかりやすいファイル名を付けます：authentication-flow.html、source-network.html、budget-analysis.html、editorial-pipeline.html。このディレクトリはセッションをまたいで保持されます。

ブラウザーで開く：

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

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

図の種類

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

複雑さに応じて、次の3つの方法を使います。

シンプルなトポロジー（要素数10未満）： Mermaidを使います。カスタムのthemeVariablesを指定したgraph TDを使うと、自動的なエッジ配置により、読みやすい図を作成できます。

テキスト量の多い概要（要素数15未満）： 明示的に行と列を配置したCSS Gridを使います。セクションは、色付きの境界線と等幅フォントのラベルを持つ角丸カードとして配置します。セクション間には垂直方向のフロー矢印を付けます。./templates/architecture.htmlの参照テンプレートでは、ニュースルームCMSを例にこのパターンを示しています。カードに説明、コード参照、ツール一覧、またはMermaidのノードに含められないその他の豊富なコンテンツが必要な場合に使います。

複雑なアーキテクチャ（要素数15以上）： ハイブリッドパターンを使います。まずモジュール間の関係を示すシンプルなMermaidの概要図（ノード数5～8個）を置き、続いて各モジュールの内部を詳しく示すCSS Gridカードを配置します。これにより、視覚的なトポロジーと読みやすい詳細の両方を実現できます。概要図ではモジュール名に<small>タグを付け、主要な関数名を示します。下のカードには、追加・変更を示すバッジとともに関数の一覧をすべて表示します。要素数15以上を1つのMermaid図に詰め込まないでください。ズーム操作を付けても、表示が小さくなりすぎて読めなくなります。

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

Mermaidを使います。 ノードの自動配置とエッジの自動ルーティングにより、接続線、ひし形の判断ノード、並列分岐を備えた適切な図を作成できます。矢印文字を使ったCSS flexboxよりも大幅に優れています。graph TD（上から下）を優先し、graph LR（左から右）は単純な3～4ノードの直線的なフローに限って使います。ノードの種類ごとに色を分けるには、MermaidのclassDefを使うか、自動スタイル設定にはthemeVariablesを使います。編集ワークフロー（企画提案 → 担当割り当て → 下書き → 編集 → 公開）、FOIAリクエストの処理、検証ワークフロー、記事の振り分けパイプラインなどに適しています。

シーケンス図

Mermaidを使います。 ライフライン、メッセージ、アクティベーションボックス、注記、ループには、すべて自動レイアウトが必要です。MermaidのsequenceDiagram構文を使います。.actor、.messageText、.activationクラスに対するCSSオーバーライドで、アクターやメッセージにスタイルを適用します。記者、編集者、情報源、システム間のやり取りを示すのに適しています。

データフロー図

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

スキーマ／ER図

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

ステートマシン／決定木

Mermaid を使います。 ラベル付きの遷移を持つ状態には stateDiagram-v2 を使います。ネストされた状態、フォーク、ジョイン、注釈をサポートします。決定木には、ひし形の決定ノードを使った graph TD を利用できます。

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

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

Mermaid を使います。 ルートノードから階層的に分岐する構造には mindmap 構文を使います。Mermaid が放射状のレイアウトを自動的に処理します。themeVariables でスタイルを設定し、階層ごとのノードの色を制御します。

クラス図

Mermaid を使います。 ドメインモデリング、OOP 設計、エンティティ関係には classDiagram 構文を使います。関連（-->）、コンポジション（*--）、集約（o--）、継承（<|--）の各関係をサポートします。多重度ラベル（例："1" --> "*"）と抽象クラス／インターフェースのマーカー（<<interface>>、<<abstract>>）を追加できます。OOP の意味付け（メソッドや継承）を持たない単純なエンティティボックスには、代わりに erDiagram を使ってください。純粋なデータモデリングでは、こちらのほうがすっきり表示されます。

C4 アーキテクチャ図

ネイティブ C4 ではなく、Mermaid のフローチャート構文を使います。 C4 の境界には subgraph ブロックを使った graph TD を利用します。ネイティブの C4Context は、角のある図形、独自のフォント、青いアイコン、themeVariables を無視するインライン SVG の色を固定で使用するため、カスタムパレットと常に調和しません。

フローチャートを C4 として使うパターン： 人物 → 角丸ノード (("Name"))、システム → 長方形 ["Name"]、データベース → 円柱 [("Name")]、境界 → subgraph ブロック、関係 → ラベル付き矢印 -->|"protocol"| を使います。classDef と :::className を使って、外部システムなどを視覚的に区別します（例：破線の境界線）。他の Mermaid 図と同様に、themeVariables、fontFamily、CSS オーバーライドが適用されます。

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

CSS Grid でテーブルのように見せるのではなく、実際の <table> 要素を使います。テーブルを使えば、アクセシビリティ、コピー＆ペースト時の動作、列の整列をすぐに利用できます。./templates/data-table.html にある参照テンプレートでは、ソース検証監査を例に、以下のパターンをすべて紹介しています。

積極的に使いましょう。 ターミナルで ASCII 罫線のテーブルを表示する場面では、HTML テーブルを生成してください。これには、要件監査（依頼と計画の比較）、機能比較、ステータスレポート、設定マトリックス、テスト結果の要約、依存関係一覧、権限テーブル、API エンドポイント一覧、ソース検証グリッド、FOIA 依頼ログ、文書一覧、主張ごとの監査など、構造化された行と列を持つものすべてが含まれます。

レイアウトパターン：

• 長いテーブルをスクロールする際にもヘッダーを表示できるよう、<thead> を固定する
• tr:nth-child(even) で背景色を交互に変える（明度差は控えめに、2～3％）
• 横幅の広いテーブルでは、必要に応じて最初の列を固定する
• ビューポートより幅の広いテーブルには、overflow-x: auto を指定したレスポンシブなラッパーを使う
• <colgroup> または th の幅指定で列幅の目安を示し、テキストの多い列には余裕を持たせる
• 行を見やすくするため、ホバー時にハイライトする

ステータス表示（絵文字は使わず、スタイル付きの <span> 要素を使います）：

• 一致／合格／はい／検証済み：緑の背景に色付きのドットまたはチェックマーク
• 不備／不合格／いいえ／未検証：赤の背景に色付きのドットまたはバツ印
• 部分的／警告：アンバー色のインジケーター
• 中立／情報：薄い色のテキストまたは控えめなバッジ

セルの内容：

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

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

中央に線を配置する垂直または水平のタイムライン（CSS の疑似要素を使用）。フェーズのマーカーを線上の円で表します。コンテンツカードは左右交互、または片側にまとめて配置します。日付ラベルは線上に配置します。過去（落ち着いた色）から未来（鮮やかな色）へと色を変化させます。調査のタイムライン、出来事の年表、プロジェクトの沿革に適しています。

ダッシュボード／指標の概要

カードグリッドレイアウトを使用します。主要な数値は大きく目立たせます。インライン SVG の <polyline> でスパークラインを描画します。div に CSS の linear-gradient を指定して進捗バーを作成します。実際のグラフ（棒、折れ線、円）には、./references/libraries.md の ローカルにベンダー化された Chart.js アセットを使用します。KPI カードにはトレンド指標（上昇／下降の矢印、変化率）を含めます。ニュースルームの分析、助成金の報告ダッシュボード、オーディエンス指標に適しています。

情報源のネットワーク

調査や記事における情報源間の関係をマッピングします。つながりの多いマップには Mermaid、詳細な情報源プロフィールには CSS Grid のカードを使用できます。以下を含めます：情報源の名前、役割、信頼性の指標、提供した情報、他の情報源への相互参照。情報源のカテゴリ（公式記録、実名の人物、匿名の人物、文書、専門家）ごとに色を分けます。

調査マップ

エンティティ（人物、組織、文書、出来事）を視覚的な線で結びます。エンティティのプロフィールには CSS Grid のカード、関係図には Mermaid を使用します。エンティティの種類ごとに色を分けます。つながりの強さを示します。調査報道、資金の流れの追跡、権力構造のマッピングに適しています。「調査の壁」をイメージしたスタイル（赤い糸、赤をアクセントにしたモノクロ）は、この用途によく合います。

編集ワークフロー

Mermaid フローチャートで、企画 → 担当割り当て → 調査 → 下書き → 編集 → 法務確認 → 校正 → レイアウト → 公開 → 配信という記事のライフサイクルを示します。各段階を色分けします。判断のゲート（中止／修正／承認）を示します。遷移には役割ラベルを含めます。./templates/mermaid-flowchart.html のリファレンステンプレートで、このパターンを確認できます。

記事の構成

CSS Grid で物語の展開を視覚化します。セクション、単語数、情報源の分布、マルチメディアの配置を示します。長編記事の計画や、公開前の記事構成の確認に適しています。

実装計画

実装計画、拡張機能の設計、機能仕様を視覚化します。目的は、ソースコード全体を読むことではなく、アプローチを理解することです。

ファイル全体をそのまま載せないでください。 ソースファイル全体をインラインで表示すると、ページが情報過多になり、視覚的な説明という目的に反します。代わりに、以下のようにします。

• ファイル構成と説明を示し、関数／エクスポートを1行で説明します
• 重要なスニペットのみ、中核となるロジックがわかる5～10行を示します
• 本当に必要な場合は、折りたたみ可能なセクションにコード全体を入れます

コードブロックには明示的な書式設定が必要です。 white-space: pre-wrap がないと、コードがつながって読みにくい塊になります。正しいパターンについては、./references/css-patterns.md の「コードブロック」セクションを参照してください。

実装計画の構成：

1. 概要／目的（どのような問題を解決するのか？）
2. フロー図（Mermaid または CSS カード）
3. 説明付きのファイル構成（コード全体ではなく）
4. 主要な実装の詳細（スニペット）
5. API／インターフェースの概要
6. 使用例

ドキュメント（README、ライブラリのドキュメント、API リファレンス）

ドキュメントを視覚化する場合は、構成を視覚的な要素にまとめます。

内容	視覚的な表現
機能	カードグリッド（2～3列）
インストール／セットアップ手順	番号付きカードまたは垂直フロー
API エンドポイント／コマンド	固定ヘッダー付きテーブル
設定オプション	テーブル
アーキテクチャ	Mermaid 図または CSS カードレイアウト
比較	横並びのパネルまたはテーブル
警告／注記	コールアウトボックス

文章を整形するだけでなく、視覚的な表現に変換してください。機能一覧はカードグリッドに、インストール手順は番号付きフローに、API リファレンスはテーブルにします。

文章のアクセント要素

ビジュアルページでは、重要なポイントを強調したり、余白を設けたりするために、これらを控えめに使用します。CSS のパターンについては、./references/css-patterns.md の「文章ページの要素」を参照してください。

• リード段落：カードやグリッドに入る前に背景を説明する、大きめの導入テキスト
• 引用文：重要な洞察を強調します。1 ページにつき最大 1 つまでです
• コールアウトボックス：警告、ヒント、重要な注意事項
• セクション区切り：主要なセクション間に視覚的な区切りを設けます

使用する場面： エッセイを説明するビジュアルページでは、主張をリード段落で示し、その後、主要な論点をカードにまとめる方法があります。README のビジュアル化では、警告にコールアウトボックスを使い、それ以外はカードや表を中心に構成できます。

スライドデッキモード

スクロール可能なページではなく、雑誌品質のスライドプレゼンテーションとしてコンテンツを提示するための代替出力形式です。オプトインのみです。ユーザーが /generate-slides を実行するか、既存のプロンプトに --slides を指定する（例：/diff-review --slides）か、スライドデッキを明示的に依頼した場合にのみ、スライドを生成します。スライド形式を自動で選択してはいけません。

スライドを生成する前に、./references/slide-patterns.md（エンジン CSS、スライドの種類、トランジション、ナビゲーション要素、プリセット）と ./templates/slide-deck.html（10 種類すべてを示すリファレンステンプレート）を読みます。また、共通パターンについては ./references/css-patterns.md を、Mermaid／Chart.js のテーマ設定については ./references/libraries.md を読みます。

スライドは、ページを再フォーマットしたものではありません。 別のメディアです。各スライドはビューポートの高さ（100dvh）にぴったり収め、スクロールは発生させません。タイポグラフィは 2～3 倍大きくします。構成は大胆にします。エージェントは、ソースを機械的にページ分割するのではなく、インパクト → 背景 → 詳細な分析 → 解決という物語の流れを組み立てます。

コンテンツの完全性。 メディアを変えても、コンテンツを省略してよいわけではありません。HTML を書く前に、slide-patterns.md の「Planning a Deck from a Source Document」の手順に従います。ソースの項目を洗い出し、すべての項目をスライドに割り当て、漏れがないことを確認します。ソース内のすべてのセクション、決定事項、データポイント、仕様、折りたたみ可能な詳細をデッキに含める必要があります。計画に 7 つのセクションがある場合、デッキにはその 7 つすべてを含めます。決定事項が 6 つある場合は、1 枚のスライドに収まる 2 つだけでなく、6 つすべてを提示します。ソース内の折りたたみ可能な詳細は、それぞれ独立したスライドにします。コンテンツを削るのではなく、スライドを追加します。すべてを網羅する 22 枚のデッキは、見栄えはよくてもソースの 40％が欠けている 13 枚のデッキより優れています。

スライドの種類（10 種類）： タイトル、セクション区切り、コンテンツ、分割、図解、ダッシュボード、表、コード、引用、全面表示。各種類のレイアウトは slide-patterns.md で定義されています。スライドの密度上限を超えるコンテンツは、スライド内でスクロールさせず、複数のスライドに分割します。

視覚的な豊かさ： 最初に which surf を確認します。surf-cli が利用可能な場合は、HTML を書く前に 2～4 枚の画像（タイトルスライドの背景、全面表示の背景、必要に応じてコンテンツのイラスト）を生成します。ワークフローについては、slide-patterns.md の Proactive Imagery セクションを参照してください。SVG の装飾要素、スライドごとの背景グラデーション、インラインのスパークライン、小さな Mermaid 図も使用します。テキストより視覚表現を優先します。

構成の多様性： 連続するスライドでは、中央寄せ、左寄せ、右寄せ、分割、端揃え、全面表示など、空間的なアプローチを変えます。中央寄せのスライドが 3 枚続く場合は、1 枚を軸からずらします。

厳選されたプリセット： 出発点として、スライド専用の 4 つのプリセット（Midnight Editorial、Warm Signal、Terminal Mono、Swiss Clean）に加え、スライド向けに調整された既存の美的方向性があります。1 つ選び、徹底して適用します。プリセットの CSS 値については slide-patterns.md を参照してください。

既存のプロンプトに対する --slides フラグ： ユーザーが /diff-review、/plan-review、/project-recap などに --slides を指定した場合、エージェントはプロンプトの通常のデータ収集指示に従って情報を集めたうえで、スクロール可能なページではなくスライドデッキとしてコンテンツを提示します。スライド版では構成やペース配分を変えて同じストーリーを伝えますが、網羅する範囲は同じです。スクロール可能な版に含まれるはずのセクションを要約したり省略したりする口実として、スライド形式を使ってはいけません。

ファイル構成

すべての図は、デプロイ可能な .html ファイルと、必要に応じてロックファイルで検証されたライブラリを含むローカルの vendor/ ディレクトリで構成されます。Mermaid のリファレンステンプレートには、必要なコアバンドルが templates/vendor/ に含まれています。テンプレートをコピーする際は、同階層のこのディレクトリを保持してください。実行時 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>

ページの共有

Pi 対応の vercel-deploy スキルが利用できる場合、Vercel を使ってビジュアル解説ページをすぐに共有できます。アカウントも認証も不要です。

インストール済みのスキルパスを使う場合：

bash ~/.pi/agent/skills/visual-explainer/scripts/share.sh <html-file>

スキルが別の場所にある場合は、~/.codex/skills/visual-explainer/scripts/share.sh、~/.config/opencode/skill/visual-explainer/scripts/share.sh、またはリポジトリのチェックアウトからの ./plugins/visual-explainer/scripts/share.sh など、該当するインストール先のパスを使用してください。

動作の仕組み：

1. インストール済みの visual-explainer スキルディレクトリから share.sh スクリプトを実行します
2. HTML ファイルを一時ディレクトリに index.html としてコピーします
3. Pi 対応の vercel-deploy スキルを使ってデプロイします
4. URL はすぐに有効になり、どのブラウザーでも利用できます

要件：

• 標準的な Pi 対応スキルの場所に vercel-deploy スキルがあること（Pi では pi install npm:vercel-deploy）

注意：

• デプロイは公開され、URL を知っている人なら誰でも閲覧できます
• プレビューデプロイの保持期間は設定可能です（デフォルト：30 日）
• Claim URL を使うと、デプロイを自分の Vercel アカウントに移管できます
• ほかのハーネスでは通常どおり HTML を生成して開けますが、/share-page には Pi 対応の vercel-deploy スクリプトが必要です

/share-page コマンドのテンプレートについては、./commands/share-page.md を参照してください。

品質チェック

納品前に、次の点を確認してください。

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

アンチパターン（AI らしい手抜き）

これらのパターンは明確に禁止されています。「AI が生成したテンプレート」と受け取られ、このスキルが目指す、個性と品質を備えた図の作成を損ないます。生成したページをすべてこのリストと照らし合わせて確認してください。

タイポグラフィ

本文用の --font-body に使ってはいけないフォント：

• Inter：AI のデフォルトとして最も多用されているフォント
• Roboto、Arial、Helvetica、および一般的なシステムフォントのフォールバックを、第一候補として扱うこと
• system-ui、sans-serif だけを使うこと。個性も意図もありません

必須： ./references/libraries.md にあるフォントの組み合わせから選んでください。生成するたびに、前回とは異なる組み合わせを使用してください。

カラーパレット

使用禁止のアクセントカラー：

• インディゴ-500／バイオレット-500（#8b5cf6、#7c3aed、#a78bfa）、Tailwind のデフォルトの紫系カラー
• シアン＋マゼンタ＋ピンクのネオン系グラデーションの組み合わせ（#06b6d4 → #d946ef → #f472b6）
• 「紫／ピンク／シアンのアクセントを使った Tailwind のデフォルト」と表現できるようなパレット

使用禁止のカラーエフェクト：

• 見出しのグラデーションテキスト（background: linear-gradient(...); background-clip: text;）。AI 生成らしさが強く出ます
• カードにアニメーション付きの発光するボックスシャドウ（box-shadow: 0 0 20px var(--glow); animation: glow 2s...）
• アクセントカラーの放射状の光を複数重ねて作る「ネオンのもや」

必須： 参照テンプレート（テラコッタ／セージ、ティール／シアン、ローズ／クランベリー、スレート／ブルー）を基にパレットを作るか、実際の IDE テーマ（Dracula、Nord、Solarized、Gruvbox、Catppuccin）から配色を導きます。アクセントカラーは意図を持って選び、デフォルトのような印象にしないでください。

セクション見出し

禁止事項：

• セクション見出しの絵文字アイコン（セクション UI に装飾目的の絵文字を一切使わない）
• すべてのセクション見出しに同じ、角丸ボックス内のアイコンというパターンを使うこと

必須： 色付きのドットインジケーターを添えたスタイル付きの等幅フォントラベル（テンプレートの .section-label を参照）、番号付きバッジ（section__num パターン）、または非対称のセクション区切りを使用します。本当にアイコンが必要な場合は、絵文字ではなく、パレットに合ったインライン SVG を使用してください。

レイアウトと階層

禁止事項：

• すべてを均等な余白で完璧に中央揃えすること
• すべてのカードを同じ角丸、シャドウ、間隔で統一すること
• すべてのセクションを同じ視覚的な強さにし、ヒーロー／主要セクションと副次セクションを区別しないこと
• 左右の半分が鏡写しになるような対称的なレイアウト

必須： 視覚的な強弱に変化をつけます。ヒーローセクションは、より大きな文字、広めの余白、アクセントカラーを薄く乗せた背景で目立たせます。参照セクションはコンパクトにまとめます。深度の段階（ヒーロー → 浮き上がり → 標準 → 奥まった表現）を使います。非対称なレイアウトで変化を生み出します。

テンプレートのパターン

禁止事項：

• コードブロックに、赤／黄／緑のドットを使ったウィンドウ枠を付けること。これはありきたりな表現です
• すべての指標に同じグラデーションテキストを使う KPI カード
• 美的表現として「ネオンダッシュボード」を選ぶこと。常にありきたりな結果になります
• 背景にピンク／紫／シアンのぼかしを使ったグラデーションメッシュ

必須： コードブロックには、ファイル名または言語ラベルを示すシンプルなヘッダーを使用します。KPI カードは重要度に応じて変化をつけ、主要指標には大きな数値を使い、補助的な指標は控えめに表現します。自然な制約のある美的表現を選びます。たとえば、Blueprint（技術的で正確な印象にする）、Editorial（十分な余白とセリフ体を使う）、Paper/ink（温かく気取らない印象にする）、Newsroom board（コルクボードに画びょうを留めたような印象にする）などです。

ありきたり度のチェック

納品前に、次の基準で確認してください。このページを見た開発者や編集者が、すぐに「AI が作ったのでは」と思うでしょうか？ その兆候は次のとおりです。

1. Inter または Roboto フォントに、紫／バイオレットのグラデーションアクセント
2. すべての見出しに background-clip: text のグラデーション
3. すべてのセクションの先頭に絵文字アイコン
4. アニメーション付きシャドウで発光するカード
5. 暗い背景にシアン／マゼンタ／ピンクの配色
6. 視覚的な階層がなく、完全に均一なカードグリッド
7. コードブロックに付けたドット 3 つの枠

これらが 2 つ以上当てはまる場合、そのページはありきたりです。Editorial、Blueprint、Paper/ink、Newsroom board、Academic、または特定の IDE テーマなど、別の美的方向性で作り直してください。こうした制約のある美的表現は、汎用的なパターンに流れるのを防ぐ具体的な視覚要件があるため、失敗しにくくなります。

関連スキル

• journalism-core/data-journalism、データ分析とストーリーテリング
• journalism-core/source-verification、SIFT メソッド、検証の追跡記録
• journalism-core/editorial-workflow、割り当ての追跡、締め切りの管理
• journalism-core/fact-check-workflow、主張の検証
• dev-toolkit/accessibility-compliance、WCAG 準拠、アクセシブルなチャート
• dev-toolkit/zero-build-frontend、依存関係のローカルでのベンダー化、React ランタイムバンドル、Leaflet マップ
• pdf-design、ブランドシステムを用いた印刷対応ドキュメント

---

nicobailon/visual-explainer（MIT）を基に、Anthropic's frontend-design skillのデザイン原則を取り入れて改変しました。ジャーナリズム、メディア、学術分野のワークフローに合わせて調整されています。