CSS Animation Patterns
Overview
CSS animations and transitions provide hardware-accelerated motion for web interfaces using keyframes, transitions, transforms, and modern scroll-driven and view transition APIs. Animate only composite properties (transform, opacity, filter) for smooth 60fps performance, and always respect prefers-reduced-motion.
The browser rendering pipeline has four stages: Style, Layout, Paint, and Composite. Animating composite-only properties skips Layout and Paint entirely, running on the GPU compositor thread. This is the single most important performance principle for CSS animation.
Modern CSS adds two powerful APIs: scroll-driven animations link keyframe progress to scroll position or element visibility instead of time, and the View Transitions API creates snapshot-based animated transitions between DOM states for both SPAs and MPAs.
When to use: Element state changes, page transitions, scroll-linked effects, loading indicators, micro-interactions, route change animations, reveal-on-scroll patterns, parallax effects, progress indicators tied to scroll.
When NOT to use: Complex physics simulations (use a JS animation library), canvas/WebGL rendering, animations requiring frame-by-frame scripted control (use Web Animations API directly), highly interactive drag-and-drop (use pointer events with JS).
Browser Support Summary
| Feature |
Chrome |
Firefox |
Safari |
| Transitions, keyframes, transforms |
Full |
Full |
Full |
| Individual transform properties |
104+ |
72+ |
14.1+ |
@starting-style |
117+ |
129+ |
17.5+ |
transition-behavior: allow-discrete |
117+ |
129+ |
17.4+ |
| Scroll-driven animations |
115+ |
Not yet |
26+ |
| Same-document view transitions |
111+ |
144+ |
18+ |
| Cross-document view transitions |
126+ |
Not yet |
18+ |
view-transition-class |
125+ |
144+ |
18+ |
Use @supports for progressive enhancement with newer features. Always provide a functional non-animated fallback.
Quick Reference
| Pattern |
API |
Key Points |
| State transition |
transition: property duration easing |
Triggers on property change, composite-only for performance |
| Discrete transition |
transition-behavior: allow-discrete |
Enables transitions on display, visibility |
| Entry animation |
@starting-style { ... } |
Initial state for elements appearing in DOM |
| Keyframe animation |
@keyframes name + animation shorthand |
Multi-step sequences, supports forwards fill mode |
| Transform |
transform: translate() scale() rotate() |
GPU-composited, no layout recalculation |
| Individual transforms |
translate, rotate, scale |
Independently animatable with different timings |
| Scroll progress |
animation-timeline: scroll() |
Links animation to scroll position of a container |
| View progress |
animation-timeline: view() |
Links animation to element visibility in scrollport |
| Animation range |
animation-range: entry 0% entry 100% |
Controls which timeline segment drives animation |
| Named scroll timeline |
scroll-timeline-name + scroll-timeline-axis |
Reusable scroll timeline across elements |
| Named view timeline |
view-timeline-name + view-timeline-axis |
Reusable view timeline for visibility tracking |
| View transition (SPA) |
document.startViewTransition(callback) |
Snapshot-based animated DOM updates |
| View transition (MPA) |
@view-transition { navigation: auto } |
Cross-document transitions, same-origin only |
| Transition naming |
view-transition-name: hero |
Identifies elements for independent transition groups |
| Transition classes |
view-transition-class: card |
Groups named elements for shared transition styles |
| Transition types |
startViewTransition({ types: [...] }) |
Conditional styling based on navigation direction |
| GPU hint |
will-change: transform |
Promotes element to compositor layer, use sparingly |
| Motion preference |
@media (prefers-reduced-motion: reduce) |
Disable or simplify animations for accessibility |
| Custom easing |
cubic-bezier() or linear() |
Fine-tuned timing curves, linear() for multi-point easing |
| Step easing |
steps(n, jump-term) |
Frame-by-frame discrete animation |
| Animation composition |
animation-composition: accumulate |
Controls how multiple animations combine on same property |
| Staggered delay |
animation-delay: calc(var(--i) * 60ms) |
Per-element delay using CSS custom properties |
| Render containment |
contain: layout style |
Isolates rendering scope for better animation perf |
| Content visibility |
content-visibility: auto |
Skips rendering of off-screen content |
Common Mistakes
| Mistake |
Correct Pattern |
Animating width, height, top, left |
Use transform: translate() and scale() for layout-free animation |
Adding will-change to every element |
Apply only to elements that animate frequently, remove after animation |
Missing prefers-reduced-motion handling |
Wrap motion in @media (prefers-reduced-motion: no-preference) |
Using translateZ(0) hack everywhere |
Use will-change instead, and only when needed |
Declaring animation-timeline before animation shorthand |
Declare animation-timeline after animation (shorthand resets it to auto) |
Setting animation-duration for scroll-driven animations |
Duration is scroll-controlled; use auto or omit, set 1ms for Firefox compat |
Forgetting view-transition-name must be unique |
Each participating element needs a distinct name per page snapshot |
| Not providing fallbacks for scroll-driven animations |
Use @supports (animation-timeline: scroll()) for progressive enhancement |
Animating background-color expecting GPU compositing |
Only transform, opacity, and filter are reliably GPU-composited |
Using transition: all |
Specify exact properties to avoid unexpected transitions and performance hits |
| Interleaving DOM reads and writes in JS animations |
Batch reads first, then writes, or use requestAnimationFrame |
Not using flushSync with React view transitions |
React batches updates; wrap navigate() in flushSync inside the callback |
Calling startViewTransition without feature check |
Always guard with if (!document.startViewTransition) fallback |
Delegation
- Animation implementation: Use
Explore agent to discover patterns in reference files
- Performance audit: Use
Task agent to review animation performance across components
- Accessibility review: Use
Task agent to verify prefers-reduced-motion coverage
- Code review: Delegate to
code-reviewer agent for animation-related PR reviews
If the ux-designer skill is available, delegate visual motion design decisions to it.
Otherwise, recommend: npx skills add oakoss/agent-skills --skill ux-designer
References
- Transitions, keyframes, and animation properties
- Transforms and performance optimization
- Scroll-driven animations
- View Transitions API
1---
2name: css-animation-patterns
3description: >
4 CSS animations, transitions, keyframes, and modern motion APIs. Use when adding animations, transitions,
5 scroll-driven effects, or view transitions. Use for css-animation, transition, keyframes, view-transitions,
6 scroll-animation, transform, motion-preference, animation-timeline.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.0'
11 source: 'https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations'
12user-invocable: false
13---
14
15# CSS Animation Patterns
16
17## Overview
18
19CSS animations and transitions provide hardware-accelerated motion for web interfaces using keyframes, transitions, transforms, and modern scroll-driven and view transition APIs. Animate only composite properties (`transform`, `opacity`, `filter`) for smooth 60fps performance, and always respect `prefers-reduced-motion`.
20
21The browser rendering pipeline has four stages: Style, Layout, Paint, and Composite. Animating composite-only properties skips Layout and Paint entirely, running on the GPU compositor thread. This is the single most important performance principle for CSS animation.
22
23Modern CSS adds two powerful APIs: **scroll-driven animations** link keyframe progress to scroll position or element visibility instead of time, and the **View Transitions API** creates snapshot-based animated transitions between DOM states for both SPAs and MPAs.
24
25**When to use:** Element state changes, page transitions, scroll-linked effects, loading indicators, micro-interactions, route change animations, reveal-on-scroll patterns, parallax effects, progress indicators tied to scroll.
26
27**When NOT to use:** Complex physics simulations (use a JS animation library), canvas/WebGL rendering, animations requiring frame-by-frame scripted control (use Web Animations API directly), highly interactive drag-and-drop (use pointer events with JS).
28
29## Browser Support Summary
30
31| Feature | Chrome | Firefox | Safari |
32| ------------------------------------- | ------ | ------- | ------ |
33| Transitions, keyframes, transforms | Full | Full | Full |
34| Individual transform properties | 104+ | 72+ | 14.1+ |
35| `@starting-style` | 117+ | 129+ | 17.5+ |
36| `transition-behavior: allow-discrete` | 117+ | 129+ | 17.4+ |
37| Scroll-driven animations | 115+ | Not yet | 26+ |
38| Same-document view transitions | 111+ | 144+ | 18+ |
39| Cross-document view transitions | 126+ | Not yet | 18+ |
40| `view-transition-class` | 125+ | 144+ | 18+ |
41
42Use `@supports` for progressive enhancement with newer features. Always provide a functional non-animated fallback.
43
44## Quick Reference
45
46| Pattern | API | Key Points |
47| --------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
48| State transition | `transition: property duration easing` | Triggers on property change, composite-only for performance |
49| Discrete transition | `transition-behavior: allow-discrete` | Enables transitions on `display`, `visibility` |
50| Entry animation | `@starting-style { ... }` | Initial state for elements appearing in DOM |
51| Keyframe animation | `@keyframes name` + `animation` shorthand | Multi-step sequences, supports `forwards` fill mode |
52| Transform | `transform: translate() scale() rotate()` | GPU-composited, no layout recalculation |
53| Individual transforms | `translate`, `rotate`, `scale` | Independently animatable with different timings |
54| Scroll progress | `animation-timeline: scroll()` | Links animation to scroll position of a container |
55| View progress | `animation-timeline: view()` | Links animation to element visibility in scrollport |
56| Animation range | `animation-range: entry 0% entry 100%` | Controls which timeline segment drives animation |
57| Named scroll timeline | `scroll-timeline-name` + `scroll-timeline-axis` | Reusable scroll timeline across elements |
58| Named view timeline | `view-timeline-name` + `view-timeline-axis` | Reusable view timeline for visibility tracking |
59| View transition (SPA) | `document.startViewTransition(callback)` | Snapshot-based animated DOM updates |
60| View transition (MPA) | `@view-transition { navigation: auto }` | Cross-document transitions, same-origin only |
61| Transition naming | `view-transition-name: hero` | Identifies elements for independent transition groups |
62| Transition classes | `view-transition-class: card` | Groups named elements for shared transition styles |
63| Transition types | `startViewTransition({ types: [...] })` | Conditional styling based on navigation direction |
64| GPU hint | `will-change: transform` | Promotes element to compositor layer, use sparingly |
65| Motion preference | `@media (prefers-reduced-motion: reduce)` | Disable or simplify animations for accessibility |
66| Custom easing | `cubic-bezier()` or `linear()` | Fine-tuned timing curves, `linear()` for multi-point easing |
67| Step easing | `steps(n, jump-term)` | Frame-by-frame discrete animation |
68| Animation composition | `animation-composition: accumulate` | Controls how multiple animations combine on same property |
69| Staggered delay | `animation-delay: calc(var(--i) * 60ms)` | Per-element delay using CSS custom properties |
70| Render containment | `contain: layout style` | Isolates rendering scope for better animation perf |
71| Content visibility | `content-visibility: auto` | Skips rendering of off-screen content |
72
73## Common Mistakes
74
75| Mistake | Correct Pattern |
76| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
77| Animating `width`, `height`, `top`, `left` | Use `transform: translate()` and `scale()` for layout-free animation |
78| Adding `will-change` to every element | Apply only to elements that animate frequently, remove after animation |
79| Missing `prefers-reduced-motion` handling | Wrap motion in `@media (prefers-reduced-motion: no-preference)` |
80| Using `translateZ(0)` hack everywhere | Use `will-change` instead, and only when needed |
81| Declaring `animation-timeline` before `animation` shorthand | Declare `animation-timeline` after `animation` (shorthand resets it to `auto`) |
82| Setting `animation-duration` for scroll-driven animations | Duration is scroll-controlled; use `auto` or omit, set `1ms` for Firefox compat |
83| Forgetting `view-transition-name` must be unique | Each participating element needs a distinct name per page snapshot |
84| Not providing fallbacks for scroll-driven animations | Use `@supports (animation-timeline: scroll())` for progressive enhancement |
85| Animating `background-color` expecting GPU compositing | Only `transform`, `opacity`, and `filter` are reliably GPU-composited |
86| Using `transition: all` | Specify exact properties to avoid unexpected transitions and performance hits |
87| Interleaving DOM reads and writes in JS animations | Batch reads first, then writes, or use `requestAnimationFrame` |
88| Not using `flushSync` with React view transitions | React batches updates; wrap `navigate()` in `flushSync` inside the callback |
89| Calling `startViewTransition` without feature check | Always guard with `if (!document.startViewTransition)` fallback |
90
91## Delegation
92
93- **Animation implementation**: Use `Explore` agent to discover patterns in reference files
94- **Performance audit**: Use `Task` agent to review animation performance across components
95- **Accessibility review**: Use `Task` agent to verify `prefers-reduced-motion` coverage
96- **Code review**: Delegate to `code-reviewer` agent for animation-related PR reviews
97
98> If the `ux-designer` skill is available, delegate visual motion design decisions to it.
99> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill ux-designer`
100
101## References
102
103- [Transitions, keyframes, and animation properties](references/transitions-and-keyframes.md)
104- [Transforms and performance optimization](references/transforms-and-performance.md)
105- [Scroll-driven animations](references/scroll-driven.md)
106- [View Transitions API](references/view-transitions.md)
oakoss