Back to Details

fixing-motion-performance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

fixing-motion-performance

修复动画性能问题

Fix animation performance issues.
修复动画性能问题。

how to use

使用方法

  • /fixing-motion-performance
    Apply these constraints to any UI animation work in this conversation.
  • /fixing-motion-performance <file>
    Review the file against all rules below and report:
    • violations (quote the exact line or snippet)
    • why it matters (one short sentence)
    • a concrete fix (code-level suggestion)
Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack.
  • /fixing-motion-performance
    将这些约束应用于本次对话中的所有UI动画工作。
  • /fixing-motion-performance <file>
    根据以下所有规则审查文件并报告：
    • 违规情况（引用确切行或代码片段）
    • 影响原因（一句话简述）
    • 具体修复方案（代码层面的建议）
除非明确要求，否则不要迁移动画库。在现有技术栈内应用规则。

when to apply

适用场景

Reference these guidelines when:
  • adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP)
  • refactoring janky interactions or transitions
  • implementing scroll-linked motion or reveal-on-scroll
  • animating layout, filters, masks, gradients, or CSS variables
  • reviewing components that use will-change, transforms, or measurement
在以下场景中参考这些指南：
  • 添加或修改UI动画（CSS、WAAPI、Motion、rAF、GSAP）
  • 重构卡顿的交互或过渡效果
  • 实现滚动关联动画或滚动显示效果
  • 对布局、滤镜、遮罩、渐变或CSS变量执行动画
  • 审查使用will-change、transform或尺寸测量的组件

rendering steps glossary

渲染步骤术语表

  • composite: transform, opacity
  • paint: color, borders, gradients, masks, images, filters
  • layout: size, position, flow, grid, flex
  • composite（合成）：transform、opacity
  • paint（绘制）：颜色、边框、渐变、遮罩、图片、滤镜
  • layout（布局）：尺寸、位置、流布局、网格、弹性布局

rule categories by priority

按优先级划分的规则类别

prioritycategoryimpact
1never patternscritical
2choose the mechanismcritical
3measurementhigh
4scrollhigh
5paintmedium-high
6layersmedium
7blur and filtersmedium
8view transitionslow
9tool boundariescritical
优先级类别影响程度
1禁止模式严重
2选择合适机制严重
3尺寸测量高
4滚动相关高
5绘制相关中高
6图层相关中
7模糊与滤镜中
8视图过渡低
9工具边界严重

quick reference

快速参考

1. never patterns (critical)

1. 禁止模式（严重）

  • do not interleave layout reads and writes in the same frame
  • do not animate layout continuously on large or meaningful surfaces
  • do not drive animation from scrollTop, scrollY, or scroll events
  • no requestAnimationFrame loops without a stop condition
  • do not mix multiple animation systems that each measure or mutate layout
  • 不要在同一帧中交替进行布局读取和写入
  • 不要在大型或重要界面上持续对布局执行动画
  • 不要通过scrollTop、scrollY或scroll事件驱动动画
  • 不要使用无停止条件的requestAnimationFrame循环
  • 不要混合使用多个会测量或修改布局的动画系统

2. choose the mechanism (critical)

2. 选择合适机制（严重）

  • default to transform and opacity for motion
  • use JS-driven animation only when interaction requires it
  • paint or layout animation is acceptable only on small, isolated surfaces
  • one-shot effects are acceptable more often than continuous motion
  • prefer downgrading technique over removing motion entirely
  • 优先使用transform和opacity实现动画
  • 仅当交互需要时才使用JS驱动的动画
  • 仅在小型、独立的界面元素上允许对绘制或布局执行动画
  • 一次性效果比持续动画更易被接受
  • 优先降级实现技术，而非完全移除动画

3. measurement (high)

3. 尺寸测量（高）

  • measure once, then animate via transform or opacity
  • batch all DOM reads before writes
  • do not read layout repeatedly during an animation
  • prefer FLIP-style transitions for layout-like effects
  • prefer approaches that batch measurement and writes
  • 仅测量一次，然后通过transform或opacity执行动画
  • 在写入前批量处理所有DOM读取操作
  • 不要在动画期间重复读取布局信息
  • 优先使用FLIP风格的过渡实现类布局效果
  • 优先选择可批量处理测量与写入的方案

4. scroll (high)

4. 滚动相关（高）

  • prefer Scroll or View Timelines for scroll-linked motion when available
  • use IntersectionObserver for visibility and pausing
  • do not poll scroll position for animation
  • pause or stop animations when off-screen
  • scroll-linked motion must not trigger continuous layout or paint on large surfaces
  • 若支持，优先使用Scroll或View Timelines实现滚动关联动画
  • 使用IntersectionObserver检测可见性并暂停动画
  • 不要轮询滚动位置来驱动动画
  • 当元素离开屏幕时暂停或停止动画
  • 滚动关联动画不得在大型界面上触发持续的布局或绘制操作

5. paint (medium-high)

5. 绘制相关（中高）

  • paint-triggering animation is allowed only on small, isolated elements
  • do not animate paint-heavy properties on large containers
  • do not animate CSS variables for transform, opacity, or position
  • do not animate inherited CSS variables
  • scope animated CSS variables locally and avoid inheritance
  • 仅允许在小型、独立的元素上执行触发绘制的动画
  • 不要在大型容器上对绘制密集型属性执行动画
  • 不要对用于transform、opacity或位置的CSS变量执行动画
  • 不要对继承的CSS变量执行动画
  • 将带动画的CSS变量限定在局部作用域，避免继承

6. layers (medium)

6. 图层相关（中）

  • compositor motion requires layer promotion, never assume it
  • use will-change temporarily and surgically
  • avoid many or large promoted layers
  • validate layer behavior with tooling when performance matters
  • 合成器动画需要提升图层，切勿默认假设已提升
  • 临时且精准地使用will-change
  • 避免过多或过大的提升图层
  • 当性能至关重要时，使用工具验证图层行为

7. blur and filters (medium)

7. 模糊与滤镜（中）

  • keep blur animation small (<=8px)
  • use blur only for short, one-time effects
  • never animate blur continuously
  • never animate blur on large surfaces
  • prefer opacity and translate before blur
  • 保持模糊动画的幅度较小（<=8px）
  • 仅在短暂的一次性效果中使用模糊
  • 不要持续对模糊执行动画
  • 不要在大型界面上对模糊执行动画
  • 优先使用opacity和translate，而非模糊

8. view transitions (low)

8. 视图过渡（低）

  • use view transitions only for navigation-level changes
  • avoid view transitions for interaction-heavy UI
  • avoid view transitions when interruption or cancellation is required
  • treat size changes as potentially layout-triggering
  • 仅在导航级别的变化中使用视图过渡
  • 避免在交互密集的UI中使用视图过渡
  • 当需要中断或取消时，避免使用视图过渡
  • 将尺寸变化视为可能触发布局的操作

9. tool boundaries (critical)

9. 工具边界（严重）

  • do not migrate or rewrite animation libraries unless explicitly requested
  • apply these rules within the existing animation system
  • never partially migrate APIs or mix styles within the same component
  • 除非明确要求，否则不要迁移或重写动画库
  • 在现有动画系统内应用这些规则
  • 切勿部分迁移API或在同一组件内混合不同风格

common fixes

常见修复方案

css
/* 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(); }
js
// 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 = ''; });
css
/* 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(); }
js
// 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 = ''; });

review guidance

审查指南

  • enforce critical rules first (never patterns, tool boundaries)
  • choose the least expensive rendering work that matches the intent
  • for any non-default choice, state the constraint that justifies it (surface size, duration, or interaction requirement)
  • when reviewing, prefer actionable notes and concrete alternatives over theory
  • 首先执行严重规则（禁止模式、工具边界）
  • 选择符合需求且性能开销最低的渲染方式
  • 对于任何非默认选择，说明证明其合理性的约束条件（界面尺寸、时长或交互需求）
  • 审查时，优先提供可操作的建议和具体替代方案，而非理论内容