fixing-motion-performance
Fix animation performance issues.
how to use
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)
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
common fixes
/* 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 = ''; });
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
