fixing-motion-performance

fixing-motion-performance

何时使用

当你需要审计并修复动画性能问题时使用此技能，包括布局抖动、合成器属性、滚动联动动效和模糊效果。适用于动画卡顿、过渡不流畅，或审查 CSS/JS 动画性能的场景。

修复动画性能问题。

如何使用

• /fixing-motion-performance 将以下约束应用于本次对话中的任何 UI 动画工作。

• /fixing-motion-performance <file> 根据以下所有规则审查该文件并报告：

  • 违规项（引用确切的代码行或片段）
  • 为什么重要（一句简短说明）
  • 具体的修复方案（代码级建议）

除非明确要求，否则不要迁移动画库。在现有技术栈内应用规则。

何时应用

在以下情况参考这些准则：

• 添加或更改 UI 动画（CSS、WAAPI、Motion、rAF、GSAP）
• 重构卡顿的交互或过渡
• 实现滚动联动动效或滚动显现
• 为布局、滤镜、遮罩、渐变或 CSS 变量添加动画
• 审查使用 will-change、transforms 或测量的组件

渲染步骤术语

• 合成：transform、opacity
• 绘制：color、borders、gradients、masks、images、filters
• 布局：size、position、flow、grid、flex

按优先级划分的规则类别

优先级	类别	影响
1	禁止模式	严重
2	选择机制	严重
3	测量	高
4	滚动	高
5	绘制	中高
6	图层	中
7	模糊与滤镜	中
8	视图过渡	低
9	工具边界	严重

快速参考

1. 禁止模式（严重）

• 不要在同一帧内交错进行布局读取和写入
• 不要在大型或重要表面上持续对布局添加动画
• 不要通过 scrollTop、scrollY 或滚动事件驱动动画
• 不允许没有停止条件的 requestAnimationFrame 循环
• 不要混用多个各自测量或修改布局的动画系统

2. 选择机制（严重）

• 动效默认使用 transform 和 opacity
• 仅在交互需要时使用 JS 驱动的动画
• 绘制或布局动画仅可在小型、隔离的表面上使用
• 一次性效果比持续动效更常被接受
• 宁可降级技术方案，也不要完全移除动效

3. 测量（高）

• 测量一次，然后通过 transform 或 opacity 添加动画
• 在写入之前批量执行所有 DOM 读取
• 不要在动画期间反复读取布局
• 对于类布局效果，优先使用 FLIP 风格的过渡
• 优先选择批量测量和写入的方法

4. 滚动（高）

• 在可用时，优先使用 Scroll 或 View Timelines 实现滚动联动动效
• 使用 IntersectionObserver 处理可见性和暂停
• 不要轮询滚动位置来驱动动画
• 在屏幕外时暂停或停止动画
• 滚动联动动效不得在大型表面上触发持续的布局或绘制

5. 绘制（中高）

• 触发绘制的动画仅允许用于小型、隔离的元素
• 不要在大型容器上为绘制开销大的属性添加动画
• 不要为 transform、opacity 或 position 相关的 CSS 变量添加动画
• 不要为继承的 CSS 变量添加动画
• 将动画使用的 CSS 变量限定在局部作用域，避免继承

6. 图层（中）

• 合成器动效需要图层提升，切勿臆断其已发生
• 临时且精准地使用 will-change
• 避免过多或过大的提升图层
• 当性能至关重要时，使用工具验证图层行为

7. 模糊与滤镜（中）

• 保持模糊动画幅度小（<=8px）
• 模糊仅用于短暂的一次性效果
• 绝不要持续为模糊添加动画
• 绝不要在大型表面上为模糊添加动画
• 优先使用 opacity 和 translate，而非 blur

8. view transitions（低）

• 仅在导航级变更中使用 view transitions
• 对于交互密集的 UI，避免使用 view transitions
• 当需要中断或取消时，避免使用 view transitions
• 将尺寸变化视为可能触发布局

9. tool boundaries（关键）

• 除非明确要求，否则不要迁移或重写动画库
• 在现有动画系统内应用这些规则
• 绝不在同一组件内部分迁移 API 或混用样式

常见修复

/* layout thrashing: animate transform instead of width */
/* before */ .panel { transition: width 0.3s; }
/* after */  .panel { transition: transform 0.3s; }

/* scroll-linked: use scroll-timeline instead of JS */
/* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500)
/* after */  .reveal { animation: fade-in linear; animation-timeline: view(); }

// measurement: batch reads before writes (FLIP)
// before — layout thrash
el.style.left = el.getBoundingClientRect().left + 10 + 'px';
// after — measure once, animate via transform
const first = el.getBoundingClientRect();
el.classList.add('moved');
const last = el.getBoundingClientRect();
el.style.transform = `translateX(${first.left - last.left}px)`;
requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; });

审查指导

• 首先执行关键规则（never patterns、tool boundaries）
• 选择与意图匹配的成本最低的渲染工作
• 对于任何非默认选择，说明其合理约束（表面尺寸、持续时间或交互要求）
• 审查时，优先给出可操作的说明和具体替代方案，而非理论

限制

• 仅当任务明确匹配其上游来源和本地项目上下文时，才使用此 skill。
• 在应用更改之前，验证命令、生成的代码、依赖项、凭据以及外部服务行为。
• 不要将示例视为环境特定测试、安全审查或针对破坏性或高成本操作的用户批准的替代品。