fixing-motion-performance ยท diff
git:20260121.08e8efc to git:20260121.fa3901e
124 added, 2 removed. Audit B to A.
---
name: fixing-motion-performance
- description: Fix animation performance issues. Prefer safe, predictable motion.
+ description: Fix animation performance issues.
---
- Loremp ipsum
+ # 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
+