references/performance.md

Performance

will-change Explained (Jakub)

A hint to the browser: "I'm about to animate these properties, please prepare."

/* Good - specific properties that will animate */
.animated-button {
  will-change: transform, opacity;
}

/* Bad - too broad, wastes resources */
* { will-change: auto; }
.element { will-change: all; }

Properties that benefit from will-change:

transform
opacity
filter (blur, brightness)
clip-path
mask

Why it matters: Without the hint, the browser promotes elements to GPU layers only when animation starts, causing first-frame stutter. With will-change, it pre-promotes during idle time.

When NOT to use:

On elements that won't animate
On too many elements (each GPU layer uses memory)
As a "fix" for janky animations (find the real cause)

Gradient Animation Performance (Jakub)

Cheap to animate (GPU-accelerated):

background-position
background-size
opacity

Expensive to animate:

Color stops
Adding/removing gradient layers
Switching gradient types

Tip: Animate a pseudo-element overlay or use CSS variables that transition indirectly.

Animation Performance Budget

As a rough guide:

0-3 elements with will-change: Fine
4-10 elements: Careful, test on low-end devices
10+ elements: Reconsider approach, use virtualization or stagger

Properties to Avoid Animating

These trigger layout recalculation (expensive):

width, height
top, left, right, bottom
margin, padding
font-size

Always prefer:

transform: translate() instead of top/left
transform: scale() instead of width/height
opacity for visibility changes

Performance Checklist

will-change used sparingly and specifically
Animations use transform/opacity (not layout properties)
Tested on low-end devices
No continuous animations without purpose
GPU layer count is reasonable (< 10 animated elements)