How-it-works サイト
コードベースを「なぜ」からコードまで説明する、依存関係のないスライドショーを site/ ディレクトリに作成します。プロジェクトの実際のロジックを反映したインタラクティブデモと、公開用のCIジョブが含まれます。リファレンス実装: https://mveplus.github.io/onair-led-sign-firmware/ （19スライド、4つのシミュレーション；ソースは https://github.com/mveplus/onair-led-sign-firmware/tree/main/site）。
このスキルの templates/ ディレクトリにあるテンプレート:
| ファイル | コピー先 | 目的 |
|---|---|---|
index.html | site/index.html | ページの枠組みと複製可能なスライドパターン |
deck.css | site/deck.css | テーマトークン、レイアウト、コンポーネント |
deck.js | site/deck.js | ナビゲーション、概要、ハッシュルーティング、フレームループ、ステッパーヘルパー |
app.js | site/app.js | プロジェクトのデモ用スターター（ステッパーの配線、フレームフック） |
github-pages.yml | .github/workflows/pages.yml | GitHub Pages デプロイ |
gitlab-ci.yml | .gitlab-ci.yml にマージ | GitLab Pages デプロイ |
プロジェクト固有のデモコードは site/app.js に記述します（スタイルはオプションで site/app.css）。deck.js と deck.css は汎用的に保ちます。
プロセス
1. 構築前に質問する（AskUserQuestion を1回呼び出す）
まず git remote -v を確認し、ホスティングに関する質問が現実を反映するようにします。リモートがGitHubなのにユーザーがGitLabと言った場合（またはその逆）、その点について質問します。最大4つの質問をします:
- ホスティング: GitHub Pages、GitLab Pages、または両方。
- 対象/深さ: 混合（最初にアイデア、その後詳細な掘り下げ；デフォルト）、開発者向け、または非開発者向け。
- インタラクティブデモ: このプロジェクトに固有の候補を3～4つ提案します（簡単にスキムして見つける。状態機械、タイミング/閾値ロジック、リクエストフロー、数学や数式、設定ビルダーなど）。multiSelect。
- オプション: リポジトリが示唆する場合、言語またはブランディングの制約。
2. コードを適切に読む
エントリポイント、主要モジュール、README/ドキュメント、CIファイルを読みます。スライドで言及するすべての主張（タイムアウト、しきい値、デフォルト値、トピック、エンドポイント、リセットがクリアする内容など）は、READMEではなくコードから取得します。ドキュメントとコードの不一致や行き止まり（例: コンシューマが存在しないCIジョブ）のリストを保持します。コードの実際の動作をスライドに表示し、リストを最後にユーザーに報告します。ドキュメントに合わせてスライドを静かに「修正」しないでください。
3. アウトライン（約12～20スライド）、章ごとにグループ化
典型的な流れ: タイトル（遊び心のあるインタラクティブ要素付き）→ アイデア/問題 → 全体像（クリック可能なアーキテクチャ）→ リクエスト/データフロー（アニメーションステッパー）→ 主要コンポーネントごとに1スライド → 耐障害性/障害処理 → セキュリティ/シークレット → ビルド、CI、配信 → 設計原則のまとめとリンク。すべてのスライドには data-chapter と data-title が必要です。
4. 構築
- テンプレートをコピーし、
index.html内のスライドパターン（ヒーロー、2カラム＋カード、ステッパー、情報グリッド）を複製します。 - シミュレーションはプロジェクトの実際のアルゴリズムを再利用します: 関数（整数演算、しきい値、順序付け）を移植し、スライド上でその関数名を引用します。見た目だけ正しいシミュレーションはバグです。
- アニメーションには
Deck.onFrame(slideId, fn)を使用し、表示中のスライドのみアニメーションさせます。クリックスルーシーケンスにはDeck.stepper(...)を使用します。 - 図: CSSトークンを使用したインラインSVG。外部リソースは使いません。CDNや取得するフォントは使用しないため、オフラインや制限付きPagesでも動作します。
- 画像: メタデータを削除しリサイズした上で
site/img/にコピーします（ImageMagick:magick in -auto-orient -strip -resize 1200x -quality 80 out.jpg）。リポジトリの元画像にGPS EXIFが含まれていないか確認（例:identify -format '%[EXIF:GPSLatitude]'またはexiftool -gps:all）し、見つかった場合はユーザーに警告します。スマートフォンの写真には通常、撮影場所が含まれています。一度プッシュするとgit履歴に残るため、削除するには履歴の書き換えが必要であり、それはユーザーが判断します。
5. 公開設定
- GitHub:
github-pages.ymlをコピーします。Pages は、一度ソース＝Actions に設定して有効にする必要があります（Settings → Pages）、または以下のコマンドを使用します。ユーザーがコピーするコマンドは、フェンスで囲まれたコードブロックに余計なものをつけずに表示します。文の終わりのピリオドが一緒にコピーされると引数に紛れ込み（build_type=workflow.）、APIが拒否します:
デフォルトブランチからのみデプロイします。gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow - GitLab:
pagesジョブを既存の.gitlab-ci.ymlにマージします。上書きしないでください。Pages は自動的に有効になります。URL は Deploy → Pages に表示されます。 - READMEの概要/「How it works」セクションに、短いリンクの段落を追加します。
6. 報告前に検証
node --check site/*.jspython3 -m http.server 8765 --bind 127.0.0.1 --directory siteでサーブします（バックグラウンドで）。ブラウザ自動化ツールが利用可能な場合（例: Claude in Chrome）、サイトを開き、各章をスクリーンショットし、各デモを座標クリックではなく、ページ内でJavaScriptを実行（.click()、ディスパッチされた PointerEvents）して操作します。スクリーンショットはCSSピクセルに対してスケーリングされることが多いため、座標クリックは位置を外します。ウィンドウサイズを変更できない場合、380pxのiframeでサイトを読み込み、getBoundingClientRect().right > 381を持つ要素を探して電話幅での表示を確認します。- ブラウザツールがない場合、手動で確認すべきページとデモをユーザーに伝えます。サイトを「テスト済み」として報告しないでください。
- 開いたタブを閉じ、その後サーバーを停止します。
7. 引き継ぎ
コミットまたはプッシュする前に質問します。その後、ブランチ上で: サイト用に1つのコミット、ユーザーが依頼したコード修正用に個別のコミット。報告内容: 構築したもの、Pagesの有効化方法、不一致リスト、およびテストされていないもの（例: ハードウェア）。
スタイルルール
- デフォルトはダークテーマ（
deck.cssのトークン）。プロジェクトごとに--accentで色を変更可能な赤のアクセントカラーを使用。 - 平易で具体的な文章。「何をするか」だけでなく、なぜその設計選択が存在するのかを説明します。
- コード抜粋は短く、実際のもの（ソースからトリミングし、ファイル名を示すコメントを付ける）。
- キーボード: ←/→/Space/PageUp/PageDown/Home/End、
Oで概要、Escで閉じる。タッチでスワイプ。すべてのスライドは独自のURLを持つ（#/スライドID）。