---
name: creating-visual-explainers
description: Generates an illustrated HTML page about any topic and deploys it to surge.sh with a comment widget (text/pin/voice feedback). Triggered by requests like "図解を作って", "図解を生成して", "このトピックを図解して", "図解してデプロイして", "この図解を再デプロイして", or "この図解を削除して".
---

# Creating Visual Explainers

任意のトピックについて、前提知識がなくても理解できる図解HTMLを生成し、コメント機能（テキスト引用・ピン・音声）付きで surge.sh に公開する。品質基準は「入社したての新卒社会人が読んでも腹落ちする明快さ」だが、この基準は出力には表示しない。

## 依存

- `references/base.html` — 図解テンプレート（Tailwind CSS CDN・Lucide Icons CDN・ADS配色を含む「額縁」）
- `references/model-answer.html` — 模範回答（品質基準・デザインパターンの実例）。base.htmlと同一の額縁を含む完全なHTMLファイル。widget 未含（デプロイ時に自動注入されるため）
- リポジトリルートの `fb-tool-url.txt` / `fb-api-token.txt` — セットアップスキル（`setting-up-comment-tool`）が生成する

## ワークフロー

### Step 0: 前提確認

1. `references/base.html` が存在するか確認する。存在しない場合、以下を伝えて終了:

> テンプレートファイルが見つかりません。スキルのフォルダ構成が壊れている可能性があります。運営に連絡してください。

2. リポジトリルート（`.claude` フォルダがある階層）に `fb-tool-url.txt` が存在するか確認する。存在しない場合、以下を伝えて終了:

> コメントツールのセットアップがまだ完了していません。
> 先にチャット欄で「セットアップして」と伝えてください。

### Step 1: 模範回答の読み込み

`references/model-answer.html` を読み、以下を把握する:

- 完成品の品質水準
- デザインパターン（色使い・余白・カード・フロー図などの視覚表現）
- Tailwind CSSクラスの使い方
- Lucide Iconsの使い方
- コンテンツの構成・情報量・説明の深さ

模範回答がデザインガイドラインの代わりになる。パーツ一覧やルールではなく、実物から読み取る。

### Step 2: テンプレートの読み込み

`references/base.html` を読み、額縁の構造を把握する:

- `<!-- CONTENT_START -->` 〜 `<!-- CONTENT_END -->` のプレースホルダー位置
- `<!-- TITLE -->`, `<!-- DESCRIPTION -->` のプレースホルダー
- ADS配色のTailwind設定
- 読み込み済みのCDN（Tailwind CSS・Lucide Icons）

### Step 3: ウェブで情報収集

トピックについてウェブ検索を行い、正確かつ最新の情報を収集する。

検索は **2〜3回** に絞る。以下の観点でクエリを組み立てる:

1. **正確な定義**: トピックの公式な定義、公式ドキュメントの説明
2. **最新動向**: 直近の変更点、アップデート、現在のベストプラクティス
3. **具体例**: 実際の使われ方、初心者に伝わるたとえに使える事例

検索結果から以下を整理し、Step 4 の参考情報とする:

- トピックの正確な定義（検索結果を優先。AIの学習データだけに頼らない）
- 最近変わった点があれば、それを明記する
- たとえ話に使えそうな事例や数字
- **出典URL**: 図解に採用した情報のソースURLを控えておく（Step 4 でインライン出典に使う）

### Step 4: コンテンツ生成

Step 3 で収集した情報をもとに、図解HTMLを生成する。検索結果で得た定義・事実・具体例を優先的に採用する。

模範回答のデザインを参考にしつつ、Tailwindの語彙で自由にレイアウトを組む。模範回答のパターンに合うものはそのまま使い、合わないものはTailwindクラスでその場で作る。テンプレートの定義済みパーツに縛られない。

### Step 5: ファイル作成

1. `output/` ディレクトリがなければ作成する
2. トピックに関連する短い英単語のスラッグを決める（例: `api-basics`, `git-rebase`）
3. `references/base.html` を `output/{スラッグ}.html` にコピーする
4. コピーしたファイル内のプレースホルダーをすべて置換する:
   - `<!-- TITLE -->` → 図解のタイトル
   - `<!-- DESCRIPTION -->` → 内容を要約した1文
   - `<!-- CONTENT_START -->` 〜 `<!-- CONTENT_END -->` → Step 4で生成したコンテンツ
5. ファイルを保存する（ブラウザで開くのは Step 6 のデプロイ後に行う。ローカルでは開かない）

### Step 6: 公開

ファイル保存後、公開する前にまず Node.js の有無を確認する。

```bash
node --version
```

バージョン番号が表示された → そのまま「公開の実行」に進む。

`command not found` と表示された → `references/node-install-guide.md` の手順に従ってNode.jsのインストールを案内する。

#### 公開の実行

以下のスクリプトを**実行する**（中身を読む必要はない）。コメントウィジェットの埋め込みはこのスクリプトが自動で行う。

**macOS / Git Bash（Windows）の場合:**

```bash
bash .claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh output/{スラッグ}.html [スラッグ]
```

**Windows（PowerShell）で bash が使えない場合:**

```powershell
$fbUrl = (Get-Content fb-tool-url.txt).Trim()
$apiToken = (Get-Content fb-api-token.txt).Trim()
$snippet = "<script src=`"$fbUrl/widget.js`" data-token=`"$apiToken`"></script>"
$dir = "$env:TEMP\diagram-deploy"
New-Item -ItemType Directory -Force $dir | Out-Null
# (?s)^(.*)</body> は貪欲マッチのため「最後の </body>」だけを置換する
# （本文中にコード例として </body> があっても多重注入しない。bash 版と同じ挙動）
(Get-Content output/{スラッグ}.html -Raw) -replace '(?s)^(.*)</body>', ('$1' + $snippet + '</body>') | Set-Content "$dir\index.html"
Set-Content "$dir\robots.txt" "User-agent: *`nDisallow: /"
npx --yes surge $dir --domain diagram-[スラッグ].surge.sh
Add-Content deploy-history.log "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') | https://diagram-[スラッグ].surge.sh"
```

スラッグにはトピックに関連する短い英単語を指定する（例: `git-rebase`, `api-basics`）。

#### 初回の場合（Surge未登録）

ターミナルにメールアドレスとパスワードの入力を求められる。以下を伝える:

> 初回のみアカウント登録が必要です。
> メールアドレスを入力して Enter → パスワードを決めて入力して Enter。
> 確認メールが届いたらリンクをクリックすれば登録完了です。
> 次回以降はこの手順は不要です。

#### エラーが出た場合

エラーメッセージをそのまま見せず、**何が起きていて何をすれば解決するか**を、専門用語を避けて平易に説明する。

よくあるエラーと対応:

- **`npx: command not found`** — Node.js がまだ入っていない。`references/node-install-guide.md` の手順を案内する
- **`surge: not found` / surge関連エラー** — `npm install -g surge` を実行してから再度試す
- **認証エラー / `Login required`** — `npx surge login` を実行してメールアドレスとパスワードを入力する
- **`fb-tool-url.txt が見つかりません`** — セットアップが未完了。チャット欄で「セットアップして」と伝えるよう案内する
- **その他** — エラーの内容を読み、「何が問題で」「次に何をすればいいか」を平易に説明する

### 図解の再デプロイ

ユーザーが「この図解を再デプロイして」と依頼した場合（内容の修正後や、公開済み図解にコメント機能を付け直すとき）:

1. 対象の HTML を特定する（直近に編集した `output/{スラッグ}.html`。不明ならリポジトリルートの `deploy-history.log` から URL を確認し、ドメインの `diagram-` 以降がスラッグ）
2. 「公開の実行」と同じコマンドを、**同じスラッグ**で再実行する（同じ URL に上書き公開される）

### 図解の削除

ユーザーが「この図解を削除して」と依頼した場合:

1. リポジトリルートの `deploy-history.log` を読み、直近のデプロイURLを特定する
   - ログが存在しない場合 → ユーザーに削除したいURLを聞く
2. `npx surge teardown [ドメイン]` を実行する
3. 削除完了をユーザーに伝える

### Step 7: 完了報告

#### 公開に成功した場合

```
完成・公開完了: 【図解のタイトル】

（図解の内容を1〜2文で要約）

公開URL:
https://diagram-スラッグ.surge.sh

図解の主なポイント:
- （主要トピックを3〜5個）

コメントの付け方:
ページ右端のボタンから、テキスト選択・ピン・音声（マイクに向かって喋る）の
3通りでフィードバックできます。

この図解を削除したいとき:
チャット欄で「この図解を削除して」と伝えてください。
```

#### 公開できなかった場合

```
完成: 【図解のタイトル】

（図解の内容を1〜2文で要約）

ファイルの保存先:
output/{スラッグ}.html（ブラウザにドラッグ＆ドロップすると表示できます）

図解の主なポイント:
- （主要トピックを3〜5個）

URLで共有したいとき:
チャット欄で「この図解を公開して」と伝えてください。
```

## 守ること（禁止事項）

- **見出し（`h1`〜`h4`）を必ず入れる** — 音声コメントはページ内の見出しを手がかりにピンを配置する。見出しが1つも無いHTMLでは音声フィードバックがエラーになる
- **React・shadcn/ui を使わない** — 静的な図解にJSフレームワークは不要。AIの出力を制限し、モデルによる品質差も限定的にしてしまう
- **絵文字を使わない** — OS依存で表示が変わる。アイコンはLucide Iconsを使う
- **インタラクティブ要素を入れない** — トグル、フェードイン、アニメーション、フォーム、クリックで開閉する要素は一切禁止
- **`<style>` タグを追加しない** — スタイリングはTailwind CSSクラスで行う。インラインの `style` 属性も避ける
- **`<script>` を追加しない** — テンプレートに含まれるもの以外のJavaScriptは禁止。widget.js の埋め込みはデプロイスクリプトが自動で行うため、SKILL の範囲外
- **外部リソースを追加しない** — テンプレートに含まれるCDN以外の外部読み込み（画像URL・フォント・追加CDN）は禁止
- **テンプレートの額縁構造を変更しない** — `<head>`・CDN読み込み・meta タグはそのまま維持する
- **PDF印刷で消える表現を使わない** — `bg-clip-text text-transparent` によるグラデーション文字はPDF出力時に透明のまま消える。テンプレートの print CSS でフォールバックを入れているが、グラデーション文字を使った場合はPDF出力で色が単色（`#2563EB`）に変わる点を意識すること

## コンテンツ生成の指針

- **概論 → 各論** — いきなり詳細に入らない。全体像を見せてから個別の話に入る
- **専門用語は初出で必ず解説** — 「API（Application Programming Interface＝ソフトウェア同士がやり取りするための窓口）」のように、括弧書きで平易に説明する
- **たとえ話で身近な体験に結びつける** — レストランの注文、郵便配達、信号機など、技術を知らない人でもイメージできる例を使う
- **簡潔にまとめすぎない** — 理解に必要な情報量は削らない。腹落ちするまで丁寧に説明する
- **図を早く見せる** — 見出しから最初のビジュアルまでに、テキストは最大2段落（各2〜3行）。それ以上の説明が必要な場合は、図を先に見せてから図の後にテキストで補足する（図→説明の順）。「説明してから図を見せる」より「図を見せてから説明する」方が、同じ文量でも「読まされている感」がなくなる。テキストで述べたたとえ話（ゲーム、レストラン等）も、テキストだけで済まさずミニビジュアル化を検討する
- **「見たことがあるもの」は説明するのではなく見せる** — 図解の中で読者がすでに体験しているもの（アプリの画面、ツールのUI、Webサイト）に言及するとき、テキストで「〜という画面が表示されます」と書く代わりに、その画面自体をTailwind CSSで再現して配置する。「天気アプリの画面」なら天気アプリのモックアップを、「チャット画面」ならチャットUIを、「ターミナル」ならターミナルウィンドウを見せる。読者の「見たことある！」という記憶が発火する瞬間が、テキスト説明より圧倒的に理解を深める
- **ビジュアルには2つの役割がある** — 図解に使うビジュアルは「構造を示す図」と「体験を再現する図」の2種類。どちらか一方ではなく、両方を組み合わせて使う:
  - **構造パターン（仕組みを頭で理解する図）** — 知識の種類に応じて選ぶ:
    - **「Xとは何か」(定義)** → アナロジー図: 身近なたとえの登場人物を配置し、矢印で関係を示す。主役を中央に大きく
    - **「Xはどう動くか」(プロセス)** → ステップフロー: 番号つき横並び（モバイルは縦）。各ステップにアイコン＋一言。色はステップごとに変える
    - **「XとYの違い」(比較)** → 左右対比: 2カラムで並べ、同じ観点を同じ行に揃える。✗/✓ や赤/緑で差を一目で伝える
    - **「Xの具体例」(事例)** → カードグリッド: 2列のカードにアイコン＋タイトル＋説明。カード内で「表の顔」と「裏の仕組み」を分けると深みが出る
    - **「Xのすごさ」(数値)** → 数字カード: 3カラムに大きな数字。text-3xl font-black で存在感を出し、色を各数字で変える
    - **「Xの構造・中身」(階層)** → 入れ子ブロック: 外側の大きなブロック内に構成要素を配置。ボーダーや背景色の濃淡で階層を表現
    - **「Xの誤解」(訂正)** → 誤解→正解カード: 赤ヘッダーに誤解、本文に緑で正解。✗と✓の対比
    - **「Xの変遷」(時系列)** → タイムライン: 左にボーダーライン、各時点に年号・ラベル・要約。色のグラデーションで時代の変化を表現
  - **体験再現パターン（読者の「見たことある」記憶と結びつける図）** — 読者が実際に触れたことのある画面をTailwind CSSで再現する。「あなたが見ているもの」「〜の画面では」「実際に使うとき」のような文脈が出てきたら、テキスト説明ではなくこちらを使う:
    - **チャットUI** — 吹き出し形式の対話画面。暗い背景＋ユーザー吹き出し（右寄せ）＋AI吹き出し（左寄せ）＋入力欄モック
    - **エディタUI** — タイトルバー（赤黄緑ボタン）＋サイドバー（ファイルツリー）＋コードペイン。AIチャットパネルを加えた3ペインも可
    - **ターミナルUI** — タイトルバー（赤黄緑ボタン）＋プロンプト（$）＋コマンド＋出力。コードブロックとの違いはウィンドウ枠がある点
    - **ブラウザUI** — タイトルバー（赤黄緑ボタン）＋アドレスバー＋ページ内容
    - **アプリ画面** — 上記に当てはまらないアプリ（天気予報、地図、決済画面など）。角丸カード内にアイコン＋数値＋ラベルでミニ画面を再現
    - 共通ルール: 中身はリアルすぎず要点が伝わるミニマルな内容にする。特定ブランドのロゴや名称は使わず汎用的な表現にする。Tailwind CSSクラスのみで構成する
- **冒頭にヒーロー＋一枚絵サマリー** — タイトルで「何の図解か」を伝えたあと、そのままトピックの核心を1枚の図で見せる。ヒーローの説明文を図への導入（「ひとことで言えば──」のような引き）にし、図の直後に各論への橋渡し（「ここからひとつずつ解説していきます」）を置く。ヒーロー → 一言の答え → 図 → 各論が一本の流れになること。一枚絵サマリーの構成:
  - **一言の答え**: トピックの核心を1文で太字表示（カード冒頭）。読者が「なるほど」と思える定義を先に読ませ、そのあとの図で視覚的に裏付ける
  - **コア図解**: 一言の答えを図にしたもの。アイコン＋矢印＋ラベルで表現
  - **身近な接点**: 読者がすでに体験している具体例を、アイコン＋一言のピルで2〜4個並べる
- **読者のレベルに言及しない** — 「初心者向け」「入門」「未経験者でもわかる」のように読者を特定のレベルにラベリングする表現をタイトル・見出し・本文に入れない。「わかりやすく説明する」のは図解の品質であって、読者のレベルではない。たとえ話や専門用語の解説で自然に噛み砕けば、ラベルなしで誰にでも伝わる
- **ヒーローバッジはトピックカテゴリ** — タイトル上のバッジには、トピックのカテゴリを入れる（テクノロジー、ビジネス、開発ツール、デザイン、マーケティングなど）。「初心者向け」「入門」など読者のレベルを示すラベルは入れない
- **インライン出典** — 検索結果から採用した事実・定義・数字のすぐ近くに、出典リンクをさりげなく添える。本文の読みやすさを損なわないよう `text-xs text-ads-dim` で小さく薄く表示し、リンクテキストはURLそのままではなく「出典: ○○公式ドキュメント」のようにページ内容がわかる名前にする。段落末やカード下部など、視線の流れを邪魔しない位置に置く
- **日本語で** — 英語メインのトピックでも、図解は日本語で書く