animations

动画

制作或审查网页动画，使其达到 60 fps（高刷新率显示屏上达到 120 fps），尊重用户的动态效果偏好，并为任务选择成本最低的工具——优先使用 CSS；需要运行时控制时使用 Web Animations API；需要弹簧物理效果、手势或共享布局动画时使用 Motion；渲染模型本身需要呈现三维效果时使用 React Three Fiber。

此 SKILL.md 是一个简要索引。 详细规则位于 rules/*.md，并按需加载。实践示例位于 references/recipes.md。可直接使用的 HTML/CSS 代码片段位于 templates/。

仅限 Web。 此技能涉及的机制适用于 Web（CSS、Motion、View Transitions、Web Animations API）。对于 React Native / Expo 动效 （Reanimated、gesture-handler、Moti、Lottie、Rive），请改用 animations-native 技能——它会重用此技能中与平台无关的 头脑风暴 / 动词→动效目录。

---

核心原则

只为 transform、opacity 和 filter 添加动画。 浏览器可以在 GPU 上合成这三个属性，而不会在主线程上触发布局或绘制。其他任何属性（width、height、top、left、margin、padding、box-shadow 等）都会触发布局或绘制，导致卡顿。完整列表见 rules/safe-properties.md。

对于那些看似无法添加动画的属性——height: auto、display: none、列表重排、路由切换——现代 CSS 提供了可将其转换为 GPU 工作的原生机制。参见 rules/modern-css.md。

---

头脑风暴模式——交互 → 反馈

当用户询问动画应该是什么样，而非如何构建时，请从此入口开始。以下问题应转到这里，而非下方的技术决策流程：

• “按下这个按钮时，理想的反馈是什么？”
• “关闭卡片时应该是什么感觉？”
• “切换这个选项时，自然的动画应该是什么样？”
• “用户删除一行时应该发生什么？”

步骤：

1. 进行五问头脑风暴，见 rules/interaction-feedback.md ——动词、可逆性、发起者、空间来源、可供性负担。 在选择建议前，逐项用一行回答。
2. 在同一文件的目录中查找对应交互。 目录涵盖离散操作（按按钮、切换、复制）、 元素生命周期（卡片打开 / 关闭、模态框、抽屉、列表添加 / 移除）、状态（加载、成功、错误、骨架屏）、 连续手势（拖动、滑动、捏合、下拉刷新）以及导航（标签页、路由、手风琴、向导）。每一行都给出 推荐动效、时长范围、缓动方式、动画属性以及选择背后的原则。
3. 选择强度级别（1——微交互，至 5——主视觉效果）。经验法则：强度级别比场景重要性高出两级，会显得设计过度。
4. 遵循方向原则——运动向量必须反映交互的语义动词（打开时从触发点缩放；关闭时反向播放打开效果；删除时移向远离方向；选择时移向靠近方向）。
5. 转交给下方的技术工作流——头脑风暴确定是什么（例如“缩放 + 透明度，240 ms，以锚点为原点”）；工作流确定如何实现（使用哪个属性、哪个 API、通过哪道检查）。

完整目录和头脑风暴框架见 rules/interaction-feedback.md。

---

决策流程

按顺序逐项检查。第一个匹配项优先。

#	信号	工具
1	悬停、聚焦或切换类时的一次性状态变化	CSS transition
2	首次绘制时淡入（模态框、弹出层、对话框）	@starting-style + transition-behavior: allow-discrete (rules/modern-css.md)
3	循环或按顺序播放的声明式关键帧	CSS @keyframes + animation
4	与滚动位置或元素进入视口相关的动画	animation-timeline: scroll() / view() (rules/modern-css.md)
5	同一页面中的 DOM 替换、列表重排，或带交叉淡入淡出的 SPA / MPA 路由切换	View Transitions API (rules/modern-css.md)
6	手风琴 / 展开折叠至 height: auto	interpolate-size: allow-keywords（Chromium）或 Motion layout（通用）
7	状态编排 — 列表 → 卡片、完整导航栏 → 仅图标导航栏、网格 → 详情视图、标签页胶囊	Motion layout / layoutId (rules/state-choreography.md)
8	弹簧物理效果、手势（拖动 / 平移 / 捏合）、声明式变体	Motion (rules/when-to-use-js.md)
9	需要 pause / reverse / scrub 的一次性编程动画	Web Animations API（element.animate）
10	3D 渲染、WebGL、粒子、着色器、与滚动关联的 3D 场景	React Three Fiber + Drei (rules/three-d.md)
11	设计师制作的素材（线性播放）— 加载器、插画、微动画	Lottie / dotLottie (rules/external-engines.md)
12	设计师制作的交互式素材 — 动画图标、角色、多状态按钮	Rive (rules/external-engines.md)

如果有两行匹配，选择编号较小的一行——它的依赖更少。**GSAP 和其他仅使用 requestAnimationFrame 的库不在此决策流程中：**Motion 的混合引擎能够覆盖相同场景，包体积更小，并且在动画仅涉及合成时会在合成器上运行。

---

工作流

对于任何动画任务——创作或审查——都按以下阶段进行：

阶段	名称	规则文件	门槛
A	集思广益反馈（当输入是“什么？”时）	rules/interaction-feedback.md	如果用户描述的是一种交互（动词），则在进入阶段 0 前，先回答五个集思广益问题并选定目录条目。如果用户描述的是动画基本效果（例如“淡入”），则跳过阶段 A。
B	管理感知性能（存在等待时）	rules/perceived-performance.md	如果动画包含异步等待——获取数据、路由更改、路由加载、图像解码、乐观更新——则查阅等待时长阶梯（以 p75 测量，而非本地开发时“感觉很快”），选择合适的模式（不显示加载器、骨架屏、加载旋转图标、进度条或异步退出），确保加载器至少显示 200 ms、低于 200 ms 时跳过，并让骨架屏与最终内容的形状一致。如果没有等待，则跳过阶段 B。
0	选择属性	rules/safe-properties.md	动画属性为 transform、opacity 或 filter。否则，需通过布局抖动测量进行论证。
1	选择模式	rules/patterns.md	模式（淡入、错开、滑动、缩放）与用户信号相符。
2	优先使用现代 CSS	rules/modern-css.md	如果需求是“从隐藏状态进入”“自动高度”“DOM 替换”或“与滚动联动”，则存在仅使用 CSS 的方案。
3	接入交互性	rules/interactive-effects.md	如果指针／滚动／传感器驱动某个值，则通过 CSS 变量传递该值；对于有类型的插值，考虑使用 @property。
4	设置时长	rules/timing-easing.md	UI 动画时长在 150–500 ms 范围内；缓动需使用具名曲线，而非 linear（除非有意为之）。
5	决定使用 CSS、JS 还是 3D	rules/when-to-use-js.md、rules/three-d.md	遵循上述决策流程；Motion / R3F 为按需选择，而非默认选项。
5.5	编排状态变形	rules/state-choreography.md	先运行规划检查清单；所选工具（Motion layout、layoutId 或 View Transitions）须与目录中记录的变更集相符。切勿直接对布局属性添加动画。
5.6	接入 React 状态	rules/react-state.md	确定状态位置（组件／提升状态／URL／上下文）；将 60 fps 的值保存在 refs 或 useMotionValue 中；选择 AnimatePresence 模式；遵守 Strict Mode 和 Server Component 边界。
5.7	添加高级效果	rules/advanced-effects.md	如果设计需要玻璃效果、发光、悬停展开、极光或 3D 倾斜，则使用开销较低的模式（伪元素 + opacity，而非对 box-shadow / backdrop-filter 添加动画）；确保提供 prefers-contrast 和 prefers-reduced-motion 的后备方案。
5.8	外部引擎	rules/external-engines.md	如果资源由设计师制作（Lottie / dotLottie 或 Rive），则延迟加载运行时、在屏幕外时暂停，并根据 prefers-reduced-motion 控制运行，同时提供静态海报后备方案。
6	尊重动态偏好	rules/accessibility.md	存在 @media (prefers-reduced-motion: reduce) 代码块并已完成测试。对于状态变形，请参阅 rules/state-choreography.md 中专门的无障碍部分。
7	测量	rules/debugging.md	动画在 DevTools Performance 中达到 60 fps；帧期间没有紫色 Layout／绿色 Paint 条。
7.5	记录证据（可选）	screencast 技能	对于非简单动画（View Transitions、Motion layout、滚动时间线、状态编排变形），或用户提出“给我看看”时，调用 Skill("screencast") 两次——一次使用 "reducedMotion": false，一次使用 true——并传入 rules/record-and-iterate.md § Recording inputs 中的 recording.json（将 crop 设为动画元素，并将 maxWidth: 768）。如果未安装该技能，则跳过，并用一行报告说明（screencast — skipped (not installed)）。
7.6	分析并迭代	video-analyser 技能	将阶段 7.5 的录制内容输入 Skill("video-analyser")，以端到端验证动画约定。分析器会返回结构化发现（错误、关键帧中的 UI 状态、建议的后续步骤）。如果发现与动画约定相矛盾（卡顿、缺少减少动态效果的分支、焦点环丢失、意外的布局闪烁），则应用修复并返回阶段 7.5。循环最多进行 3 次——第 4 次时通过 Skill("confidence", analysis) 升级处理。完整的录制 → 分析 → 迭代流程：rules/record-and-iterate.md。如果未安装 video-analyser，则跳过，并用一行报告说明（video-analyser — skipped (not installed)）。

---

各阶段必读内容

按需加载——不要预加载。

阶段	文件
A	rules/interaction-feedback.md
B	rules/perceived-performance.md
0	rules/safe-properties.md
1	rules/patterns.md
2	rules/modern-css.md
3	rules/interactive-effects.md, templates/cursor-spotlight.html
4	rules/timing-easing.md
5	rules/when-to-use-js.md, rules/three-d.md
5.5	rules/state-choreography.md
5.6	rules/react-state.md
5.7	rules/advanced-effects.md
5.8	rules/external-engines.md
6	rules/accessibility.md
7	rules/debugging.md
7.5/7.6	rules/record-and-iterate.md
—	references/recipes.md（完整示例——当用户询问“X 从头到尾是什么样？”时加载）

---

核心原则

1. 仅限合成属性。 transform 和 opacity 会映射到 GPU 合成。 其他一切都会消耗帧。
2. will-change 是手术刀。 在动画开始前才应用， 结束后立即移除；绝不用于空闲元素；同时应用的节点不得超过 少数几个。
3. 变量流动，类切换。 每次指针移动或每帧的值 放在 CSS 自定义属性中；生命周期状态放在类中。
4. @property 让动画成为可能。 未注册的自定义属性 会离散动画（跳变）。已注册的属性则会平滑插值。
5. 优先使用平台能力。 @starting-style、interpolate-size、 View Transitions 和滚动驱动时间轴，已经取代了大多数过去需要 Motion 或手写 rAF 循环才能实现的 JS 技巧。只有平台无法表达 所需动画时，才使用库。
6. 减少动效，而非移除动效。 当设置了 prefers-reduced-motion: reduce 时， 用淡入淡出或近乎即时的状态变化替代动效，绝不要完全去掉反馈。
7. 优化前先测量。 感知到的卡顿可能是 200 ms 的图像 解码，而非动画本身。打开 Performance，录制一段，然后先查看 帧图表，再调整。
8. 先构思，再选择。 当问题是「这个交互应该提供什么反馈？」时， 先按照 interaction-feedback.md 中的五个问题进行构思—— 动作、可逆性、发起者、空间来源和显著性负担。跳过思考，直接问「淡入还是滑动？」 会失去让选择有理有据的推理过程。
9. 无法缩短等待时，就让用户感觉更快。 真实延迟受物理规律限制；感知延迟取决于设计。在 100 ms 内响应输入（Doherty 阈值），在答案到达前先绘制其轮廓（骨架屏应与最终布局匹配）， 乐观地应用可逆变更，为不足 200 ms 的加载器设定最短显示时间 （或完全跳过），并在用户表达意图时预取。相同的 1.2 s 请求，会因等待期间发生的事情不同，而显得迅捷或失灵。参见 rules/perceived-performance.md。

---

反模式（一句话概述——完整列表见链接中的规则）

• 为 width、height、top、left、margin 或 padding 添加动画 （safe-properties.md）。
• 在主视觉元素上永久保留 will-change: transform （safe-properties.md）。
• 使用 transition: all——每次属性变化都会产生开销，还会意外触发 布局属性动画。
• 在 UI 动效中使用 linear 缓动——看起来像机器人；改用 ease-out 或命名的 cubic-bezier （timing-easing.md）。
• 为未注册的自定义属性添加动画，却惊讶地发现它会直接跳变，而非插值 （interactive-effects.md）。
• 还没尝试 CSS、View Transitions 或 Web Animations API，就急着引入一个 25 KB 的库 （when-to-use-js.md）。
• 在新代码中从 framer-motion 导入——该包已无人维护。改用 motion。
• 将 60 fps 状态放在 React useState 中，尤其是在 R3F 内 （three-d.md）。
• 忘记 prefers-reduced-motion，给用户带来前庭系统伤害 （accessibility.md）。
• 还没回答五个头脑风暴问题，就先决定动画形态（interaction-feedback.md）—— 最终可能需要滑动却用了淡入淡出，需要曲线却用了弹簧，或是在开关上用了主视觉级动效。
• 非对称的打开/关闭动画采用不同的形态（模态框打开时缩放，关闭时滑动）——选定一种形态，反向播放，并让退出动画快约 30%。
• 快速网络下，加载指示器闪现不到 200 ms——看起来像故障，而非速度快。使用 perceived-performance.md 中的加载时长下限和低于 200 ms 时跳过的方案。
• 骨架屏的形态与最终内容不匹配（例如用三条文本栏占位卡片网格）——替换时会导致布局偏移，看起来像页面重新加载 （perceived-performance.md）。
• 乐观 UI 没有回滚动画——点击时状态立即变化，服务器拒绝后却静默跳回，用户会以为是自己的问题 （perceived-performance.md）。
• 原子式图片加载没有主色或 blurhash 占位符——先显示空白框，再突然显示完整图片并导致布局偏移 （perceived-performance.md）。

---

配合使用

• /visual-design — 动效个性是品牌信号（野蛮主义的强力按压 vs 柔和 UI 的轻柔抬起），缓动和时长的选择应融入选定的风格方向。从头设计新组件的动效时，先运行 /visual-design 确定方向，再回到这里处理实现细节。审查感觉不对劲的动效时，判断问题是实现层面（卡顿、GPU、缓动曲线——本技能），还是品牌特征层面（动效类型不符合品牌——/visual-design/rules/signature-details.md 介绍了作为品牌特征动作的悬停、按压和焦点效果）。
• /ux — prefers-reduced-motion、过渡期间的 focus-visible，以及由动效触发的前庭系统问题，都是由 /ux/rules/accessibility.md 负责的无障碍底线检查。
• /screencast — 多帧交互无法通过静态画面证明。对于任何依赖时序的严重或高优先级问题，都应调用它。

完成标准

• 动画属性为 transform、opacity 或 filter，或者是驱动其中一个属性的 @property 注册自定义属性。
• 空闲元素上没有遗留 will-change。
• 缓动方式和时长符合用途（UI 动效为 150–500 ms，使用命名缓动曲线；为实现不对称效果，进入动画可以与退出动画有所不同）。
• 如果涉及 JavaScript，使用的库必须是 Motion（不能是 framer-motion 或 GSAP），或者完全不使用库。
• @media (prefers-reduced-motion: reduce) 会将动效减弱为淡入淡出或即时状态变化。
• DevTools Performance 显示动画线程运行在合成器上（Compositor 行有活动，动画帧期间没有紫色 Layout 或绿色 Paint 条）。
• 动画不会影响键盘焦点和屏幕阅读器的行为。