fixing-motion-performance

Corriger les problèmes de performance d'animation.

Triggers

• animation performance
• jank
• fps
• reflow
• repaint
• will-change
• gpu
• composite
• 60fps
• smooth animation
• laggy animation
• slow animation

how to use

• /fixing-motion-performance Appliquer ces contraintes à tout travail d'animation UI dans cette conversation.

• /fixing-motion-performance <file> Examiner le fichier par rapport à toutes les règles ci-dessous et rapporter :

  • violations (citer la ligne ou l'extrait exact)
  • pourquoi c'est important (une courte phrase)
  • un correctif concret (suggestion au niveau du code)

Ne pas migrer les bibliothèques d'animation sauf demande explicite. Appliquer les règles au sein de la stack existante.

when to apply

Consulter ces directives lors de :

• l'ajout ou la modification d'animations UI (CSS, WAAPI, Motion, rAF, GSAP)
• la refonte d'interactions ou de transitions saccadées
• l'implémentation de motion liée au scroll ou de reveal-on-scroll
• l'animation de layout, filtres, masques, gradients, ou variables CSS
• l'examen de composants utilisant will-change, transforms, ou measurement

rendering steps glossary

• composite: transform, opacity
• paint: color, borders, gradients, masks, images, filters
• layout: size, position, flow, grid, flex

rule categories by priority

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

Verify

• A profiler trace (DevTools Performance, Instruments, Xcode FPS HUD) was captured before and after the fix; both are linked
• Frame rate is reported as a number on a named device/browser (e.g., '58-60 fps on iPhone 13 Safari') for both before and after
• The animation was checked under prefers-reduced-motion; the reduced variant was visually confirmed
• GPU-accelerated properties (transform/opacity) are used where possible; layout-thrashing properties were identified and removed
• Long-task / main-thread-blocking measurements show the regression is gone, not just feels smoother
• Battery / thermal impact on mobile was at least sanity-checked for animations that loop or run for > 1s