/web-animation-css-animations

name: web-animation-css-animations
description: CSS animation patterns - transitions, keyframes, scroll-driven timelines, @property, compositor-friendly properties, prefers-reduced-motion

CSS Animation Patterns

> **Quick Guide:** Transitions carry state changes (hover, focus, a toggled attribute); `@keyframes` > carries motion that loops, auto-plays, or has more than two steps; `animation-timeline` carries > scroll- and viewport-linked progress. Confining animation to `transform` and `opacity` keeps the > frames on the compositor thread, and every animation gets a `prefers-reduced-motion` branch.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — token system, interactive states, entrance, spinner, toast, reduced-motion
• [examples/transitions.md](examples/transitions.md) — multi-property transitions, staggered delays, accordions, colour, links
• [examples/keyframes.md](examples/keyframes.md) — scroll-driven timelines, `@property` gradients, typewriter, stagger, clip-path morphs
• [reference.md](reference.md) — easing catalogue, property cost table, duration guidance, browser support

---

Which path applies

• **The motion is a state change** — `:hover`, `:focus-visible`, a data attribute, a toggled class —

then a `transition` on the base rule is the whole mechanism; follow [examples/transitions.md](examples/transitions.md).

• **The motion loops, auto-plays on mount, or passes through more than two states** — then it needs

`@keyframes` and an `animation` shorthand; follow [examples/keyframes.md](examples/keyframes.md).

• **The motion tracks scroll position or viewport entry** — then the driver is

`animation-timeline: scroll()` or `view()` rather than time, and the keyframes describe progress from 0 to 1; follow [examples/keyframes.md](examples/keyframes.md).

---

<critical_requirements>

Before writing CSS animation code

**Animate `transform` and `opacity`.** Both are composited, so the frames run off the main thread and survive a busy tab; `width`, `top` and `margin` re-run layout on every frame instead.

**Give every animation a `prefers-reduced-motion` branch.** The preference is a vestibular safety setting rather than an off switch — an opacity fade at a shorter duration usually satisfies it while keeping the state change legible.

**Use `ease-out` on enter and `ease-in` on exit.** An element arriving decelerates into place and one leaving accelerates away; `linear` reads as mechanical for anything but continuous rotation.

**Scope `will-change` to the interaction that needs it.** Each declaration holds a compositing layer for as long as the rule applies, so a blanket selector holds one per element on the page at once.

</critical_requirements>

---

**Auto-detection:** @keyframes, transition-property, transition-duration, animation-timeline, scroll-timeline, view-timeline, animation-range, animation-fill-mode, prefers-reduced-motion, will-change, cubic-bezier, linear(), @property, steps(), transform-origin

**Applies to:**

• State-change motion driven by a pseudo-class, a data attribute or a toggled class
• Autonomous motion — spinners, pulses, shimmer, attention cues
• Scroll-linked and viewport-entry progress
• Entrance and exit motion whose trigger is a class or attribute the page already sets

**Handled elsewhere:**

• Playback control at runtime — pause, reverse, seek, or read progress. A CSS declaration exposes no

handle; the Web Animations API is where one comes from, either `element.animate()` or `element.getAnimations()` over what CSS already declared

• Motion whose velocity carries across an interruption, such as a spring picked up mid-gesture
• Pointer-tracking drag, where the animated value is the pointer position itself
• Compositing an outgoing and an incoming view together across a navigation or view swap

---

<decision_framework>

Easing selection

Element entering        -> ease-out (fast start, slow settle)
Element exiting         -> ease-in (slow start, fast departure)
Symmetric motion        -> ease-in-out
Continuous rotation     -> linear
Playful, overshooting   -> cubic-bezier with a control point past 1
Anything else           -> ease-out

`ease`, the browser default, is generic enough that two adjacent animations using it read as unrelated; name the curve instead.

What CSS expresses

• **Scroll and viewport progress** — `animation-timeline: scroll()` or `view()`, with

`animation-range` deciding where progress starts and ends

• **Sequencing across elements** — `animation-delay` computed from an `--index` custom property, with

`backwards` fill so the pre-animation state holds during the delay

• **Values computed at runtime** — write them into a custom property; the animation itself stays

declarative and reads the property each frame

• **Overshoot and arbitrary curves** — a `cubic-bezier` past the 0–1 range, or `linear()` with a

point list for a curve no cubic can express

</decision_framework>

---

<patterns>

Core patterns

Pattern 1: Animation Token System

Durations, easings and travel distances defined once as custom properties, so motion stays consistent across components and is retunable in one place.

:root {
  --duration-fast: 150ms;
  --duration-normal: 250ms;
  --ease-out: cubic-bezier(0, 0, 0.2, 1); /* enter */
  --ease-in: cubic-bezier(0.4, 0, 1, 1); /* exit */
  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275); /* overshoot */
  --lift-md: -4px;
}

Full code: [examples/core.md](examples/core.md)

---

Pattern 2: Compositor-Only Transitions

Name each property being transitioned, and express movement and size as `transform` so no frame triggers layout.

.card {
  transition:
    transform var(--duration-fast) var(--ease-out),
    opacity var(--duration-fast) var(--ease-out);
}
.card:hover {
  transform: translateY(var(--lift-md)) scale(1.02);
}

`translate()` replaces `top`/`left`, `scale()` replaces `width`/`height`, and a pseudo-elem