waynesutton/fixing-motion-performance

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

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