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