ビジュアルナラティブサイト納品ガイド
コア原則
まず確認 → 計画を出せ → 独立レビュー → 自己検証 → 実測で補正 → バッチで実装 → 各バッチはデプロイ可能。 「カクつかない」「見た目が良い」のようなスクリプトで判定できない受け入れ条件は禁止。すべての受入基準はヘッドレスブラウザでアサーション可能でなければなりません。
本スキルの6つの構成要素:
- 本ファイル：7フェーズのプロセス + 質問チェックリスト + レビューテンプレート + 報告フォーマット
references/verify-recipes.md：13種類のランタイム計測テクニック + 座標/パイプラインの落とし穴references/pitfalls.md：22の実機検証済み落とし穴（症状→根本原因→修正→一般則）references/animation-components.md：サードパーティ製Canvasコンポーネントの統合パターン（キャッシュキー/クリーンアップ/マウント条件/停止フレーム検証）references/content-sourcing.md：数字には出典か明示的な「教育用サンプル」の表示が必要（サイエンス/医療/データ系プロジェクトでは必須）assets/：long-stage.tsx+long-stage.css（長尺ステージの3層構造）、tokens.css（デュアルテーマ）、verify-skeleton.mjs.md（検証スクリプトのスケルトン）
トリガーに応じた参照先: サードパーティ製アニメーションコンポーネントを組み込む場合 → animation-components を読む。ページに具体的な数字や科学的結論がある場合 → content-sourcing を読む。それ以外はフェーズ順に読む。
フェーズ1: まず質問せよ、推測するな
要件に未確認の前提がある場合、コードを書くのは禁止。未決定の判断事項をツリー状に可視化し、毎回、前提条件が確定しているものから質問する。各質問には推奨回答とその理由を必ず添え、ユーザーがすぐにYes/Noで答えられるようにする。自分で確認できること（ファイルを読む、コマンドを実行する、ドキュメントを調べる）はユーザーに質問しない。
必須質問リスト（依存順、プロジェクトに応じてカット可能）:
- テーマは具体的に何か（分野/サブ分野/提示の角度）
- 誰に向けて作るか（専門用語の密度と許容範囲を決める）——「評価者/レビューアの視点」は暗黙的な要件であり、積極的に掘り下げるべき：「誰がこの出来を判定するのか？」と聞く方が、「どの程度の深さで書くか？」より効果的。
- ページを開いた第一印象で何を伝えたいか（一言で。候補例：「数字で衝撃を与える型」「質問で対話する型」「ギャップやサスペンスで引き込む型」）
- データソース: 実データ（出典あり）/ 教育用サンプル / 混在
- ビジュアルトーン: 没入型ダーク / プロフェッショナルライト / ハイコントラスト
- 納品形態: シングルページランディング / マルチチャプターの長尺スクロール / マルチページ
- 3Dは必要か（メリット vs 検証コスト）
- インタラクション強化: 長尺固定ステージ / マウス追従 / サードパーティアニメーションコンポーネント
- プロジェクトディレクトリのパス
- ユーザー提供の参考資料をどう扱うか（ソースコードに統合 vs ビジュアルリファレンスとしてのみ）
- オンラインURL / デプロイ方法
ユーザーが途中で決定を変えるのは正常（例：ライトテーマ→デュアルテーマ）。決定表には「元の決定は破棄」の記録を残し、黙って上書きしない。
フェーズ2: 計画を出し、承認を待て
計画ファイルを docs/plan-<テーマ>.md に作成し、リポジトリに含める。以下を必須とする:
- 現状分析: 既存プロジェクトを修正する場合、各記述に
file:lineを付ける。新規プロジェクトの場合はファイル一覧を記載。 - 決定表 D1～Dn: 各項目に「なぜこの選択をしたのか」を書き、「これをやろうと思う」とは書かない。
- バッチ分割: 各バッチは独立してデプロイ可能、ロールバック可能。
- 受入基準はスクリプトで判定可能に: 「カクつかない」→「rAFフレーム間隔の中央値が33ms以下」、「見た目が良い」→「隣接カードの blur(3px) opacity .55」。
- 「やらないこと」を明記: 実装範囲の拡大を防ぐため、除外項目を明確に書く。
フェーズ3: 明確な確認を待て
「うん」「いいよ」「OK」は曖昧とみなし、もう一度確認する。「任せる」は確認とみなさない。
フェーズ4: 独立レビュー
完全に新しいコンテキストのサブエージェントに計画をレビューさせる。サブエージェントには計画書だけでなく、実際のコードと検証スクリプトも与えなければならない。
あなたはこれから、まだ実装が始まっていない計画をレビューします。問題を見つけることがタスクであり、承認することではありません。
## 必読
- 計画書: <パス>
- 実コード: <プロジェクトルート>、特に <ファイル>
- 検証ツール: <スクリプトパス>
## 優先順位に従ってチェック
1. 事実の正確性（最も重要）: 各 `file:line` は正しいか？既存の動作に関する記述はすべて正しいか？間違っている場合、実コードの行を引用して反論せよ。
2. 完全性: N個の決定事項を実装すると主張しているなら、それぞれに対応するタスクが存在するか、個別に確認せよ。
3. 内部矛盾: セクションAで約束したことが、セクションBで禁止されていないか？
4. 具体的な技術リスク: このタスクで最も起こりそうなエラーを3～5個挙げよ。
5. 漏れ: 計画に書かれていないが、実装者が自分で発明しなければならないものは何か？
6. 検証可能性: 各基準は客観的に判定可能か？曖昧な表現はないか？
7. バッチ順序: あるバッチが後のバッチに依存していないか？どのバッチにも属さないものはないか？
## 出力
番号付きリスト。各項目: 重大度（BLOCKING/MAJOR/MINOR）、場所、何が間違っているか（証拠付き）、修正方法。
最後に結論: 実装に進んでよいか？
いかなるファイルも変更してはならない。礼儀のために承認してはならない——何も見つからなかったレビューは失敗したレビューである。
フェーズ5: レビュー意見は必ず自分で検証せよ
サブエージェントは間違える。 指摘された点を一つずつコードで確認し、正しい場合のみ修正する。「指摘の中に一つは間違いがある」と想定せよ。
観測された実際の結果の例:
- あるレビューでは16の指摘すべてが正しかった（7 MAJOR + 9 MINOR。うち3つは「検証メカニズム自体が機能していない」——アサーションが常にtrueまたは決して失敗しない）
- 別のケースでは、コンポーネントAのアイドル判定をコンポーネントBに誤って割り当てていた。ソースコードの行番号を読んで発見した。
フェーズ6: 実機計測で補正せよ
レビューエージェントはコードを読んで推論するが、ランタイム時のサイズ/フレームレート/コンポジット動作を読み取ることはできない。ヘッドレスブラウザで実測し、ドキュメントに書かれた数値はすべて実測値でなければならない。
references/verify-recipes.md を参照。
フェーズ7: バッチで実装せよ
各バッチ終了時: フル検証を実行 → git tag → コミット。コミットメッセージには「何を変えたか、なぜ変えたか、実測データ」を書く。
報告は固定の3セクション:
- やったこと: ファイル一覧 + 実測データ（「完了しました」ではなく、
pinTop=68.0、travel偏差0.0px） - 残っていること
- 発見したこと: 計画が間違っていたかコードが間違っていたか、どの行か
検証システムの最小構成（本プロジェクトの実績: 45アサーション / 7ユニットテスト）
| 層 | ツール | 担当範囲 |
|---|---|---|
| 型 | tsc --noEmit | 型の完全性。vitestがすべてパスしていてもビルドできるとは限らない。esbuildは型を剥がす |
| ユニット | vitest run | データの誠実性（出典フィールドが空でない、両方必須のものが共存している）、純粋関数 |
| ランタイム | scripts/verify.mjs（puppeteer-core + システムChrome） | レイアウトオーバーフロー、コントラスト、フレームレート、アニメーション状態、フォールバック分岐 |
| 納品 | npm run build | 実際の成果物がビルドできる |
アサーションは必ず失敗できるようにせよ。 各アサーションを書いた後、コードを逆に変更してFAILすることを確認せよ。そうしなければ、そのアサーションが常にtrueなのか、実際にテストしているのかが分からない。
ビューポートをまたぐアサーションは必ず setViewportSettled を使え。 page.setViewport はビューポートサイズがブラウザに送信されたことのみ保証し、リフロー完了は保証しない。続けて scrollWidth を読むと、縮小前の古い値が返り、間欠的なFAILを引き起こす（references/pitfalls.md 第21条参照）。このような間欠問題は繰り返し実行でのみ発覚する——1回の全パスは検証の証拠にならない。
よくある誤解
| 誤解 | 実際 |
|---|---|
| 「ユニットテストが通れば納品できる」 | esbuildは型を剥がすため、tsc がエラーを出してもvitestは全パスする |
| 「スクリーンショット差分で全ての視覚変化が測れる」 | ヘッドレススクリーンショットのパイプラインはDOMの再描画をキャプチャせず、Canvasのテクスチャのみをキャプチャする場合がある |
| 「ポーリングで500ms待てば十分」 | scroll-behavior:smooth + scrub:1 は非同期。明示的に instant にして、条件成立までポーリングする必要がある |
| 「レスポンシブはビューポートを変えて1回テストすれば十分」 | pin/タッチ/CDPの状態はテストケース間で汚染されるため、必ず新しいページか新しいブラウザプロセスを開く必要がある |
| 「reduced-motionはアニメーションを止めること」 | アニメーションは止めるが、情報は一切減らしてはならない。テキスト量が減っていないことをアサーションする |
他のスキルとの関係
- ビジュアル方向性/AI臭さ回避:
frontend-design、design-taste-frontend - 計画とレビューの規律:
writing-plans、plan-sds-review - 欠陥特定:
systematic-debugging - 実装後の検証:
verification-before-completion
本スキルはこれらのスキルがカバーしない部分を補完します: ランタイムデータの収集口径、ビジュアライゼーション固有の落とし穴、長尺スクロールナラティブの構造。