Optimize UI Animation Performance

Fixing Motion Performance is a skill for auditing and fixing animation performance problems: layout thrashing, compositor properties, scroll-linked motion and blur effects. It comes from the ibelick/ui-skills repository under the MIT license. It is invoked in two ways. Running /fixing-motion-performance applies its constraints to any UI animation work in the conversation, and running /fixing-motion-performance with a file path reviews that file against every rule and reports each violation (quoting the exact line or snippet), why it matters in one short sentence, and a concrete code-level fix.

The skill starts from a glossary of rendering steps. Composite covers transform and opacity, paint covers color, borders, gradients, masks, images and filters, and layout covers size, position, flow, grid and flex. Rules are ranked by priority: never patterns and tool boundaries are critical, choosing the mechanism is critical, measurement and scroll are high, paint is medium-high, layers and blur are medium, and view transitions are low.

Key rules include never interleaving layout reads and writes in one frame, never driving animation from scrollTop, scrollY or scroll events, no requestAnimationFrame loops without a stop condition, defaulting to transform and opacity, batching DOM reads before writes, preferring FLIP-style transitions, and preferring Scroll or View Timelines with IntersectionObserver for visibility. Blur animation should stay at 8px or less, be short and one-time, and never run continuously or on large surfaces.

Use it when animations stutter or transitions jank, or when reviewing CSS or JS animation performance. It applies when adding or changing UI animations in CSS, WAAPI, Motion, rAF or GSAP, refactoring janky interactions, implementing scroll-linked or reveal-on-scroll motion, animating layout, filters, masks, gradients or CSS variables, and reviewing components that use will-change, transforms or measurement.

A firm boundary applies: do not migrate or rewrite animation libraries unless explicitly requested, apply the rules within the existing animation system, and never partially migrate APIs or mix styles within one component. Its limitations add that commands, generated code and dependencies should be verified before applying changes, and that examples do not replace environment-specific tests.

The input is either the conversation context or a file to review. The output is a list of violations with quotes, reasons and fixes. The skill's review guidance is to enforce critical rules first, choose the least expensive rendering work that fits the intent, state the justifying constraint (surface size, duration or interaction requirement) for any non-default choice, and prefer actionable notes over theory.

The skill includes before-and-after examples, such as animating transform instead of width to avoid layout thrashing:

/* before */ .panel { transition: width 0.3s; }
/* after */  .panel { transition: transform 0.3s; }

It also shows replacing a scroll listener with a CSS scroll timeline (animation-timeline: view()) and a FLIP pattern that measures once and animates via transform.

It is for front-end developers and reviewers who need smooth UI motion and want concrete, rule-based fixes without changing their animation stack.