frontend-perf-animation-gpu-containment

name	frontend-perf-animation-gpu-containment
description	Use when a CSS animation or transition feels janky on a real device, when scroll stutters on a long page, when DevTools shows recurring layout or paint work during interaction, when an animation uses `top`, `left`, `width`, `height`, `margin`, `padding`, `font-size`, or `box-shadow`, when an off-screen part of a long document is still costing layout and paint time, when `will-change` has been sprinkled across the stylesheet and GPU memory is exhausted, when a card grid drops frames as cards enter the viewport, or when a custom property needs to be transitioned smoothly. Prevents the classic "animate top/left" main-thread jank, the `will-change` always-on memory leak, `contain: strict` collapsing an element to zero size because no explicit dimensions were given, `content-visibility: auto` without `contain-intrinsic-size` causing scrollbar jitter and lost scroll position, animating `box-shadow` or `width`/`height`/`margin` triggering paint storms, the `requestAnimationFrame` infinite-loop animation pattern that the platform already provides through CSS animations, and the trap of trying to transition an unregistered CSS custom property (untyped customs are interpolation-opaque). Covers the compositor-only animation rule (animate ONLY `transform`, `opacity`, `filter`), correct `will-change` lifecycle (set on interaction-start, remove on `transitionend` / `animationend` / interaction-end), the full `contain` value matrix (`none`, `strict`, `content`, `size`, `inline-size`, `layout`, `style`, `paint`) with side effects (containing block, stacking context, BFC), the `content-visibility` value set (`visible`, `hidden`, `auto`) and the mandatory `contain-intrinsic-size` pairing for `auto`, `@property` to make a CSS custom property animatable, and the rendering pipeline (Style -> Layout -> Paint -> Composite) used to reason about which stage a given animation hits. Keywords: will-change, contain, content-visibility, contain-intrinsic-size, transform, opacity, filter, compositor, compositor layer, GPU layer, GPU memory, paint, paint storm, layout thrash, layout, repaint, recomposite, render pipeline, @property, CSS.registerProperty, registerProperty, animatable custom property, transitionable custom property, FLIP, requestAnimationFrame, rAF, jank, frame drop, scroll stutter, scroll jank, off-screen content slow, animation laggy, animation choppy, GPU memory exhausted, why is my animation choppy, why is my page slow, what is GPU acceleration, how to make CSS faster, how do I make animation smooth, what is GPU-friendly animation, how to use CSS contain, when to use will-change.
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Perf Animation GPU Containment

This skill defines the rules for shipping animations and isolation that stay off the main thread and out of layout / paint storms. The rendering pipeline is Style -> Layout -> Paint -> Composite; transitions and animations are cheap when they only hit Composite, expensive when they hit Layout or Paint per frame. This skill builds on [[frontend-core-architecture]] (where Performance sits in the platform) and is referenced by [[frontend-errors-animation-jank]] (the bug catalog).

Sources : MDN: contain (verified 2026-05-19), MDN: content-visibility (verified 2026-05-19), MDN: will-change (verified 2026-05-19), MDN: @property (verified 2026-05-19), web.dev: Animations guide (verified 2026-05-19).

Quick Reference

The compositor-only rule

ALWAYS animate ONLY the following properties for production interactions :

Property	Pipeline stage
transform (translate, scale, rotate, skew, matrix)	Composite only.
opacity	Composite only.
filter (e.g. blur, drop-shadow, brightness)	Composite when the layer is already promoted; modern engines treat most filters as compositor-friendly.

NEVER animate any of the following in a repeated or per-frame transition :

Property	Why
top, left, right, bottom, inset	Triggers Layout.
width, height, block-size, inline-size	Triggers Layout.
margin, padding	Triggers Layout.
font-size, letter-spacing, line-height	Triggers Layout.
box-shadow	Triggers Paint per frame.
background-color, color (when the surface is large)	Triggers Paint per frame.
border-radius, border-* widths	Triggers Layout or Paint depending on context.

Per web.dev: Animations guide (verified 2026-05-19), profiling shows roughly 0 ms for Layout and Paint when transform is animated, versus tens of ms per frame when top/left is animated on the same scene.

will-change lifecycle

will-change MUST be applied dynamically and removed when the change is done. NEVER ship it statically in the stylesheet for elements that "might" animate.

el.addEventListener('pointerenter', () => { el.style.willChange = 'transform'; });
el.addEventListener('pointerleave', () => { el.style.willChange = 'auto'; });
el.addEventListener('animationend',   () => { el.style.willChange = 'auto'; });
el.addEventListener('transitionend',  () => { el.style.willChange = 'auto'; });

Per MDN: will-change (verified 2026-05-19) : "will-change is intended to be used as a last resort, in order to try to deal with existing performance problems. It should not be used to anticipate performance problems." Over-using will-change allocates compositor layers and GPU memory the browser would have managed automatically; the result is WORSE performance, not better.

Side effects : will-change that names a stacking-context-creating property (e.g. opacity, transform) creates the stacking context UP FRONT, which may shift visual layering before the animation runs. Account for this when promoting elements that float above siblings.

contain values

Per MDN: contain (verified 2026-05-19), Baseline Widely Available since March 2022.

Value	What it isolates	Containing block / stacking ctx / BFC
none	nothing	no
size	element size (both axes); element sized as if it had no contents	no
inline-size	inline-axis size only	no
layout	internal layout (floats, positioning, scroll do not leak out)	YES
style	CSS counters and quotes scoped to subtree	no
paint	descendants clipped to the border box, paint stays inside	no
content	shorthand for layout paint style	YES
strict	shorthand for size layout paint style	YES; the element MUST have an explicit size (intrinsic or set) or it collapses to 0

contain: content is the safe default for self-contained components (cards, list items, panels). contain: strict is for elements with KNOWN dimensions (image grid cells, virtualised rows) and adds size containment.

content-visibility values

Per MDN: content-visibility (verified 2026-05-19), Baseline 2024 (September 2024).

Value	Layout / Paint of subtree	Find-in-page	a11y tree	Tab/focus
visible (default)	always rendered	yes	yes	yes
hidden	skipped, render-state PRESERVED (like display: none but resumes faster)	NO	NO	NO
auto	skipped while OFF-SCREEN, rendered when near viewport; implies contain: layout style paint	yes	yes	yes

ALWAYS pair content-visibility: auto with contain-intrinsic-size: auto <length> or contain-intrinsic-size: <length>. Without it, off-screen content is sized to 0; the scrollbar jumps as content materialises and the user's scroll position drifts.

@property for animatable custom properties

Per MDN: @property (verified 2026-05-19), Baseline 2024 (July 2024).

@property --gradient-angle {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}

Untyped custom properties cannot be interpolated; transitions and animations on them snap from start to end. Registering with @property (or CSS.registerProperty() from JS) makes the property typed and interpolatable. initial-value MUST be computationally independent (no em, no vh units).

Decision Trees

Decision : can I animate this property safely?

Which property does the transition target?

  transform / opacity / filter
    -> YES. Composite-only. Ship the animation.

  top / left / width / height / margin / padding / font-size /
  box-shadow / background-color (large surface)
    -> NO. Rewrite using transform or opacity.
        - Position move : translate3d(...) / translate()
        - Size grow / shrink : transform: scale(...)
        - Shadow appear : opacity on a pseudo-element holding the shadow
        - Color crossfade on large surface : opacity on a layered overlay,
          NOT background-color transition.

  A CSS custom property (e.g. --gradient-angle, --progress)
    -> Register it with @property to make it typed. Then animate
       per the typed-property rules.

  Anything else
    -> Profile in DevTools Performance. If the property triggers
       Layout or Paint on the timeline, treat it as NO and rewrite.

Decision : should I use will-change?

What is the trigger for the change?

  User interaction is imminent (pointerenter on a card you will hover-grow,
  keydown on a slide deck about to transition).
    -> Set will-change on the trigger event. Remove on
       transitionend / animationend / interaction-end.

  The change is rare or far-future ("might be hovered eventually").
    -> NEVER. The browser already promotes elements during active
       transitions automatically.

  Already-running CSS transition or animation.
    -> NEVER add will-change after the animation has started; the
       element is already promoted.

  The element is animated all the time (sticky badge, ambient bg).
    -> Profile first. Many "always animating" effects can be
       redesigned to run only when visible or rely on transform
       which the engine promotes during the active transition.

Decision : which contain value (or content-visibility)?

What needs to be isolated?

  Self-contained component (card, panel, list-item) whose internal
  layout, paint, and style counters should not leak.
    -> contain: content;

  Same plus a KNOWN size (you can give an explicit width/height or
  the element has intrinsic dimensions).
    -> contain: strict;
       Set width and height (or aspect-ratio) explicitly; otherwise
       the element collapses to 0.

  Only CSS counters/quotes need scoping.
    -> contain: style;

  Long list / very tall page where off-screen items should not
  cost layout/paint.
    -> content-visibility: auto;
       PLUS contain-intrinsic-size: auto <length>;
       Each item should be a separate element with its own
       content-visibility rule so the engine can skip each block.

  An element that must be rendered but kept ready to swap in
  faster than display:none allows.
    -> content-visibility: hidden;
       Render state preserved across show / hide; find-in-page
       and the a11y tree do NOT see it.

Patterns

Pattern 1 : Long virtualised-feel list with content-visibility: auto

Render every item normally; the engine skips layout and paint for items that are far from the viewport. Pair with contain-intrinsic-size so the scrollbar stays correct.

.feed-item {
  content-visibility: auto;
  contain-intrinsic-size: auto 320px;
}

Full HTML in examples.md (100-item demo).

Pattern 2 : Promote on hover, demote on leave

.card { transition: transform 200ms; }
.card:hover { transform: translateY(-4px); }

card.addEventListener('pointerenter', () => card.style.willChange = 'transform');
card.addEventListener('pointerleave', () => card.style.willChange = 'auto');

The transition itself is composite-only. will-change is added per-interaction so the GPU layer is allocated only while needed.

Pattern 3 : Size animation via transform: scale, NOT width

.bar { transform-origin: left; transform: scaleX(var(--progress)); transition: transform 200ms ease; }

scaleX is a transform; pixel-perfect text inside the bar is achievable by counter-scaling the text child (transform: scaleX(calc(1 / var(--progress)))) when needed.

Pattern 4 : Animatable gradient angle with @property

@property --grad-angle { syntax: '<angle>'; inherits: false; initial-value: 0deg; }
.hero {
  background: linear-gradient(var(--grad-angle), #4d4dff, #ff66cc);
  animation: spin 12s linear infinite;
}
@keyframes spin { to { --grad-angle: 360deg; } }

Without @property, the transition would snap at 0deg / 360deg rather than rotating smoothly.

Pattern 5 : Component isolation with contain: content

.card { contain: content; }

Internal floats, positioned descendants, and counter usage do not leak to the page. The card establishes a containing block, stacking context, and BFC; ALWAYS verify positioned descendants still target the intended ancestor (a position: fixed child now positions against the viewport BUT also lives inside a containing block; see the contain MDN reference for details).

Anti-Patterns Index

See anti-patterns.md. Eight cataloged : animating top/left/width/height/margin (jank); will-change always-on (GPU memory drain); will-change never removed; content-visibility: auto without contain-intrinsic-size (scroll jitter); animating box-shadow (paint storm); contain: strict on an element with no explicit size (collapses to 0); requestAnimationFrame infinite loop for state-independent animation (CSS would be cheaper); animating an unregistered custom property (snaps).

Reference Links

• Methods and signatures : full contain matrix, content-visibility matrix, will-change JS lifecycle, @property syntax, rendering-pipeline diagram in text, DevTools panels to inspect each stage.
• Examples : working snippets for the five patterns above plus DevTools-driven debugging walkthrough.
• Anti-patterns : eight cataloged anti-patterns with symptom, root cause, and fix.

Cross-references

• [[frontend-perf-core-web-vitals-inp]] : LCP / INP / CLS metrics and how compositor-only animation feeds into them.
• [[frontend-visual-micro-interactions]] : choreography of micro-interactions; uses this skill's compositor rule as a hard constraint.
• [[frontend-impl-view-transitions-scroll-animations]] : view-transitions and scroll-driven animations both rely on compositor-only properties.
• [[frontend-errors-animation-jank]] : the bug-catalog companion that diagnoses symptoms back to this skill's rules.
• [[frontend-syntax-css-color-modern]] : @property re-appears for animating colour custom properties.