滚动动画网站构建器
获取用户的主题和对象,交付一个完整的、已验证的、滚动驱动的网站——中途不将工作交还给用户。
开始前:新网站还是改造?
为已有排名的页面添加动画是一项不同的任务,具有不同的风险——滚动预算必须包含现有页面高度,而钉固(pin)在用户正在滚动做决定的页面上意味着可滚动距离的浪费。默认构建单独的展示 URL并链接到它;仅当页面没有流量损失风险且其任务是留下印象而非作为参考时,才进行原地改造。务必先进行逐字节备份并向用户提供恢复命令。在同意改造前,请阅读 references/08-failure-modes.md §3。
流水线
六个阶段。按顺序执行。仅阶段 1 与用户对话。
1 DISCOVER → 向导,2–3 轮问题 [交互式]
2 SCORE → 编译 scroll-score.json 蓝图 [自主式]
3 ASSETS → 生成/收集图片、帧、视频 [自主式]
4 SCAFFOLD → 项目骨架 + 动画运行环境 [自主式]
5 BUILD → 实现评分中的每一个拍节(beat) [自主式]
6 VERIFY → 驱动真实浏览器,修复,重复 [自主式]
向导在阶段 1 结束后,停止提问。 阶段 2–6 由你自行判断并执行完毕。在 DECISIONS.md 中记录假设并在最后报告,而不是阻塞等待回答。用户要求的是端到端构建;一个半成品页面加上一个问题就是一次失败的运行。
阶段 1 — 发现(向导)
使用 AskUserQuestion 工具提问,不要使用长篇大论的散文。通常两轮,最多三轮。完整的问题库,按分支分类:
→ 阅读 references/01-discovery-wizard.md
第一轮总是相同的两个问题——主体类型和主要目标:
| 主体 | 滚动实际上在做什么 |
|---|---|
| 人物(作品集、简历、个人品牌) | 建立信任:工作 → 证明 → 联系 |
| 产品(实体或数字) | 揭示对象:英雄区 → 功能 → 购买 |
| 公司(代理商、初创公司、工作室) | 展示规模:宣言 → 作品 → 团队 |
| 活动/发布(会议、首发、发布) | 营造期待:日期 → 阵容 → 注册 |
| 事业/故事(非营利、编辑、报告) | 承载论点:钩子 → 证据 → 行动 |
你所处的分支决定了章节骨架和主导动画模式。第二轮询问分支特定问题(什么作品、什么产品、什么证明)。第三轮,仅在仍然模棱两可时,确定美学方向、动画强度和资产策略。
一旦你能说出以下信息,就停止向导: 主体、目标、4–7 个章节、美学方向以及资产来源。其余信息自行推断。
阶段 2 — 评分(蓝图)
将所有内容编译到项目根目录下的 scroll-score.json。这是构建和验证器都需读取的契约——在编写任何组件之前先编写它。
→ 阅读 references/02-scroll-score.md 了解完整模式。
一个评分由一系列**拍节(beat)**组成。一个拍节 = 一个滚动驱动的时刻:什么钉固(pin)、什么同步(scrub)、滚动多远、什么移动。
{
"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 + Σ beat scroll cost)。一个钉固同步(pinned scrub)拍节花费 1.5–2.5 个视口高度;一个出现(reveal)拍节花费约 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 同步(canvas scrub)。保持序列总大小不超过 4 MB,36–60 帧,宽度 1600px。这个预算正是该效果保持可用的全部原因;超出预算是此模式最常见的失败原因。
阶段 4 — 搭建
默认技术栈,除非用户指定:Vite + vanilla TS + GSAP。它没有框架生命周期需要处理,并且 ScrollTrigger 在 React 中的 bug 几乎总是清理(cleanup)bug。仅当用户要求或项目需要路由时才使用 Next.js/React,然后使用 useGSAP() 进行清理——绝不要使用裸的 useEffect。
平滑滚动(Lenis)是可选加入的——它不再是默认技术栈的一部分。 仅当用户明确要求平滑或惯性滚动时才添加。它会用自己的动画位置替换原生滚动;当它感觉稍有不对时,整个页面就会被认为是坏掉的——这是技术上正确的构建被拒绝的最常见原因。ScrollTrigger 的 scrub 已经能提供人们通常所说的“平滑”的缓动电影感效果。
参见 references/08-failure-modes.md §1。
→ 阅读 references/07-stack-setup.md 了解脚手架和确切命令。
自 v3.13(Webflow 收购)起 GSAP 100% 免费,包括 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,放在时间线上 — 绝不要放在子补间(child tween)上,绝不要嵌套在父时间线内部。
- 如果——并且仅当——你添加了 Lenis,让它与 GSAP 共享循环。
lenis.on('scroll', ScrollTrigger.update)+gsap.ticker.add(t => lenis.raf(t * 1000))+gsap.ticker.lagSmoothing(0)。 绝不要为 Lenis 添加单独的requestAnimationFrame循环。 ease: "none"用于驱动containerAnimation或媒体同步(media scrub)的任何补间。scrub或toggleActions,两者不可兼用 在同一触发器上。- 在字体和图片加载后调用
ScrollTrigger.refresh()— 不仅是调整大小时。 - 在任何钉固(pin)之前,遍历祖先元素检查
transform/filter/contain。 任何其中之一都会静默地破坏position: fixed,因此钉固被创建,报告pin: true,但什么也不做。移除该属性或设置pinType: 'transform'。参见08-failure-modes.md§2。
仅对 transform 和 opacity 进行动画。任何在滚动时触及 top、left、width、height 或 margin 的操作都会掉帧。
阶段 6 — 验证
此阶段不可省略,并且正是该技能与手动编写 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。合成滚动会被滚动劫持库吞掉,而这正是你需要捕捉的失败。如果三次滚轮拨动没有移动页面,那么无论断言怎么说,它都是坏的。
如果以下任何一个条件为真,则标记为失败并修复:
- 控制台错误,或任何
ScrollTrigger警告 - 任何 404,或总资产大小超出预算
- 在任何深度出现空白/无样式的截屏
- 钉固章节与下一章节重叠,或导致布局折叠
- 始终不可见的内容(从未触发的出现动画)
- 宽度 390px 时水平溢出
- 源代码中任何地方保留
markers: true - 没有
prefers-reduced-motion回退 - 三次真实滚轮拨动未在视觉上移动页面
- 钉固的舞台仍然跟随滚动(在范围内断言
|rect.top| < 10) - 同步媒体在其钉固的 ~90% 之前到达结束
- 需要超过 ~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 以下更倾向于淡入
- ❌ 超出英雄序列的资产预算