interactive-study-guide

インタラクティブな学習ガイド

静的な学習ガイドの Markdown ファイルを、ローカルの Web アプリとして提供される、没入感のあるインタラクティブな学習体験に変換します。出力は、NYT のインタラクティブ特集や Pudding.cool のエッセイのような雰囲気にします。編集記事のようなタイポグラフィ、ゆとりのある余白、そして装飾ではなく構造を明らかにする、意図のあるアニメーションを取り入れます。

基本方針

• 派手さよりも節度を。 すべてのアニメーションは、静的なテキストでは伝えられない何かを明らかにするものでなければなりません。むやみな動きは避けます。
• コンテンツに合わせた表現。 各セクションのコンテンツに最適なレイアウトとインタラクティブ機能を選びます。文章のほうが適している箇所に、無理にビジュアライゼーションを使うことは避けます。
• スクロールで物語を紡ぐ。 主な操作はスクロールです。スクロールに連動した表示、スティッキー要素、要所での切り替えを使い、読むリズムを作ります。
• 自信のあるタイポグラフィ。 大きなセリフ体の見出し、適切な行の長さ、ゆったりとした垂直方向のリズムを取り入れます。インタラクティブ機能が読み込まれる前から、テキスト自体が美しく感じられるようにします。
• 段階的な機能強化。 JavaScript が動作しなくても、ページは読みやすく、役立つものでなければなりません。インタラクティブ機能はその上に重ねて追加します。

ワークフロー

ステップ 1：学習ガイドを見つけて解析する

学習ガイドの Markdown ファイルへのパスを受け取ります。codebase-study-guide の既知のテンプレート形式を使い、構造化されたセクションに解析します。

セクション	見出しのパターン	コンテンツの種類
目的	## 1. Why This Exists	課題、アプローチ、ユーザーに関する文章
閾値概念	## 2. The Big Ideas	コードの場所を含む、名前付きの概念
システムマップ	## 3. System Map	Mermaid 図と表
リクエストの流れ	## 4. Walking Through a Request	シーケンス図と注釈付きコードの手順
詳細解説	## 5. System Deep Dives	複数の ### 5.X サブセクション
パターン	## 6. Patterns & Conventions	名前付きのパターンと命名規則の表
境界	## 7. Boundaries & External Systems	外部システムの表
テスト	## 8. Testing Strategy	探索用プロンプトを含む文章
次のステップ	## 9. Your Next Steps	日ごとのチェックリスト

Markdown がこの正確な構造に合わない場合は、番号ではなく見出しの内容からセクションを検出し、柔軟に対応します。

ステップ 2：プロジェクトをセットアップする

スキャフォールドスクリプトを実行して、Vite プロジェクトを作成します。

bash scripts/scaffold.sh <output-directory> "<project-name>"

これにより、D3、Prism.js、編集記事向けのデザインシステムがあらかじめインストールされた、設定済みの Vite プロジェクトが作成されます。スキャフォールディングの完了後、出力ディレクトリで npm install を実行します。

Step 3: セクションごとに構築する

解析した各セクションを、対応するインタラクティブな要素に変換します。各セクションタイプの詳細なビジュアライゼーションパターンとコード例については、references/section-strategies.mdを参照してください。タイポグラフィ、色、間隔、モーションのすべてのトークンについては、references/design-system.mdを参照してください。

セクションとビジュアライゼーションの対応関係：

セクション	インタラクティブな表現
目的	画面いっぱいに広がるヒーロー領域に、大きなセリフ体のタイポグラフィを使用します。読み込み時にテキストがフェードインするアニメーションを加えます。問題提起は、太字の引用として示します。インタラクションは不要です。言葉の余韻を大切にしてください。
しきい値となる概念	折りたたまれた状態では概念名のみを表示するカードを使用します。クリックすると、滑らかな高さのトランジションで展開します。「この概念が見られる場所」を示すファイルパスは、クリック可能なピルとして表示します。関連する概念間には、控えめな接続線を引きます。
システムマップ	Mermaid 図に代わる、インタラクティブな D3 のフォースグラフを作成します。ノードはドラッグ可能にします。ホバーすると、表に記載された一行の目的を表示します。ノードをクリックすると、詳細解説のセクションまでスクロールします。アニメーション付きのエッジでデータフローの方向を示します。
リクエストのウォークスルー	スクロールに連動したステップ表示にします。左側の図を固定パネルとして表示し、右側の注釈付きコードステップを読者がスクロールするのに合わせてアニメーションさせます。各ステップでは、図の中で該当するシステムを強調表示します。コードブロックにはシンタックスハイライトを適用し、行ごとに表示します。
詳細解説	各システムをタブにしたインターフェースを作成します。各タブには、目的を太字の見出しで、パターン名をリンク付きバッジで表示し、抽象化の表、ミニ接続図で示すインターフェース、そして目立つコールアウトボックスに入れた探索タスクを配置します。
パターン	検索・絞り込み可能なカードグリッドにします。各カードには、パターン名、登場箇所（コードの場所を示すピル）、理由を表示します。カードをクリックすると、裏返すか展開して詳細を表示します。命名規則は、スタイルを整えた参考表で示します。
境界	ホバーすると行が展開する、見やすいデータテーブルにします。各行には、外部システム、その役割、統合パターンを表示します。システムの内側と外側を示すシンプルな境界図も検討してください。
テスト	最小限の表現にします。文章にはスタイルを適用し、探索プロンプトは独立したインタラクティブなコールアウトにします（チェックボックスを選択するとヒントが表示されます）。
次のステップ	ローカルストレージで状態を保持するインタラクティブなチェックリストにします。上部に進捗バーを配置します。各日を水平タイムライン上のノードとして示します。項目を完了すると、心地よいチェックアニメーションを表示します。

Step 4: ナビゲーションとトランジションを接続する

最小限のナビゲーションシステムを構築します。

• 左サイドバー（デスクトップ）またはボトムシート（モバイル）：セクションタイトルをナビゲーションリンクとして表示し、スクロールスパイで現在の位置を強調表示します
• 進捗インジケーター：ビューポート上部に細いバーを配置し、読了の進捗を表示します
• スムーズスクロール：ナビゲーションリンクをクリックすると、該当セクションまでアニメーションしながら移動します
• セクションのトランジション：IntersectionObserverを使用して、各セクションがビューポートに入るとフェードインさせます

Step 5: 開発サーバーを起動する

すべてのコンポーネントを構築した後：

cd <output-directory> && npx vite --open

Step 6: 仕上げの確認

ユーザーに提示する前に、次の点を確認してください。

• タイポグラフィの階層が明確である — 見出し、本文、コード、キャプションが視覚的に区別されている
• 余白にゆとりがある — セクションに十分な空間があり、窮屈に感じない
• アニメーションが滑らかで意図的である — カクつきや、不要なバウンスがない
• システムマップがインタラクティブである — ノードをドラッグでき、ホバーで情報が表示され、クリックで移動できる
• コードブロックに、コードベースの言語に適したシンタックスハイライトが適用されている
• モバイルレイアウトが機能する — 単一カラムで、タッチ操作に適している
• prefers-reduced-motionに準拠している — すべてのアニメーションが適切に無効化される
• 色のコントラストがWCAG AAを満たしている — 特にコードブロックと控えめな色のテキスト
• ナビゲーションのスクロールスパイが現在のセクションを正確に追跡している
• インタラクティブな要素（タブ、カード、チェックリスト）がすぐに応答する — 読み込み状態は不要

リソース

scripts/scaffold.sh

依存関係とエディトリアルデザインシステムが設定された Vite プロジェクトを作成します。使い方はステップ 2 に記載されています。

references/section-strategies.md

学習ガイドの各セクションに関する詳細な視覚化戦略とコードパターンです。構築時の主要なリファレンスです。セクションコンポーネントを書く前に参照してください。

references/design-system.md

エディトリアルデザインシステムの全容です。タイポグラフィのスケール、カラーパレット、スペーシング、モーションのトークン、コンポーネントレベルのスタイルを網羅しています。視覚に関するすべての判断で、これらのトークンを参照してください。