1---
2name: fixing-motion-performance
3description: Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.
4---
5 
6# fixing-motion-performance
7 
8Fix animation performance issues.
9 
10## how to use
11 
12- `/fixing-motion-performance`
13  Apply these constraints to any UI animation work in this conversation.
14 
15- `/fixing-motion-performance <file>`
16  Review the file against all rules below and report:
17  - violations (quote the exact line or snippet)
18  - why it matters (one short sentence)
19  - a concrete fix (code-level suggestion)
20 
21Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack.
22 
23## when to apply
24 
25Reference these guidelines when:
26- adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP)
27- refactoring janky interactions or transitions
28- implementing scroll-linked motion or reveal-on-scroll
29- animating layout, filters, masks, gradients, or CSS variables
30- reviewing components that use will-change, transforms, or measurement
31 
32## rendering steps glossary
33 
34- composite: transform, opacity
35- paint: color, borders, gradients, masks, images, filters
36- layout: size, position, flow, grid, flex
37 
38## rule categories by priority
39 
40| priority | category | impact |
41|----------|----------|--------|
42| 1 | never patterns | critical |
43| 2 | choose the mechanism | critical |
44| 3 | measurement | high |
45| 4 | scroll | high |
46| 5 | paint | medium-high |
47| 6 | layers | medium |
48| 7 | blur and filters | medium |
49| 8 | view transitions | low |
50| 9 | tool boundaries | critical |
51 
52## quick reference
53 
54### 1. never patterns (critical)
55 
56- do not interleave layout reads and writes in the same frame
57- do not animate layout continuously on large or meaningful surfaces
58- do not drive animation from scrollTop, scrollY, or scroll events
59- no requestAnimationFrame loops without a stop condition
60- do not mix multiple animation systems that each measure or mutate layout
61 
62### 2. choose the mechanism (critical)
63 
64- default to transform and opacity for motion
65- use JS-driven animation only when interaction requires it
66- paint or layout animation is acceptable only on small, isolated surfaces
67- one-shot effects are acceptable more often than continuous motion
68- prefer downgrading technique over removing motion entirely
69 
70### 3. measurement (high)
71 
72- measure once, then animate via transform or opacity
73- batch all DOM reads before writes
74- do not read layout repeatedly during an animation
75- prefer FLIP-style transitions for layout-like effects
76- prefer approaches that batch measurement and writes
77 
78### 4. scroll (high)
79 
80- prefer Scroll or View Timelines for scroll-linked motion when available
81- use IntersectionObserver for visibility and pausing
82- do not poll scroll position for animation
83- pause or stop animations when off-screen
84- scroll-linked motion must not trigger continuous layout or paint on large surfaces
85 
86### 5. paint (medium-high)
87 
88- paint-triggering animation is allowed only on small, isolated elements
89- do not animate paint-heavy properties on large containers
90- do not animate CSS variables for transform, opacity, or position
91- do not animate inherited CSS variables
92- scope animated CSS variables locally and avoid inheritance
93 
94### 6. layers (medium)
95 
96- compositor motion requires layer promotion, never assume it
97- use will-change temporarily and surgically
98- avoid many or large promoted layers
99- validate layer behavior with tooling when performance matters
100 
101### 7. blur and filters (medium)
102 
103- keep blur animation small (<=8px)
104- use blur only for short, one-time effects
105- never animate blur continuously
106- never animate blur on large surfaces
107- prefer opacity and translate before blur
108 
109### 8. view transitions (low)
110 
111- use view transitions only for navigation-level changes
112- avoid view transitions for interaction-heavy UI
113- avoid view transitions when interruption or cancellation is required
114- treat size changes as potentially layout-triggering
115 
116### 9. tool boundaries (critical)
117 
118- do not migrate or rewrite animation libraries unless explicitly requested
119- apply these rules within the existing animation system
120- never partially migrate APIs or mix styles within the same component
121 
122## common fixes
123 
124```css
125/* layout thrashing: animate transform instead of width */
126/* before */ .panel { transition: width 0.3s; }
127/* after */  .panel { transition: transform 0.3s; }
128 
129/* scroll-linked: use scroll-timeline instead of JS */
130/* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500)
131/* after */  .reveal { animation: fade-in linear; animation-timeline: view(); }
132```
133 
134```js
135// measurement: batch reads before writes (FLIP)
136// before — layout thrash
137el.style.left = el.getBoundingClientRect().left + 10 + 'px';
138// after — measure once, animate via transform
139const first = el.getBoundingClientRect();
140el.classList.add('moved');
141const last = el.getBoundingClientRect();
142el.style.transform = `translateX(${first.left - last.left}px)`;
143requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; });
144```
145 
146## review guidance
147 
148- enforce critical rules first (never patterns, tool boundaries)
149- choose the least expensive rendering work that matches the intent
150- for any non-default choice, state the constraint that justifies it (surface size, duration, or interaction requirement)
151- when reviewing, prefer actionable notes and concrete alternatives over theory
152