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

priority	category	impact
1	never patterns	critical
2	choose the mechanism	critical
3	measurement	high
4	scroll	high
5	paint	medium-high
6	layers	medium
7	blur and filters	medium
8	view transitions	low
9	tool boundaries	critical

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)