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