滾動動畫網站建構器
接收使用者提供的主題與對象,製作並交付一個完整、經過驗證的滾動驅動網站——過程中不中斷工作或將工作交回。
開始之前:這是新網站還是改造?
為已經有排名的頁面添加動畫是不同的工作,具有不同的風險——滾動預算必須包含現有頁面高度,而 pin 會消耗使用者掃描以做決策的頁面的有效滾動距離。預設做法是在單獨的展示 URL 上建構並連結到它;僅在頁面沒有流量損失風險且其目的是營造印象而非提供參考時,才在原位進行轉換。務必先進行逐字節的備份,並將還原指令交給使用者。同意改造前,請先閱讀 references/08-failure-modes.md §3。
流程
六個階段。依序執行。只有第 1 階段與使用者對話。
1 探索 → 精靈,2–3 輪問題 [互動式]
2 評分 → 編譯 scroll-score.json 藍圖 [自主]
3 素材 → 生成/收集圖片、影格、影片 [自主]
4 搭建 → 專案骨架 + 動畫運行環境 [自主]
5 建構 → 實作評分中的每一個節拍 [自主]
6 驗證 → 驅動真實瀏覽器,修正,重複 [自主]
第 1 階段精靈關閉後,不再提問。 第 2–6 階段根據你的判斷自主運行至完成。將假設記錄在 DECISIONS.md 中,並在最後報告它們,而不是因提問而阻塞。使用者要求的是端到端的建構;一個半成品頁面加上一個問題,就是一次失敗的執行。
第 1 階段——探索(精靈)
使用 AskUserQuestion 工具提問,絕不要用一大段文字。通常兩輪,最多三輪。完整問題庫,按分支區分:
→ 閱讀 references/01-discovery-wizard.md
第 1 輪總是相同的兩個問題——對象類型和主要目標:
| 對象 | 滾動的核心目的 |
|---|---|
| 人物(作品集、履歷、個人品牌) | 建立信任:作品 → 證明 → 聯絡 |
| 產品(實體或數位) | 揭示物品:主視覺 → 功能 → 購買 |
| 公司(代理商、新創公司、工作室) | 建立規模:宣言 → 作品 → 團隊 |
| 活動 / 發布(會議、限量發售、發表會) | 營造期待:日期 → 陣容 → 註冊 |
| 理念 / 故事(非營利組織、社論、報告) | 傳遞論點:鉤子 → 證據 → 行動 |
你落腳的分支決定了章節骨架和主導的動畫模式。第 2 輪詢問分支特定的問題(什麼作品、什麼產品、什麼證明)。第 3 輪,僅在仍然模糊時,確定美學方向、動畫強度和素材策略。
一旦你能夠說出以下內容,就停止精靈: 對象、目標、4–7 個章節、美學方向、以及素材來源。其餘部分自行推斷。
第 2 階段——評分(藍圖)
將所有內容編譯到專案根目錄的 scroll-score.json 中。這是建構和驗證器都會讀取的合約——在撰寫任何元件之前先寫好它。
→ 閱讀 references/02-scroll-score.md 以了解完整 schema。
評分是一系列的節拍。一個節拍 = 一個滾動驅動的時刻:什麼被固定、什麼被擦除、覆蓋多少距離、以及什麼在移動。
{
"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 階段——素材
絕不交付灰色方塊。評分中命名的每個節拍在第 5 階段之前都需要其真實素材——使用佔位符進行建構,總是需要重做。
→ 閱讀 references/05-asset-pipeline.md 以了解完整的流程,包括 AI 渲染 → 插值影片 → 影格序列的鏈路、所有 ffmpeg 調用以及權重預算。
三個來源,按偏好順序:
- 使用者提供——永遠優先。在精靈中要求提供,之後絕不再問。
- 生成——
mcp__image-gen-mcp__generate_image(gpt-image-2,產品使用background: "transparent",最高3840x2160),或使用edit_image將真實產品照片轉換為風格化渲染。 - 佔位符——僅用於使用者明確推遲的節拍,且必須是有考量的漸層/文字排版組合,絕不能是灰色方塊。
對於圖片序列主視覺(Apple 風格的「產品隨滾動展開」),流程是:第一幀 + 最後一幀 → 插值影片 → 提取影格 → WebP 序列 → Canvas 擦除。 保持序列總大小低於 4 MB,36–60 幀,寬 1600px。這個預算正是該效果保持可用的全部原因;超出預算是此模式最常見的失敗原因。
第 4 階段——搭建
預設技術棧,除非使用者指定:Vite + vanilla TS + GSAP。它沒有框架生命週期需要對抗,而且 ScrollTrigger 在 React 中的問題幾乎都是清理錯誤。僅在使用者要求或專案需要路由時才使用 Next.js/React,然後使用 useGSAP() 進行清理——絕不使用裸 useEffect。
平滑滾動(Lenis)是選擇加入的——它不再是預設技術棧的一部分。 僅在使用者明確要求平滑或慣性滾動時才加入。它用自己的動畫位置取代了原生滾動,一旦感覺稍有偏差,整個頁面就會被認為是壞的——這是技術正確的建構被拒絕的最常見原因。ScrollTrigger 的 scrub 已經提供了人們通常所說的「平滑」那種緩和、電影般的感覺。
參閱 references/08-failure-modes.md §1。
→ 閱讀 references/07-stack-setup.md 以了解架構和確切指令。
GSAP 自 v3.13 起100% 免費(Webflow 收購後),包括 SplitText、ScrollSmoother 和 MorphSVG。npm install gsap 即可取得一切——不需要授權金鑰、不需要 gsap-trial、也不需要 CDN 外掛的因應措施。不要告訴使用者某個外掛是需要付費的。
內容存放在 src/content.ts 中,絕不內嵌在標記中。使用者必須能夠在不觸碰動畫程式碼的情況下更換文案。
第 5 階段——建構
使用標準模式實作來實作評分中的每個節拍:
→ 閱讀 references/03-pattern-library.md —— 12 種模式,可複製使用。
| 模式 | 用途 |
|---|---|
reveal-on-enter | 標準章節入口、卡片網格 |
text-reveal | 標題、引人注目的引言(SplitText,遮罩) |
pin-scrub | 核心的「令人驚嘆」時刻——固定舞台,擦除時間軸 |
parallax-layers | 深度:背景、前景道具 |
media-scrub-sequence | Apple 風格的產品揭示(Canvas + 影格) |
media-scrub-video | 從影片檔案產生的相同效果(currentTime) |
horizontal-scroll | 作品集、畫廊、時間線 |
mask-reveal | 一張影像展開以吞沒視埠 |
sticky-stack | 功能列表、堆疊卡片 |
scroll-progress | 進度條、計數器、章節指示器 |
theme-morph | 章節之間的背景/顏色轉換 |
snap-sections | 類似投影片,每個滾動一個章節的頁面 |
以及不可協商的 GSAP 規則:
→ 在撰寫 ScrollTrigger 程式碼之前,閱讀 references/04-gsap-rules.md。
最常破壞建構的五個規則:
- 每個時間軸一個 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()——不僅在調整大小時。 - 在任何 pin 之前,檢查祖先元素是否有
transform/filter/contain。 其中任何一個都會默默地破壞position: fixed,因此 pin 被建立了,回報pin: true,但實際上沒有任何作用。移除該屬性或設定pinType: 'transform'。參閱08-failure-modes.md§2。
僅對 transform 和 opacity 進行動畫。任何在滾動時觸及 top、left、width、height 或 margin 的屬性都會掉幀。
第 6 階段——驗證
此階段非可選,也是這項技能與手寫 GSAP 的區別所在。 滾動動畫無法透過閱讀程式碼來驗證——pin 會塌陷、觸發器會在錯誤的深度觸發、影格只會在真實瀏覽器的真實視埠中遺失。
→ 閱讀 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。虛擬滾動會被滾動劫持庫吞沒,這正是你需要捕捉的失敗。如果滑鼠滾動三下沒有移動頁面,無論斷言說什麼,頁面都是壞的。
如果出現以下任何一種情況,則判定運行失敗並進行修正:
- 一個主控台錯誤,或任何
ScrollTrigger警告 - 任何 404 錯誤,或素材總權重超出預算
- 在任何深度出現空白/無樣式的截圖
- 一個固定區塊與下一個區塊重疊,或導致版面塌陷
- 內容從未變得可見(一個從未觸發的揭露效果)
- 在 390px 寬度下出現水平溢出
markers: true殘留在原始碼的任何地方- 沒有
prefers-reduced-motion的降級方案 - 真實滑鼠滾動三下無法明顯移動頁面
- 一個固定區塊的舞台仍在追蹤滾動(在範圍內斷言
|rect.top| < 10) - 擦除的媒體在其 pin 結束之前約 90% 就達到了末端
- 需要超過約 40 下滑鼠滾輪才能到達主要行動呼籲按鈕
循環進行修正 → 重新驗證直到通過,最多 5 輪。如果某項在 5 輪後仍然失敗,則交付其餘部分,將該節拍放在一個旗標後面停用,並在最終報告中清楚說明。絕不報告未經驗證的頁面為成功。
完成定義
-
scroll-score.json與實際建構的內容相符 - 每個節拍在桌面和行動版均已驗證
- 零主控台錯誤,零 404 錯誤
-
prefers-reduced-motion降級為即時狀態,無動畫 - Lighthouse 似的完整性檢查:無因 pin 導致的版面位移,圖片已設定尺寸
-
README.md—— 如何執行、內容放在哪裡、如何更換素材 -
DECISIONS.md—— 精靈關閉後所做的假設 - 最終訊息:建構了什麼、假設了什麼、需要審查什麼
禁止事項
- ❌ 在精靈關閉後提問——改為假設、記錄並報告
- ❌ 未在第 6 階段的真實瀏覽器中執行就報告完成
- ❌ 在交付的程式碼中留有
markers: true、console.log或TODO - ❌ 使用
gsap-trial或聲稱 SplitText/ScrollSmoother 需要 Club 授權 - ❌ 在滾動時對版面屬性進行動畫
- ❌ 在行動版上使用 pin 而不進行檢查——在 768px 以下,偏好使用淡入效果
- ❌ 超出英雄序列的素材預算