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.

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

rendering steps glossary

• •composite: transform, opacity
• •paint: color, borders, gradients, masks, images, filters
• •layout: size, position, flow, grid, flex

rule categories by priority

quick reference

1. never patterns (critical)

• •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

2. choose the mechanism (critical)

• •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

3. measurement (high)

• •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

4. scroll (high)

• •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

5. paint (medium-high)

• •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

6. layers (medium)

• •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

7. blur and filters (medium)

• •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

8. view transitions (low)

• •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

9. tool boundaries (critical)

• •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

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