スクロールアニメーションサイトビルダー
ユーザーからトピックと対象を聞き、完全で検証済みのスクロール駆動型Webサイトを納品します。途中で作業を差し戻しにすることはありません。
始める前に:新規サイトか、既存サイトへの後付けか?
すでに検索順位がついているページにアニメーションを追加するのは別の仕事であり、リスクが異なります。スクロール予算には既存のページ高を含める必要があり、ピンはユーザーが意思決定のためにページをスキャンしている領域での無駄なスクロール距離となります。デフォルトでは別のショーケースURLで構築し、リンクで誘導するようにしてください。ページにトラフィックがなく、参照ではなく印象が目的の場合にのみ、その場で変換を行います。必ず事前にバイト単位のバックアップを取得し、復元コマンドをユーザーに渡してください。後付けの同意前にreferences/08-failure-modes.md §3を読んでください。
パイプライン
6つのフェーズ。順番に実行します。ユーザーと対話するのはフェーズ1のみです。
1 DISCOVER → ウィザード、2〜3ラウンドの質問 [インタラクティブ]
2 SCORE → scroll-score.jsonの設計書を作成 [自律実行]
3 ASSETS → 画像、フレーム、動画を生成/収集 [自律実行]
4 SCAFFOLD → プロジェクトの骨格とモーションランタイム [自律実行]
5 BUILD → Scoreのすべてのビートを実装 [自律実行]
6 VERIFY → 実ブラウザで動作確認、修正、繰り返し [自律実行]
フェーズ1でウィザードを閉じた後は、質問をやめてください。 フェーズ2〜6は、自身の判断で完了まで実行します。前提条件はDECISIONS.mdに記録し、最後に報告するにとどめ、その場でブロックしないでください。ユーザーはエンドツーエンドのビルドを依頼しています。中途半端なページと質問の組み合わせは失敗です。
フェーズ1 — DISCOVER(ウィザード)
AskUserQuestionツールで質問してください。散文で一気に尋ねないでください。典型的には2ラウンド、最大でも3ラウンドです。完全な質問バンクは以下のブランチ構造に従います。
→ references/01-discovery-wizard.mdを読む
ラウンド1は常に同じ2つの質問です。対象の種類と主要な目的です:
| 対象 | スクロールが本当にしていること |
|---|---|
| 個人(ポートフォリオ、履歴書、個人ブランド) | 信頼を獲得する:仕事 → 証明 → 連絡先 |
| 製品(物理的またはデジタル) | 対象を明らかにする:ヒーロー → 機能 → 購入 |
| 企業(代理店、スタートアップ、スタジオ) | 規模を示す:マニフェスト → 仕事 → チーム |
| イベント/ローンチ(カンファレンス、ドロップ、リリース) | 期待を高める:日付 → ラインナップ → 申し込み |
| 原因/ストーリー(非営利、編集、報告) | 主張を伝える:フック → 証拠 → 行動 |
選択したブランチによって、セクションの骨格と主要なモーションパターンが決まります。ラウンド2ではブランチ固有の質問(どの仕事か、どの製品か、どの証明か)を行います。ラウンド3は、対象、目的、美観の方向性、アセットの入手先がまだ不明瞭な場合のみ、方向性やモーション強度、アセット戦略を詰めます。
以下の項目が特定できた時点でウィザードを終了してください: 対象、目的、4〜7個のセクション、美観の方向性、アセットの入手元。残りは推測します。
フェーズ2 — SCORE(設計書)
すべてをscroll-score.jsonとしてプロジェクトルートにまとめます。これがビルドと検証の両方が読み取る契約書です。コンポーネントを書き始める前に作成してください。
→ **references/02-scroll-score.md**で完全なスキーマを確認する。
Scoreはビートのリストです。1ビート=1つのスクロール駆動モーメント:何をピンするか、何をスクラブするか、どの距離で、何が動くか。
{
"meta": { "subject": "…", "type": "product", "goal": "…", "stack": "vite-vanilla" },
"theme": { "bg": "#0a0a0a", "fg": "#fafafa", "accent": "#ff4d17", "font": { … } },
"motion":{ "intensity": "cinematic", "smoothScroll": false, "reducedMotion": "degrade" },
"beats": [
{ "id": "hero", "pattern": "media-scrub-sequence", "pin": true,
"scrub": 1, "start": "top top", "end": "+=200%", "frames": 48, … },
{ "id": "features", "pattern": "sticky-stack", … }
]
}
スクロール予算を計算する。 ページ全体の高さはおおよそ100vh × (1 + Σ ビートのスクロールコスト)に近づける必要があります。ピンでスクラブするビートは1.5〜2.5ビューポート高、リビールビートは約1ビューポート高です。合計が3未満だとサイトが唐突に感じられ、12を超えると負担に感じます。5〜9を目指してください。
フェーズ3 — ASSETS
グレーのボックスを絶対に納品しないでください。Scoreに記載されたすべてのビートには、フェーズ5の前に実際のアセットが必要です。プレースホルダーを使ってビルドしたものは必ずやり直しになります。
→ **references/05-asset-pipeline.md**で完全なパイプラインを確認する。AIレンダリング→補間動画→フレームシーケンスのチェーン、すべてのffmpeg呼び出し、およびウェイト予算が含まれています。
3つのソース、優先順位順:
- ユーザー提供 — 常に最優先。ウィザード内で依頼し、後回しにしないでください。
- 生成 —
mcp__image-gen-mcp__generate_image(gpt-image-2、製品の場合はbackground: "transparent"、最大3840x2160)、またはedit_imageで実際の製品写真をスタイル付けレンダリングに変換。 - プレースホルダー — ユーザーが明示的に延期したビートのみ。ただし、検討されたグラデーション/タイポグラフィ構成でなければならず、グレーのボックスは不可。
イメージシーケンスヒーロー(Apple風「スクロールで製品が展開する」効果)の場合、チェーンは以下の通り:最初のフレーム+最後のフレーム→補間動画→フレーム抽出→WebPシーケンス→キャンバススクラブ。シーケンスは合計4MB以下、36〜60フレーム、幅1600pxに抑えてください。この予算がこの効果を使い物にするためのすべてです。予算超過はこのパターンで最も一般的な失敗です。
フェーズ4 — SCAFFOLD
デフォルトのスタック(ユーザーが指定しない場合):Vite + vanilla TS + GSAP。フレームワークのライフサイクルと戦う必要がなく、ReactでのScrollTriggerバグはほぼ常にクリーンアップバグです。Next.js/Reactはユーザーが明示的に要求した場合、またはルーティングが必要なプロジェクトでのみ使用し、その場合はクリーンアップにuseGSAP()を使用してください。裸のuseEffectは使わないでください。
スムーススクロール(Lenis)はオプトインです。デフォルトのスタックには含まれなくなりました。 ユーザーが明示的に「スムース」や「慣性スクロール」と名前を挙げた場合のみ追加してください。Lenisはネイティブスクロールを独自のアニメーション位置に置き換えるため、少しでも違和感があるとページ全体が壊れているように見えます。これは、技術的に正しいビルドが却下される最も一般的な理由です。ScrollTriggerのscrubは、通常ユーザーが「スムース」と言うときに意味している、イージングの効いた映画的な感覚をすでに提供します。references/08-failure-modes.md §1を参照してください。
→ **references/07-stack-setup.md**でスキャフォールドと正確なコマンドを確認する。
GSAPはv3.13以降(Webflow買収後)100%無料で、SplitText、ScrollSmoother、MorphSVGも含まれます。npm install gsapですべてが取得できます。ライセンスキー、gsap-trial、CDNプラグインの回避策は必要ありません。ユーザーにプラグインが有料だと伝えないでください。
コンテンツはsrc/content.tsに配置し、マークアップにインラインで記述しないでください。ユーザーはモーションコードに触れずにコピーを変更できる必要があります。
フェーズ5 — BUILD
Scoreの各ビートを、標準的なパターン実装を使用して実装します。
→ references/03-pattern-library.md — 12のパターン、コピー可能。
| パターン | 使用する場面 |
|---|---|
reveal-on-enter | 標準的なセクションエントランス、カードグリッド |
text-reveal | 見出し、プルクォート(SplitText、マスク) |
pin-scrub | 核となる「ワウ」要素—ピン留めされたステージ、スクラブされたタイムライン |
parallax-layers | 奥行き:背景、前景プロップ |
media-scrub-sequence | Apple風プロダクトリビール(キャンバス+フレーム) |
media-scrub-video | 動画ファイルからの同じ効果(currentTime) |
horizontal-scroll | ポートフォリオ、ギャラリー、タイムライン |
mask-reveal | 画像が開いてビューポートを飲み込む |
sticky-stack | 機能リスト、カードのスタッキング |
scroll-progress | プログレスバー、カウンター、セクションインジケーター |
theme-morph | セクション間の背景/色の変化 |
snap-sections | デッキ風、1セクション1スクロールのページ |
そして、絶対に守るべきGSAPルール:
→ ScrollTriggerコードを書く前にreferences/04-gsap-rules.mdを読む
ビルドを最も頻繁に壊す5つ:
- タイムラインごとに1つのScrollTriggerを、タイムラインに設定する — 子トゥイーンには決して設定せず、親タイムラインの中にネストしないでください。
- Lenisを追加した場合(追加した場合のみ)、GSAPのループと共有する。
lenis.on('scroll', ScrollTrigger.update)+gsap.ticker.add(t => lenis.raf(t * 1000))+gsap.ticker.lagSmoothing(0)。Lenis用に別のrequestAnimationFrameループを追加しないでください。 containerAnimationやメディアスクラブを駆動するトゥイーンには**ease: "none"**を設定する。- 同じトリガーに**
scrubとtoggleActionsの両方を設定しない**。 - フォントと画像のロード後に**
ScrollTrigger.refresh()**を呼び出す — リサイズ時だけでなく。 - ピンの前に、先祖要素に
transform/filter/containがないか確認する。 これらはいずれも静かにposition: fixedを壊すため、ピンは作成されpin: trueを報告するが何もしません。プロパティを削除するか、pinType: 'transform'を設定してください。08-failure-modes.md§2を参照。
transformとopacityのみをアニメーションさせてください。top、left、width、height、marginに触れるものはスクロール時にフレームを落とします。
フェーズ6 — VERIFY
このフェーズはオプションではなく、このスキルを手書きのGSAPと区別するものです。 スクロールアニメーションはコードを読むだけでは検証できません。ピンが崩れたり、トリガーが間違った深さで発火したり、フレームが欠落したりする問題は、実際のブラウザと実際のビューポートでのみ発見できます。
→ **references/06-verification.md**で完全なループとチェックリストを確認する。
→ references/08-failure-modes.md — すべての自動チェックを通過する失敗モード。何かが壊れる前にフェーズ4の前に読んでください。
開発サーバーを起動し、Playwright MCPで操作します:
mcp__playwright__browser_navigate → 開発サーバーのURL
mcp__playwright__browser_resize → 1440×900、その後390×844
mcp__playwright__browser_evaluate → スクロール深さまで移動、状態を読み取り
mcp__playwright__browser_take_screenshot → 各深さで
mcp__playwright__browser_console_messages → エラーとGSAP警告
mcp__playwright__browser_network_requests → 404、アセット容量
デスクトップとモバイルでページ高の**0 %、15 %、30 %、50 %、70 %、85 %、100 %**をスイープします。各停止点でスクリーンショットを撮り、見てください。チェックしているのは、ページが見た目に正しいかどうかであり、単にエラーがスローされていないかどうかではありません。
実際の入力でページを操作してください — mouse.wheel()またはキー押下で、決してwindow.scrollToは使わないでください。シンセティックスクロールはスクロールハイジャックライブラリに飲み込まれ、それがまさに捕捉すべき失敗です。3回のホイールノッチでページが動かない場合、アサーションが何と言おうと壊れています。
以下のいずれかに該当する場合、実行を失敗とし、修正してください:
- コンソールエラー、または
ScrollTriggerの警告 - 404、または総アセット容量が予算超過
- いずれかの深さで空白/スタイル未適用のスクリーンショット
- ピン留めされたセクションが次のセクションと重なる、またはレイアウトを崩す
- 表示されないコンテンツ(発火しないリビール)
- 幅390pxで水平方向のオーバーフロー
- ソースのどこかに
markers: trueが残っている prefers-reduced-motionフォールバックがない- 3回の実際のホイールノッチでページが目に見えて動かない
- ピンのステージがスクロールを追跡し続ける(範囲内で
|rect.top| < 10を確認) - スクラブメディアがピン終了の約90%より前に終端に達する
- 主要CTAに到達するまでに約40回以上のホイールノッチが必要
修正→再検証のループを、クリーンになるまで最大5ラウンド繰り返します。5回後も何かが失敗する場合、残りを出荷し、そのビートをフラグで無効にして、最終報告書にその旨を明確に記載してください。未検証のページで成功を報告しないでください。
完了条件
-
scroll-score.jsonが実際にビルドされたものと一致する - すべてのビートがデスクトップおよびモバイルで検証済み
- コンソールエラーゼロ、404ゼロ
-
prefers-reduced-motionは瞬時状態に劣化し、モーションなし - Lighthouse的に健全:ピンによるレイアウトシフトなし、画像サイズ設定済み
-
README.md— 実行方法、コンテンツの場所、アセットの交換方法 -
DECISIONS.md— ウィザード終了後に下した前提条件 - 最終メッセージ:何をビルドしたか、何を前提としたか、何を確認すべきか
やってはいけないこと
- ❌ ウィザード終了後に質問をする — 代わりに推測し、記録し、報告する
- ❌ フェーズ6を実ブラウザで実行せずに完了と報告する
- ❌ 納品コードに
markers: true、console.log、TODOを含める - ❌
gsap-trialを使用したり、SplitText/ScrollSmootherにClubライセンスが必要だと主張する - ❌ スクロールでレイアウトプロパティをアニメーションさせる
- ❌ チェックなしでモバイルにピン留めする — 768px未満ではフェードインを優先する
- ❌ ヒーローシーケンスのアセット予算を超える