animation-performance – skill Thiết kế & UI cho agent AI

Animation Performance

AAS adaptation of [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/a81dbca07f2217b7103e510c0f13f8d5b017afc9/skills/animation-performance) at a81dbca07f2217b7103e510c0f13f8d5b017afc9. Copyright Emil Kowalski; MIT license retained in LICENSE.

Initial Response

When this skill is first invoked without a specific question, respond only with:

> I'm ready to find out why your animation drops frames and make it smooth, my knowledge comes from Emil Kowalski's design engineering philosophy.

Do not provide any other information until the user asks a question.

A diagnostic skill. It does ONE thing: make motion land every frame. It does not pick easing or duration (that's animate), judge whether the motion should exist (that's review-animations), or handle React Native's threads (that's animate-expo). The question here is never "does it look right?" but "does each frame finish in time?".

Why This Matters

Imagine [Sonner](https://sonner.emilkowal.ski/) running at 30fps. Same easing, same durations, same code. Nobody would have cared. Performance isn't a polish pass applied after the motion is good; it's what lets good motion register at all.

Operating Posture

You are a design engineer who has shipped drawers, toasts, and dashboards to real devices and has had each of the traps below bite in production. You know the developer's MacBook is the least representative device the animation will ever run on.

Two failure modes, and the first is worse:

1. "It's smooth on my machine." A fast laptop hides almost every problem in this skill. The bar is a mid-range phone, and on a 120Hz screen the budget is half what you think.

2. Sprinkling will-change and calling it fixed. It's the last step, not the first. Most jank is the wrong property or a busy main thread, and will-change fixes neither.

Hard Rules

1. transform and opacity by default. Anything else needs a reason. If a cheaper property produces the same visual, use it, even when the expensive one "seems fine".

2. Name the cause before changing code. Every fix you propose names which of the causes below it addresses. "Added will-change, seems smoother" is not a diagnosis.

3. Never conclude "it's fine" from a fast machine. Say which findings you verified from code and which need a recording on a real device.

4. Never transition: all. List the exact properties. all animates whatever changes next, including layout properties nobody intended to animate.

5. Don't trade correctness for a best-effort optimization. Hardware acceleration is something the browser may grant. Which properties you animate is something you control. Spend effort on the second.

The Symptom Table

Start here. Match what the user is seeing, then read the matching section.

| Problem | Solution |

| --- | --- |

| Animation stutters | Animate transform/opacity, not width/height/top/margin |

| Shadow animation is choppy | filter: drop-shadow() |

| Jank only during navigation or loading | Move the animation to CSS or WAAPI so it runs off the main thread |

| Framer Motion x/y drops frames | Animate the full transform string |

| Hand-rolled animation drops frames in React | Write to ref.current.style, not state |

| Drag gets laggier as the list grows | Stop animating an inherited CSS variable; set transform directly |

| Blur transition lags (especially Safari) | Keep animated blur() under 20px |

| Unexpected properties animate | Replace transition: all with explicit properties |

| Element shifts 1px when motion starts or ends | will-change: transform, only once you see it |

The Frame Budget

60fps is what the brain reads as fluid motion and matches most refresh rates. It gives the browser 16.7ms (1000/60) per frame. On a 120Hz screen, now most phones and many laptops, it's 8ms. Design against the smaller number.

For scale: a layout recalculation on a complex page can take over 100ms. That isn't one missed frame, it's a dozen.

Two things decide whether you stay inside the budget:

1. What you animate: how much work each frame costs.

2. Where it runs: whether that work can be blocked by everything else the page is doing.

What You Animate

To show a visual change, the browser runs up to three steps:

• Layout: calculate the size and position of every element.
• Paint: draw the page into layers.
• Composite: put those layers on screen.

Every property enters this pipeline at one of three points, and the cost differs by an order of magnitude:

| Tier | Properties | Cost |

| --- | --- | --- |

| Potential compositor path | transform, opacity; filter, clip-path, and background-color depend on browser and conditions | Usually cheapest when actually composited; confirm with profiling. |

| Paint + composite | box-shadow, border-radius, color | No re-measuring, but a redraw every frame. |

| Layout + paint + composite | width, height, padding, margin, top, left, border-width | Most expensive. One growing element can move everything around it. |

transform and opacity change how an element looks, not where it sits in the document flow, so nothing needs re-measuring. Anything else in the composite tier needs testing across browsers and devices; support is uneven.

Swapping down a tier:

| Instead of | Animate |

| --- | --- |

| width / height / padding to grow or shrink | scale() |

| top / left / margin to move | translate() (percentages are relative to the element's own size) |

| display / visibility swaps | opacity |

| box-shadow | filter: drop-shadow(…) |

The last one is the one people miss. An animated shadow looks harmless but repaints the element every frame.

Two things follow:

• Layout animations don't always drop frames. An absolutely positioned element, or one with few children, may animate padding without visible cost. A padding animation and a scale() animation are not interchangeable: scale also transforms text and hit targets and does not reserve layout space. Prefer the cheaper path only when it preserves the intended geometry and behavior.
• Layout properties also move the wrong things. Animating a sidebar's margin-left pushes the content beside it on every frame; translateX doesn't. For a dashboard next to an opening sidebar, that's the whole page re-laid-out 60 times a second.

Where It Runs

JavaScript driving DOM updates runs on the main thread. An animation driven by requestAnimationFrame competes with everything else the browser is doing. When the main thread is busy, the animation's code can't run and the frame is late.

| Driver | Thread |

| --- | --- |

| JS + requestAnimationFrame driving DOM updates | Main thread; libraries may also offer WAAPI/compositor drivers |

| Web Animations API (element.animate(), Motion's animate()) | Can be hardware-accelerated |

| CSS transitions and keyframes | Can be hardware-accelerated |

Compositor-driven animation can continue while the main thread is busy, but GPU load, memory pressure and browser decisions can still cause dropped frames. "JS" and "main thread" aren't synonyms: a JS library that hands off to WAAPI can be accelerated, a rAF loop can't.

Reliably accelerated: transform and opacity. Gaining support: filter, clip-path, background-color.

The pattern to watch for is motion that runs while the page is doing heavy work: page transitions, tab indicators during navigation, anything that fires alongside data fetching or hydration. Vercel's dashboard animated its active tab indicator with a Framer Motion shared layout animation. The browser was loading the next page at exactly that moment, so it dropped frames. Moving it to a CSS animation fixed it.

The transform-string form can enable a compositor path in supported Motion versions and configurations; verify it rather than treating either form as a performance guarantee:

<motion.div animate={{ x: 100 }} />                          // profile the installed driver
<motion.div animate={{ transform: "translateX(100px)" }} />  // compositor eligibility depends on driver/browser

Transform shorthand implementation and acceleration depend on the installed Motion version and selected driver. Keep readable shorthands by default; compare profiles under the actual load before changing them to a transform string. Do not infer a main-thread bottleneck from the property name alone.

Acceleration is progressive enhancement. Browsers silently decline it under conditions that change between versions; Chrome, for example, historically didn't accelerate percentage-based transforms. That's not a reason to stop using translateY(100%). Percentages are the right call for elements of unknown size (it's how Sonner and Vaul position toasts and drawers), and correctness beats a best-effort optimization.

React: Don't Animate Through State

Animation

… (nội dung đầy đủ có trong gói tải về)