Communitygithub.com

hemangjoshi37a/scroll_animated_webpages_skill

构建端到端的获奖级滚动动画网站。通过发现向导(人物/产品/公司/活动/事业)收集需求,编译滚动评分蓝图,生成项目骨架,实现 GSAP ScrollTrigger 动画(可选 Lenis 平滑滚动),然后用 Playwright MCP 在真实浏览器中验证并修复问题。

scroll_animated_webpages_skill 是什么?

该技能提供了一个完整的滚动驱动网站构建流水线,包含六个阶段:发现(交互式向导)、评分(蓝图生成)、资产收集、项目搭建、构建与验证。它专门用于创建类似 Apple 产品页面的滚动动画、视差效果、图片序列滚动等高端展示型网站。 技能的核心优势在于其验证驱动的方法:使用 Playwright MCP 在真实浏览器中驱动页面滚动、截屏并检查视觉正确性,而非仅依赖代码审查。它绕过框架生命周期问题(默认使用 Vite + vanilla TS + GSAP),并提供了详尽的失败模式参考文档(如钉固折叠、滚动劫持等)。 该技能支持多种项目管理平台(Claude Code、Cursor、Codex 等),但描述中强调其可在任何支持 MCP 协议的环境中运行。它包含一个由 12 种预置动画模式组成的模式库(如出现动画、文字揭示、水平滚动、贴片堆叠等),以及严格的 GSAP 编码规则和资产预算约束。

兼容平台~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 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 调用以及权重预算。

三个来源,按优先级排列:

  1. 用户提供 — 始终优先。在向导中索取,之后不要。
  2. 生成 — mcp__image-gen-mcp__generate_image(gpt-image-2,产品使用 background: "transparent",最大 3840x2160),或 edit_image 将真实产品照片转换为风格化渲染。
  3. 占位符 — 仅用于用户明确延后的拍节,且必须是有考虑的渐变/文字组合,绝不能是灰色方块。

对于图片序列英雄区(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-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,放在时间线上 — 绝不要放在子补间(child tween)上,绝不要嵌套在父时间线内部。
  2. 如果——并且仅当——你添加了 Lenis,让它与 GSAP 共享循环。 lenis.on('scroll', ScrollTrigger.update) + gsap.ticker.add(t => lenis.raf(t * 1000)) + gsap.ticker.lagSmoothing(0)。 绝不要为 Lenis 添加单独的 requestAnimationFrame 循环。
  3. ease: "none" 用于驱动 containerAnimation 或媒体同步(media scrub)的任何补间。
  4. scrub 或 toggleActions,两者不可兼用 在同一触发器上。
  5. 在字体和图片加载后调用 ScrollTrigger.refresh() — 不仅是调整大小时。
  6. 在任何钉固(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 以下更倾向于淡入
  • ❌ 超出英雄序列的资产预算

相关技能