219 lines
16 KiB
Markdown
219 lines
16 KiB
Markdown
---
|
||
name: creating-visual-explainers
|
||
description: Generates an illustrated HTML page about any topic and deploys it to surge.sh. 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ファイル
|
||
|
||
## ワークフロー
|
||
|
||
### Step 0: 前提確認
|
||
|
||
`references/base.html` が存在するか確認する。
|
||
|
||
存在しない場合、以下を伝えて終了:
|
||
|
||
> テンプレートファイルが見つかりません。スキルのフォルダ構成が壊れている可能性があります。運営に連絡してください。
|
||
|
||
### 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
|
||
npx --yes surge output/{スラッグ}.html --domain 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` を実行してメールアドレスとパスワードを入力する
|
||
- **その他** — エラーの内容を読み、「何が問題で」「次に何をすればいいか」を平易に説明する
|
||
|
||
### 図解の削除
|
||
|
||
ユーザーが「この図解を削除して」と依頼した場合:
|
||
|
||
1. `deploy-history.log` を読み、直近のデプロイURLを特定する
|
||
- ログが存在しない場合 → ユーザーに削除したいURLを聞く
|
||
2. `npx surge teardown [ドメイン]` を実行する
|
||
3. 削除完了をユーザーに伝える
|
||
|
||
### Step 7: 完了報告
|
||
|
||
#### 公開に成功した場合
|
||
|
||
```
|
||
完成・公開完了: 【図解のタイトル】
|
||
|
||
（図解の内容を1〜2文で要約）
|
||
|
||
公開URL:
|
||
https://diagram-スラッグ.surge.sh
|
||
|
||
図解の主なポイント:
|
||
- （主要トピックを3〜5個）
|
||
|
||
この図解を削除したいとき:
|
||
チャット欄で「この図解を削除して」と伝えてください。
|
||
```
|
||
|
||
#### 公開できなかった場合
|
||
|
||
```
|
||
完成: 【図解のタイトル】
|
||
|
||
（図解の内容を1〜2文で要約）
|
||
|
||
ファイルの保存先:
|
||
output/{スラッグ}.html（ブラウザにドラッグ＆ドロップすると表示できます）
|
||
|
||
図解の主なポイント:
|
||
- （主要トピックを3〜5個）
|
||
|
||
URLで共有したいとき:
|
||
チャット欄で「この図解を公開して」と伝えてください。
|
||
```
|
||
|
||
## 守ること（禁止事項）
|
||
|
||
- **React・shadcn/ui を使わない** — 静的な図解にJSフレームワークは不要。AIの出力を制限し、モデルによる品質差も限定的にしてしまう
|
||
- **絵文字を使わない** — OS依存で表示が変わる。アイコンはLucide Iconsを使う
|
||
- **インタラクティブ要素を入れない** — トグル、フェードイン、アニメーション、フォーム、クリックで開閉する要素は一切禁止
|
||
- **`<style>` タグを追加しない** — スタイリングはTailwind CSSクラスで行う。インラインの `style` 属性も避ける
|
||
- **`<script>` を追加しない** — テンプレートに含まれるもの以外のJavaScriptは禁止
|
||
- **外部リソースを追加しない** — テンプレートに含まれる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そのままではなく「出典: ○○公式ドキュメント」のようにページ内容がわかる名前にする。段落末やカード下部など、視線の流れを邪魔しない位置に置く
|
||
- **日本語で** — 英語メインのトピックでも、図解は日本語で書く
|