关于 motion-authoring
motion-authoring 是面向开发者的技能,用于为转换后的网页项目添加经测量的动效。它将动效证据转为实现代码,区分测量数据与手动编写内容,并通过构建及响应式检查。
主要功能
- 01选择页面级或版块级触发方式
- 02将生成的动效清单作为证据
- 03编写页面与版块动画
- 04避免重复加载 GSAP 运行时
- 05验证桌面与移动端构建
适用场景
- 01为转换后的网页复刻添加动效
- 02实现经测量的页面级滚动叙事
- 03检查手写动画的减少动态效果模式
MCP 相关
该技能使用 Awwwards MCP 工具检查页面结构和滚动行为,并生成供动效编写使用的清单。
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ insane0777/ awwwards-skills --skill motion-authoring安装后在 Claude Code 中输入/motion-authoring确认已加载。
附带文件LICENSEv2-routing.md
详细介绍
动效编写——从测量清单到真实动效
仅当用户选择了已转换的项目并且编写了动效时才会运行。
生成器会提供结构、惰性骨架挂载点和
motion.manifest.json(测量触发器、pageTriggers、初始隐藏
提示)。编写动效这一步会让这些挂载点产生真实动效,并通过参考页面验证
构建结果。这是 N2 dogfood 配方
(nesil:一个 31.21 s 的主 scrub,精确匹配 25,650 px)。
**配置说明:**此技能的工具为
analyze_page_structure、analyze_scroll_map、build_motion_manifest和保留的build_project。 以下示例使用 1.x 名称(默认值为full)。在AWWWARDS_MCP_PROFILE=v2时,请使用inspect_page {request:{kind:"structure", url}}、analyze_motion {request:{kind:"scroll", url, compact:false}}和build_motion {request:{kind:"manifest", bands, scrollCensus}};build_project保持扁平结构。普查结果必须为compact:false——紧凑型 普查结果没有anims[],无法传入build_motion。完整映射: v2-routing.md。
0. 阅读参考页面,而不只是普查结果
普查结果会告诉你什么在动,以及大致的动效时机;其中的选择器是
结构路径,不是你的 id/class。有条件时,请阅读网站自身的动效脚本,并将
普查结果视为佐证:实际触发器数量、固定定位、scrub 比例、持续时间、缓动
类型、错开延迟,以及哪些动画使用 CSS 关键帧、GSAP 或原生滚动时间线。
使用 anims[] 验证覆盖范围——切勿据此推导时间线。
1. 编写代码前先确定拓扑结构
只需回答一个问题:使用一个主时间线,还是独立的分节触发器?
- 一个主 scrub(高大的占位区、固定舞台、单个 scrub 触发器)→
编写页面级
journey模块,其中包含一条带标签的时间线;分节 模块改为向其中添加内容的轻量构建器。切勿拆分成七个独立的 ScrollTrigger——这会改变重叠和衔接。 - 独立的分节触发器 → 每个分节模块各有一条时间线,以清单中的
triggers[]为键;骨架已经具备相应结构 (gsap.context、测量常量、刷新)。
start: null 的行属于 CSS 关键帧或未归属行——它们用于说明来源,并不
表示要为每一行都构建时间线。
2. 清单约定
motion.manifest.json 是证据,不是动效编写文件:
- 按生成结果使用;切勿手动添加行或切换
measured - 原样记录计数(
sections、sectionTriggers、pageTriggers) - 分别记录编写的代码(文件 + 前后状态),并确保交付的
清单哈希与新生成的哈希一致;如果必须添加行,请标记为已编写并注明——切勿使用
measured: true pageTriggers属于页面级模块,而非某个分节- 尚未构建?
build_motion_manifest({ bands, scrollCensus, sections? })会直接根据analyze_page_structure+analyze_scroll_map(以及可选的{label, selector?}覆盖项)搭建此清单结构。其 封套中的measured: false,且 DOM 初始状态提示为空(没有 标记),因此请根据普查触发器编写动效,并按下文记录编写的代码——切勿手动 将脚手架切换为measured: true。
3. 意图映射(移植什么,跳过什么)
| 意图 | 移植 | 跳过 |
|---|---|---|
| 加载器简介 | 网站时间线中的主视觉序列(名称、光标移动、盖子、提示语、角色、面容) | 分析、加载动画 |
| 主旅程 | 一条可拖动的时间线、各分区的 set 时间、--bg 补间动画、带标签的分区 | 无关脚本 |
| Canvas/粒子 | Canvas 尺寸与舞台一致、限制 DPR、限定数量、速度推动、清理 | 未使用的粒子/WebGL 库 |
| 光标 | 空闲补间动画、简介交接、结束状态交接 | 替换操作系统光标 |
| 音频 | 循环播放元素、音量渐变、切换、visibilitychange 时暂停 | 自动播放断言 |
| 标尺/进度 | 每个标签一个控件,播放头位置 = 进度 | 自定义滚动条 |
| 文案/表单 | 剪贴板 + 回退方案、重置状态 | 页面未提供的服务端行为 |
| 减少动态效果 | 页面头部初始化 + CSS 类;编写的代码在 GSAP 前返回 | 无人要求的“轻量”变体 |
4. 目标环境(不要重复加载 GSAP)
| 目标 | 环境 | 规则 |
|---|---|---|
| Next | 通过 SiteScripts 引入供应商全局变量(位于 MotionRoot 之前),以及编写的 hooks/模块 | 编写的代码中不要 import gsap;有限等待 window.gsap/ScrollTrigger |
| Vite | 将保留的经典标签中的 window.gsap/ScrollTrigger/Lenis 复制到 dist/src/scripts | 不要 import gsap |
| Astro | 相同的全局变量,使用 is:inline 供应商标签;先运行页面脚本,再运行各分区脚本 | 不要 import gsap |
生成的骨架会导入 npm gsap;改用保留的全局变量可以避免出现两份副本。可以保留未使用的 gsap 依赖——无害,不要导入。
5. 编写顺序
先处理页面级内容(加载器 → 旅程 → 光标 → 音频 → 标尺),再处理拥有独立触发器的分区。与分区循环一样,保持相同的锁定流程:编写一个分区,重新运行该分区的门禁检查(捕获几何信息 + 截图 + 明确检查),锁定后再处理下一个。verify_build 提供的是整页汇总证据,而非单个分区的评分。
6. 验证门禁(必须全部通过)
- 每个目标都能构建(
vite build、astro build、next build+ 启动探测)。 - 桌面端 1440×900,在各个带状锚点(8 个停靠点)处:scrollHeight 差异不超过 ±1 %,可见分区 ID、字体一致,控制台/页面错误和 404 均为 0。
- 移动端 390×844 冒烟测试:无水平溢出,锚点/可见分区一致,错误为 0。
- 减少动态效果:应用页面头部类,禁用固定舞台,无溢出,页面可读。
- 编写代码的证明:源代码和构建目录中均不含已移除的网站脚本引用;仅保留指定的供应商库;
SiteScripts位于MotionRoot之前。
故障模式
| 症状 | 原因 | 修复 |
|---|---|---|
| 编写后页面无响应 | 编写的代码在库加载前启动 | 等待全局变量/确保 SiteScripts 位于最前 |
| 出现两套 GSAP 运行时/缓动异常 | npm 导入 + 供应商全局变量 | 仅使用保留的全局变量 |
| 交接效果发生变化 | 主时间线拆分为各分区触发器 | 使用单条页面级旅程,由各分区切分 |
| 清单显示“已测量”但结果错误 | 直接编辑手动填写的行 | 重新生成,或明确标记人工编写的行 |
| 动效正常,移动端页面损坏 | 仅针对桌面端编写 | 每次迭代都运行 390 冒烟测试 |