animation-performance

作者: emilkowalski

Keep web animations inside the frame budget — animate composite-only properties, keep motion off the main thread when the page is busy, and find the cause when an animation drops frames. Use when an animation is janky, choppy, stutters, or drops frames; when choosing which property to animate; when deciding between CSS and JS animation on performance grounds; or when reaching for `will-change` or GPU layers. For choosing easing, duration, or whether to animate at all use animate; for...

npx skills add https://github.com/emilkowalski/skills --skill animation-performance

Animation Performance

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 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.

ProblemSolution
Animation stuttersAnimate transform/opacity, not width/height/top/margin
Shadow animation is choppyfilter: drop-shadow() (composited in Chrome; measure elsewhere)
Jank only during navigation or loadingMove the animation to CSS or WAAPI so it runs off the main thread
Motion x/y drops framesUpgrade to motion 14.2+, or animate the full transform string
Hand-rolled animation drops frames in ReactWrite to ref.current.style, not state
Drag gets laggier as the list growsStop animating an inherited CSS variable; set transform directly
Blur transition lags (especially Safari)Keep animated blur() under 20px
Unexpected properties animateReplace transition: all with explicit properties
Element shifts 1px when motion starts or endswill-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:

TierPropertiesCost
Composite onlytransform, opacityCheapest. Browsers promote these to their own layer.
Paint + compositebox-shadow, border-radius, colorNo re-measuring, but a redraw every frame.
Layout + paint + compositewidth, height, padding, margin, top, left, border-widthMost 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.

Swapping down a tier:

Instead ofAnimate
width / height / padding to grow or shrinkscale()
top / left / margin to movetranslate() (percentages are relative to the element's own size)
display / visibility swapsopacity, then visibility: hidden once it ends so it stops taking clicks
box-shadowfilter: drop-shadow(…) (Chrome composites filter; other engines may repaint, so measure)

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. But when scale() gives the look you want (it scales children too and keeps the layout space), only it can't regress on a slower device. Pick it.
  • 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 always 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.

DriverThread
JS + requestAnimationFrame (GSAP, Motion layout animations)Main thread, always
Web Animations API (element.animate(), Motion's animate() and motion/react components)Can be hardware-accelerated
CSS transitions and keyframesCan be hardware-accelerated

Hardware acceleration means the animation runs off the main thread, so it stays smooth no matter what JavaScript is doing. "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.

Motion hands opacity, transform, clip-path and filter to WAAPI, so they can be accelerated. The x, y, scale, rotate shorthands depend on the version:

<motion.div animate={{ x: 100 }} />                          // motion 14.2+: hardware-accelerated. Before: main thread, can jank
<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware-accelerated in every version

From motion 14.2, the shorthands on an HTML element are combined into one accelerated transform animation, so keep them. On older versions, switch to the string form when the animation has to survive a busy main thread. In every version, these stay on the main thread: layout animations (layout, layoutId), onUpdate, transformTemplate, inertia, and values driven every frame by a motion value (drag, useTransform).

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 libraries animate outside React's render cycle, so they're fine. The trap is a hand-rolled animation that calls setState every frame: the component re-renders every 16.7ms and the render alone blows the budget.

// Drops frames: one re-render per frame
setY(nextY);

// Smooth: no re-render
ref.current.style.transform = `translateY(${nextY}px)`;
// or with a motion value: y.set(nextY)

Look for state updates inside requestAnimationFrame, pointermove, scroll, or drag handlers.

Two Traps That Look Correct

Both of these use transform and still drop frames.

Inherited CSS variables. Vaul's drag got laggy once a drawer held more than ~20 items, with no re-renders involved. The drag distance was written to a CSS variable that translateY() read:

// Recalculates styles for every descendant, every frame
const style = { "--swipe-amount": `${draggedDistance}px` };

// Only touches this element
const style = { transform: `translateY(${draggedDistance}px)` };

CSS variables inherit, so changing one on a parent triggers style recalculation for every child. The more content, the slower each frame. Suspect this whenever a transform animation degrades as content grows.

Blur. filter: blur() gets expensive fast, especially in Safari. Keep animated blur under 20px; 2–5px is enough to soften a crossfade.

will-change

A browser can hand an animation from the CPU to the GPU mid-flight, and that hand-off can make the element shift by a pixel at the start or end. will-change promotes the element up front so no hand-off happens:

.drawer {
  will-change: transform;
}

Add it only once you see the shift or measured dropped frames. Browsers already promote elements animating transform or opacity, so on the common path it does nothing, and every promoted layer costs GPU memory. Put it on the element that animates, never on * or large containers.

Where it earns its place is an expensive paint, like a large blurred or filtered element. Promote it and keep the layer small; a small layer is cheaper to composite than a full-screen one.

Should You Avoid JS Animation?

No. Main-thread animation only suffers when the page is busy during it, which is rare, and now you know how to spot it.

Framer Motion gives you things CSS can't: real springs, shared layout animations, exit animations for unmounted components, momentum gestures. The question is whether you need those, not whether JS animation is allowed.

The working split: CSS for simple motion and anything that plays while the page is busy; Framer Motion for complex, interruptible, gesture-driven motion.

Workflow

Phase 1: Find what animates

List every animation in scope with its driver and properties:

ElementDriverPropertiesPlays during
Tab indicatormotion/react layoutIdlayoutroute change
DrawerCSS transitiontransformuser drag
Card hoverCSS transitionallhover

Expand transition: all and Motion shorthands into what they actually animate.

Phase 2: Diagnose

Work down this list. It's ordered by how often each one is the cause:

  1. Which properties animate? Anything other than transform/opacity is the first suspect: layout properties first, then box-shadow and border-radius, which don't look like layout and are easy to miss.
  2. Does the jank coincide with the page being busy? Navigation, fetching, hydration, a long task. Move the animation to CSS or WAAPI.
  3. Is React re-rendering per frame? State updates in rAF, pointer, or scroll handlers.
  4. Does it get worse as content grows? An inherited CSS variable, or too many nodes animating at once.
  5. Is a CSS variable animated at all? Or Motion's x/y/scale on a version before 14.2?
  6. Any animated blur() above 20px?
  7. Still shifting or stuttering? Now add will-change: transform to the animating element.

Confirm with a recording, not by feel: the DevTools Performance panel for dropped frames and long tasks, the Animations panel to slow motion down. Profile on a real mid-range phone over remote debugging. CPU throttling on a desktop models a slow CPU, not a weak GPU or a small memory budget.

Phase 3: Report

For each finding:

**[Element]**: `file.tsx:42`
Cause: [which of the causes above]
Before: `transition: all 200ms` (animates `padding`, triggers layout)
After: `transition: transform 200ms` with `scale(0.97)`
Verified: from code / needs a device recording

Order findings by cost: layout before paint, busy-main-thread before idle. Then stop. Apply fixes when asked.

來自 emilkowalski 的更多技能

animate
emilkowalski
從零開始建立動畫,依序做出決定,以判斷整體是否自然流暢——是否該有動畫、目的為何、選用哪種工具、哪些屬性、哪條曲線與時長、如何打斷、如何結束。並撰寫實作內容。當被要求為某個東西加上動畫、增添動態感、讓元件更有生命力,或建立轉場效果時使用。若要評論現有動態效果,請使用 review-animations;若要審查整個程式碼庫,請使用 improve-animations。
animate-expo
emilkowalski
在 React Native 和 Expo 中製作動畫,依照決定動畫是否自然的順序做出選擇——是否要動畫、在哪個執行緒執行、使用哪些屬性、採用彈簧還是定時動畫、手勢如何交接,以及如何降級。使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics 撰寫實作。適用於在 Expo app 中製作任何動畫、加入手勢、底部面板、畫面轉場、按壓回饋或觸覺回饋,或修復裝置上卡頓的動態效果。適用於……
developmentdesign
animation-vocabulary
emilkowalski
反向查詢詞彙表,將模糊描述的網頁動畫或動態效果轉換為精確術語(例如:「彈出視窗開啟時的彈跳效果」→ Pop in;「iOS橡皮筋滾動」→ Rubber-banding)。適用於使用者詢問「那個叫什麼…」或描述某個動態效果卻不知其名稱,並希望獲得正確詞彙以提示AI或設計師時使用。此功能僅用於命名效果,而非設計或實作。
researchdesigncreative
apple-design
emilkowalski
Apple 的介面設計與流暢、物理動態方法,專為網頁轉譯。適用於建構或審查手勢驅動的 UI、彈性動畫、拖曳/滑動/面板互動、動量與可中斷轉場、半透明材質與深度、字體排印(光學尺寸、字距、行距)、減少動態效果,或 Apple 風格介面背後的設計基礎(回饋、空間一致性、克制)。
ask-emil
emilkowalski
Ask which skill or flow fits your situation. A router over the skills in this repo.
developmentproductivity
ask-sonner
emilkowalski
Sonner(React toast 函式庫)使用指南——安裝並接上 Toaster、選用正確的 toast() 呼叫、promise 與 loading toast、更新、關閉及持久化 toast、樣式、主題與圖示、定位與多個 toaster。適用於使用 Sonner 或排解其問題時——例如 toast 未出現、出現兩次、失去樣式、忽略 Tailwind 類別、位於 modal 後方,或未跟隨深色模式。
break-ui
emilkowalski
透過輸入最糟情況的資料來嘗試破壞 UI 元件——長名稱、無法換行的電子郵件、單字母名稱、缺少欄位、超大數量、零個項目、長標籤、非拉丁文字、表情符號、極端數字——接著在「Demo data / Worst case」切換開關後方呈現,並回報所有出問題的地方及各自的修正方式。當使用者要求對元件或畫面進行壓力測試、找出問題或邊界情況,或「試試最糟情況」時使用。若要進行視覺設計評論,請使用 emil-design-eng;若要處理動態效果……
testingdesigndevelopment
choreograph
emilkowalski
Coordinate several elements that animate together — decide what moves, in what order, how much they overlap, and what stays still — so a group reads as one intentional motion instead of a pile of separate animations. Use when building or fixing a staggered list, a hero entrance, a view swap inside a container, a multi-step flow, an element leaving while its siblings close the gap, a morph between rich states, or any interaction with several moving parts (icon + background + lines, panel +...
designdevelopment