Optimize UI Animation Performance

A prioritized rulebook for diagnosing and fixing animation-performance issues, invoked as /fixing-motion-performance (apply to any UI animation work) or /fixing-motion-performance <file> (review a file and report violations with the exact snippet, why it matters, and a concrete fix) - applying rules within the existing animation stack rather than migrating libraries. It frames the browser's rendering steps as three tiers - composite (transform, opacity), paint (color, borders, gradients, masks, filters), and layout (size, position, flow) - and organizes rules into nine priority categories: never-patterns (critical - no interleaved layout reads and writes in a frame, no continuous layout animation on large surfaces, no driving animation from scrollTop/scrollY), mechanism choice (critical - default to transform/opacity, downgrade technique before removing motion entirely), measurement (high - measure once then animate via transform, batch DOM reads before writes, prefer FLIP-style transitions), scroll (high - prefer Scroll or View Timelines over polling scroll position, pause animations off-screen), paint (medium-high - paint-triggering animation only on small isolated elements, never animate inherited CSS variables), layers (medium - never assume compositor layer promotion, use will-change surgically), blur and filters (medium - keep blur animation under 8px, never animate it continuously or on large surfaces), view transitions (low - only for navigation-level changes, not interaction-heavy UI), and tool boundaries (critical - no partial API migrations or mixed styles within a component).

.panel { transition: transform 0.3s; }

Use it when adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP), refactoring janky interactions or transitions, implementing scroll-linked or reveal-on-scroll motion, animating layout, filters, masks, gradients, or CSS variables, or reviewing components using will-change, transforms, or DOM measurement.

Input: UI animation code being written or an existing file to review. Output: either constraints applied inline to new animation work, or a violation-by-violation review report - a quoted snippet, why it matters, and a concrete fix - enforcing critical rules (never-patterns, tool boundaries) first, and for any non-default technique choice, stating the constraint (surface size, duration, or interaction requirement) that justifies it.

Frontend developers fixing janky or expensive animations who want a concrete, priority-ordered performance checklist rather than generic "use transform not width" advice.

Its common-fixes reference includes converting a scroll event listener that mutates opacity on every scroll event into a declarative animation-timeline: view() rule, and a FLIP-style fix that measures an element's bounding rect before and after a layout change, then animates only the transform delta between the two.