fixing-motion-performance

name	fixing-motion-performance
description	Fix animation performance issues. Use when adding or changing UI animations, refactoring janky interactions, implementing scroll-linked motion, animating layout/filters/masks, or reviewing components that use will-change, transforms, or measurement.

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)

• 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