UltraExplainer（超解説）
コード、システム、差分、計画、データ、概念を、たった一つの重要なアイデアが一目でわかり、その裏付けとなる証拠が提示された、単一の自己完結型HTMLページに変換します。UltraExplainerは以下の3つの要素が連携して機能します。
- 合成手法（頭脳） — 何を見せ、何を強調し、何を削るか、ソースに存在しない構造を決して描かない方法を決定します。詳細は
references/synthesis-method.mdを参照。 - カメレオンスタジオ（技術） — 安定した、デザイン言語に依存しないコンポーネント契約（
assets/core.css）を、7つの完全なデザイン言語（assets/themes.css）でスキン変更します。同じ差分が、TerminalではIDEのガターのように、Blueprintでは罫線付きの吹き出しのように、Editorialでは図のようになります。主題に合わせて言語を選択します。グロー（輝き）は一つのオプション（Luminous）であり、決してデフォルトではありません。references/aesthetic-languages.mdおよびreferences/component-contract.mdを参照。 - インタラクティブ層（
assets/ux.js） — 単一の状態→レンダリングエンジンが、スライダー、シナリオ切り替え、ステップ実行、ソート/フィルタ可能なテーブル、スクロール追跡ナビゲーション、ルーティングされたノードエッジグラフを動かします。references/interactivity.mdを参照。
アイデンティティ：真実 + 適切なデザイン言語 + 検証された技術。「すべてが光る」でもなければ、「箱と矢印のスープ」でもなく、「同一カードの壁」でもありません。
このスキルを使用すべき時
出力が本質的に視覚的、関連的、または操作可能であり、ASCII/Markdownではうまく表現できない場合に、HTMLページを活用してください。
- 図、アーキテクチャ概要、ノードエッジグラフ（何がどのように接続または流れるか）。
- 差分 / PRレビュー（変更されたコード + その理由 + 影響範囲）。
- 計画 / 要件監査 または比較マトリックス。
- メトリクスのダッシュボード、または4行以上 / 3列以上のテーブル。
- 概念解説（メカニズムを教える）、またはインタラクティブモデル（読者が入力を変更することで体感できるもの）。
- スライドデッキ、またはコンテキストスイッチのためのプロジェクトの振り返り。
正直な答えが一文または単一の数値に収まる場合は、チャットでそのまま伝えてください。ページを作成しないでください（最小限の解説ルール）。構築する場合は、一行のチャットサマリーを提供し、ファイルを送信してください。
2つのモード — チャーターで決定する
どちらのモードであるかを明記してください（ユーザーが修正できるように）。
- EXPLAIN（説明）（デフォルト） — テーゼ（主張）を最初に提示。結論を素早く必要とするレビュアー、意思決定者、コンテキストスイッチャー向け。顕著性の上限あり（T0 ≤ 3、T1 ≤ 7）。
- TEACH（教示） — 質問を最初に提示。実行可能なメンタルモデルを必要とする学習者向け。具体から抽象へ、予測してから明らかにし、転移チェックで終了。
references/teaching.mdを参照。
手法の概要
重要なものを作成する前に references/synthesis-method.md を読んでください。簡略版は以下の通りです。
- チャーター — 一文：「これは*<成果物>を高度<A0–A4>で<読者>が<ジョブ>*できるように説明する」に加え、モード（EXPLAIN/TEACH）。一つの高度を維持します。
- 緊張を伴うテーゼ — 読者がまだ知らない、宣言的な主張（トピックではありません）。背骨（目が追跡する単一の軸）を選びます。
- 証拠台帳 — 実際のソースを読みます。すべてのノード/エッジ/ラベル/数値について
{主張, アンカー (ファイル:行 / シンボル / git参照 / メトリクス+日付), 信頼度 (verified確認済み|inferred推測|assumed仮定)}を記録します。アンカーがない → 事実としてレンダリングしません。 インタラクティブモデルの場合、すべてのスライダーの範囲/デフォルト値と入力→出力の関数はアンカーされるか、「説明用モデルであり、測定値ではありません」とスタンプされます。 - 調整 — テーゼを矛盾する証拠と突き合わせます。改訂、範囲調整、または表示します。決して黙って破棄しません。
- 最小限チェック — 過剰にレンダリングしません。単純な答え → ヒーロー文 + 一つのビジュアル。
- 顕著性の階層化 — T0（テーゼ+背骨、≤3）/ T1（構造を支える、≤7）/ T2（証拠類、
<details>/ホバー内）。上限を超える場合は分割または格下げ。決して縮小しません。（TEACHモードでは上限を望ましい難易度予算に置き換えます。） - デザイン言語の選択 — 7つの言語を主題×読者×媒体でスコアリングし、一行を記録します：
LANGUAGE: <名前> because <主題 + 読者 + 媒体>。以下を参照。 - 表現 — まず操作可能性の問いをします（「読者は入力変更によって関係性を体感すべきか？」）。「はい」の場合、モデル/ステッパー/シナリオを選択します。そうでなければ、最もインクの少ない静的形態を選びます。大きさは量的に（サイズ/長さ/位置）エンコードし、等しい箱では表現しません。
- 圧縮 — 省略は技術です。繰り返しを折りたたみます（「×12ハンドラ」）。負荷のかかる行だけを抜粋し、ファイル全体は抜粋しません。
- ゲート — 引き渡す前に以下の3つすべてを通過させます。
3つの引き渡しゲート — 真実がすべてに優先する
- TRUTH（真実） — すべてのノード/エッジ/数値が実際のアンカーにたどり着く。推測/仮定の内容は明示的に留保される。テーゼは矛盾する証拠と照合された。アンカーを再度開いた。「Xを確認できなかった」と明確にマークすることは、自信満々の捏造に勝る。インタラクティブな嘘（偽の関係性をなぞるスライダー）は最大の罪です。
- CRAFT（技術） — 目を細めてテスト：部屋の反対側から見て、意図的なデザイン言語であり、色を変えたテンプレートではないように見える。T0の焦点は正確に1つ。
- OBSERVED（観察） — 実際にページをレンダリングして見た。ビルドし、開き（
1280および360でヘッドレススクリーンショット）、コンソールエラーをキャプチャし、水平スクロールがないこと、テーゼが最初のビューポートにあることを確認し、自己修正する。「測定したことのないチェックリスト項目」を主張するのはやめましょう。
ページの構築方法（アセンブリ）
ページは scripts/build.mjs によって、templates/_src/<name>.body.html 内のボディフラグメントから組み立てられます。最も速い方法： 最も近いテンプレートをコピーし、preset を変更し、コンテンツを適応させます。
- 1行目ディレクティブ（HTMLコメント内のJSON）が言語とチューニングを選択します：
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset：blueprint | editorial | terminal | instrument | notebook | swiss | luminous（デフォルトはluminous）presets: ["…","…"]→ 言語ごとに1ファイルを出力（カメレオンデモ）theme：light | dark（デフォルトはプリセットの自然なチューニング）fx：glow | flat（Luminousのみ）head/foot：追加のマークアップ。<name>.head.html/<name>.foot.htmlのサイドカーファイルもマージされます。
- ビルドは
core.css+themes.css+ux.jsをインライン化し、プリセットのフォントにリンクし、ペイント前にdata-theme-preset/data-theme/data-fxを設定し（FOUCなし）、templates/<name>.htmlを出力します。 - 実行：
node scripts/build.mjs <name-filter>（フィルタは部分文字列。省略するとすべてをビルド）。 - ページの外部リクエストは、Google Fonts（システムフォールバックあり — レイアウトはこれに依存しない）と、Mermaidページの場合はMermaid CDNのみです。これらが失敗しても、正しく表示される必要があります。
重要 リテラル文字列
</script>を含むJSをインライン化する場合（例：コードスニペット）：</script>としてエスケープしてください。そうしないとタグが早期に閉じられ、ソースがページにダンプされます。
デザイン言語の選択
メリットに基づいてルーティングし、理由を記録します。完全なスコアカードと言語別プロフィールは references/aesthetic-languages.md にあります。
| 主題 | デフォルト言語 |
|---|---|
| アーキテクチャ、スキーマ、プロトコル、インフラトポロジ | Blueprint |
| 概念、ADR、ポストモーテム、エグゼクティブ向け説明 | Editorial |
| 差分、PR、CLIツール、CIパイプライン、ログ | Terminal |
| メトリクス、ベンチマーク、監査、ダッシュボード | Instrument |
| 教育、ウォークスルー、オンボーディング、優しい解説 | Notebook |
| 比較、原則/マニフェストページ、ステータスレポート | Swiss |
| システムフローデモ、プロダクトビジョン、ワウファクターブリーフ | Luminous（決してデフォルトではない） |
タイブレーカー：明示的なユーザー要求を尊重する（「ターミナルにして」）。セッションの単調さを避けるためにローテーションする。派手だからという理由だけでLuminousを選ばないこと。
表現の選択
コンテンツタイプではなく、認知的なジョブとデータの形状に基づいてルーティングします。操作可能性が最優先。完全なカタログとルーティングは references/representations.md に、正直なチャートは references/charts-honesty.md にあります。
| ジョブ | 表現（コンポーネント） |
|---|---|
| 1つの支配的なポイント / イエス・ノー | タイポグラフィックテーゼヒーロー（.ux-thesis）、場合により下に1つのビジュアル |
| 読者が関係性を体感すべき | パラメータモデル（[data-playground]） — スライダー + 連動した読み出し |
| 順序 / 中間状態が意味を持つ | ステップスルー（[data-stepper]） — コード↔データが連動 |
| 設定によって異なる動作 | シナリオトグル（.ux-seg[data-scenario-ctl]）が1つの図を再照明 |
| 真の線形シーケンス | 番号付きリスト / フローストリップ（.ux-spine） — フローチャートではありません |
| 分岐 / マージ / サイクルフロー | ノードエッジグラフ（.ux-graph、≤12ノード）またはテーマ付きMermaid |
| 密なペアワイズ関係 | マトリックスヒートマップ（.ux-matrix） — ヘアボールグラフよりも優れています |
| コード変更 / PR | 注釈付き差分 + 判定（.ux-diff + .ux-verdict）+ 影響範囲 |
| 概念 / 誤解 | ナイーブ対正解パネル（.ux-compare）+ 1つの動作例 |
| 比較 / 監査 / マトリックス | ソート可能、フィルタ可能なテーブル（.ux-table、th[data-sort]、data-ux-filter） |
| 定量的メトリクス | デルタ主導のKPI行（.ux-kpis）+ 最も薄い正直なチャート（.ux-bars/.ux-linechart） |
| 計画 / ロードマップ | 現在→目標ブロック + リスク階層化タイムライン（.ux-timeline） |
| プレゼンテーション | スライドデッキ（templates/slides） |
| 何も当てはまらない | テーマトークンを使用したカスタムインラインSVG |
テンプレート（templates/、ソースは templates/_src/）
| テンプレート | 言語 | デモ内容 |
|---|---|---|
chameleon.<preset>.html | 全7種 | 同一の説明をすべての言語でレンダリング — 目を細めてテスト |
blueprint → playground | Blueprint | パラメータ駆動モデル（スライダー、連動KPI/棒グラフ、プリセット） |
terminal-diff | Terminal | PRレビュー：注釈付き差分 + 判定 + 影響範囲 |
instrument-dashboard | Instrument | KPIマストヘッド + 正直な線/棒グラフ + ソート/フィルタテーブル |
editorial-concept | Editorial | 概念解説：スクロール追跡ナビ + カスタムSVG + ナイーブ対正解 + サイドノート |
notebook-teach | Notebook | TEACHモード：ステップスルー + 予測してから明らかに + 転移チェック |
swiss-comparison | Swiss | 意思決定マトリックス：特大数字 + ソート可能な比較テーブル |
luminous-flow | Luminous | シナリオトグル（ヒット/ミス）+ ルーティンググラフ + オプションのグロー |
mermaid | 任意 | ズーム/パン/展開可能なテーマ付きMermaid |
slides | 任意 | キーボード/スクロールナビゲーション付き全画面デッキ |
リファレンスルーティング — 現在の出力に必要なものだけを読む
| 必要なもの | 読むファイル |
|---|---|
| 何を/どのように表示するかを決める方法（頭脳） | references/synthesis-method.md |
| 7つの言語、選択スコアカード、目を細めてテスト | references/aesthetic-languages.md |
トークン階層、すべての.ux-コンポーネント、ビルド/アセンブリ | references/component-contract.md |
| 表現カタログ + データ形状×ジョブルーティング | references/representations.md |
| スライダー、シナリオトグル、ステッパー、グラフ、スクロール追跡 — JS API | references/interactivity.md |
| 正直なチャート：数値台帳、チャネルランキング、軸ルール | references/charts-honesty.md |
| TEACHモード：学習者状態、具体優先、予測-表示、転移 | references/teaching.md |
| ジョブ別プレイブック（PRレビュー、ポストモーテム、ADR、パフォーマンスプロファイル、…） | references/playbooks.md |
| 自己完結性、オーバーフロー安全性、検証ループ、配信チェックリスト | references/self-contained.md |
| テーマ付きMermaid（いつ + どのように） | references/mermaid.md |
| スライドデッキ | references/slides.md |
不変条件
- 真実は美と技術に優先します。 アンカーするか省略します。推測/仮定の内容は留保します。レイヤー、対称性、エッジ、または根拠を決して発明しません。インタラクティブな範囲/関数はアンカーされるか、「説明用モデル」とスタンプされます。
- ページごとに1つの言語をメリットに基づいて選択し、記録します。目を細めてテストをパスする必要があります。グローはLuminous専用であり、
--fx-*経由でルーティングされるため、data-fx="flat"でクリーンに削除できます。静的コンテンツに継続的な呼吸/パルス効果を適用しないでください。 - 水平方向のページスクロールはありません。 グリッド/フレックス子要素には
min-width:0。幅の広いコンテンツ（差分、テーブル、Mermaid）は自身のoverflow-x:autoコンテナ内でスクロールします。360pxで確認します。 - 両方のテーマが構成されているように見えること。 ライトテーマは再調整されており、反転ではありません。ページは選択されたテーマで開き、読者は切り替え可能です（プリセットごとに保存）。
prefers-reduced-motionを尊重します。キーボードフォーカスを可視に保ちます。印刷に耐えます。 - コンポーネントは意味トークンと
--fx-*トークンのみを使用し、HEXカラーは使用しません。 新しい外観はテーマパッケージからもたらされ、インラインカラーからはもたらされません。 - ページレベルの
.nodeクラスを定義しないでください。 Mermaidが内部的に使用します。すべてのUltraExplainerクラスは.ux-プレフィックスが付いています。 - 配信前に観察します。 ページをレンダリングし、見て、問題を修正します。測定していないことを主張しないでください。
最終チェックリスト
適切なパスにある自己完結型ドキュメント · 選択した preset でビルド · コンソールエラーなし · デスクトップおよび360pxで水平オーバーフローなし · フォントはグレースフルに劣化 · テーゼが最初のビューポートで正確に1つの焦点とともに明確である · テーブル/差分/図は自身のコンテナ内でスクロール · テーマ（およびLuminousグロー）の切り替えが機能 · すべての主張がアンカーまたは留保されている · ページが実際にレンダリングされ、検査された。