Communitygithub.com

hemangjoshi37a/scroll_animated_webpages_skill

從頭到尾建立獲獎級別的滾動動畫網站。執行探索精靈(人物/產品/公司/活動/理念),編譯滾動評分藍圖,搭建專案結構,實作 GSAP ScrollTrigger 動畫(可選 Lenis 平滑滾動),然後透過 Playwright MCP 在真實瀏覽器中驗證並修正發現的問題。當使用者想要滾動動畫網站、滾動驅動的登陸頁面、Apple 風格的產品滾動、Awwwards 風格網站、滾動敘事、視差或固定區塊、或圖片序列滾動效果時使用。

scroll_animated_webpages_skill 是什麼?

這是一個專業的 AI 技能,專為從頭到尾建立、驗證並交付獲獎級別的滾動動畫網站而設計。它遵循一個嚴謹的六階段流程:首先透過互動式精靈探索使用者的主題與目標,然後自主編譯一個結構化的藍圖(`scroll-score.json`)來定義每個滾動時刻(節拍)。技能接著會生成或收集所需素材,使用 Vite、TypeScript、GSAP 與 ScrollTrigger 搭建專案骨架,最後在 Playwright MCP 驅動的真實瀏覽器中徹底驗證成品。這個流程的關鍵區別在於其嚴格的紀律:探索階段後不允許提問,所有假設都記錄在 `DECISIONS.md` 中;並且透過真實的滑鼠滾輪輸入來驗證動畫,而非僅檢查程式碼。它支援多種模式(揭露、固定-擦除、水平滾動、粘性堆疊、媒體序列等),並內建針對常見 ScrollTrigger 陷阱(如 pin 損壞、Lenis 整合錯誤、動畫效能問題)的防護。該技能可在 Claude Code、Cursor 及其它支援 MCP 的 AI 代理環境中運作。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hemangjoshi37a/scroll_animated_webpages_skill/tree/HEAD/skills/scroll-animated-site

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

滾動動畫網站建構器

接收使用者提供的主題與對象,製作並交付一個完整、經過驗證的滾動驅動網站——過程中不中斷工作或將工作交回。

開始之前:這是新網站還是改造?

為已經有排名的頁面添加動畫是不同的工作,具有不同的風險——滾動預算必須包含現有頁面高度,而 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 調用以及權重預算。

三個來源,按偏好順序:

  1. 使用者提供——永遠優先。在精靈中要求提供,之後絕不再問。
  2. 生成——mcp__image-gen-mcp__generate_image(gpt-image-2,產品使用 background: "transparent",最高 3840x2160),或使用 edit_image 將真實產品照片轉換為風格化渲染。
  3. 佔位符——僅用於使用者明確推遲的節拍,且必須是有考量的漸層/文字排版組合,絕不能是灰色方塊。

對於圖片序列主視覺(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-sequenceApple 風格的產品揭示(Canvas + 影格)
media-scrub-video從影片檔案產生的相同效果(currentTime)
horizontal-scroll作品集、畫廊、時間線
mask-reveal一張影像展開以吞沒視埠
sticky-stack功能列表、堆疊卡片
scroll-progress進度條、計數器、章節指示器
theme-morph章節之間的背景/顏色轉換
snap-sections類似投影片,每個滾動一個章節的頁面

以及不可協商的 GSAP 規則:

→ 在撰寫 ScrollTrigger 程式碼之前,閱讀 references/04-gsap-rules.md。

最常破壞建構的五個規則:

  1. 每個時間軸一個 ScrollTrigger,並且放在時間軸上——絕不放在子補間上,也不嵌套在父時間軸內。
  2. 如果——並且僅當——你加入了 Lenis,它必須與 GSAP 共用循環。 lenis.on('scroll', ScrollTrigger.update) + gsap.ticker.add(t => lenis.raf(t * 1000)) + gsap.ticker.lagSmoothing(0)。 絕不為 Lenis 添加單獨的 requestAnimationFrame 循環。
  3. 在任何驅動 containerAnimation 或媒體擦除的補間上,加上 ease: "none"。
  4. 在同一個觸發器上,scrub 或 toggleActions,不能同時使用。
  5. 在字型和圖片載入後,執行 ScrollTrigger.refresh()——不僅在調整大小時。
  6. 在任何 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 以下,偏好使用淡入效果
  • ❌ 超出英雄序列的素材預算

相關技能