/web-animation-css-animations

name: web-animation-css-animations
description: CSS Animation patterns - transitions, keyframes, scroll-driven animations, @property, GPU-accelerated properties, accessibility with prefers-reduced-motion

CSS Animation Patterns

> **Quick Guide:** Use CSS transitions for state changes (hover, focus), `@keyframes` for autonomous/looping animations, scroll-driven animations for scroll-linked effects. Animate only `transform` and `opacity` for 60fps. Always respect `prefers-reduced-motion`.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST animate ONLY transform and opacity for GPU-accelerated 60fps performance)**

**(You MUST respect prefers-reduced-motion using @media (prefers-reduced-motion: no-preference) for opt-in or @media (prefers-reduced-motion: reduce) for opt-out)**

**(You MUST use CSS custom properties for ALL timing values - NO magic numbers like `0.3s`)**

**(You MUST use ease-out for enter animations and ease-in for exit animations - NEVER linear for UI transitions)**

**(You MUST remove will-change after animation completes - permanent will-change wastes GPU memory)**

</critical_requirements>

---

**Auto-detection:** CSS animation, CSS transition, @keyframes, transform, opacity, transition-duration, animation-duration, prefers-reduced-motion, scroll-timeline, animation-timeline, will-change, cubic-bezier, ease-out, ease-in, @property

**When to use:**

• Simple state change animations (hover, focus, active states)
• Autonomous looping animations (spinners, pulses, attention grabbers)
• Scroll-linked animations and parallax effects
• Micro-interactions that don't need JavaScript control

**When NOT to use:**

• Animations requiring JavaScript control (pause, reverse, seek) -- use Web Animations API
• Complex orchestrated animations with staggered timing -- use your animation library
• Physics-based spring animations -- use your animation library
• Drag-and-drop or gesture-driven animations -- use your animation library

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Token system, interactive states, shadows, loading, reduced motion
• [examples/transitions.md](examples/transitions.md) - Multi-property transitions, accordions, color, links
• [examples/keyframes.md](examples/keyframes.md) - Scroll-driven, @property gradients, typewriter, stagger, shapes
• [reference.md](reference.md) - Decision frameworks, timing reference, browser support

---

<philosophy>

Philosophy

CSS animations leverage the browser's compositor thread for smooth, 60fps animations that don't block JavaScript execution. By animating only GPU-accelerated properties (`transform` and `opacity`), animations run on a separate thread from the main JavaScript thread.

**Core principles:**

1. **Performance first** - Animate only `transform` and `opacity` to avoid layout/paint triggers 2. **Accessibility built-in** - Always respect `prefers-reduced-motion` user preferences 3. **Transitions for state changes** - Use CSS transitions for hover, focus, and state-driven animations 4. **Keyframes for autonomous motion** - Use `@keyframes` for animations that loop, auto-play, or have multiple steps 5. **Design tokens for consistency** - Use CSS custom properties for durations, easings, and distances

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Animation Token System

Define timing, easing, and distance tokens as CSS custom properties for consistency. See [examples/core.md](examples/core.md) for the full token setup.

:root {
  --duration-instant: 100ms;
  --duration-fast: 150ms;
  --duration-normal: 250ms;
  --duration-slow: 400ms;

  --ease-out: cubic-bezier(0, 0, 0.2, 1); /* Enter */
  --ease-in: cubic-bezier(0.4, 0, 1, 1); /* Exit */
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); /* Symmetric */
  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275); /* Bouncy */

  --lift-sm: -2px;
  --lift-md: -4px;
}

**Why tokens matter:** Consistent timing across application, easy to adjust globally, semantic naming communicates intent

---

Pattern 2: GPU-Accelerated Transitions

Only animate `transform` and `opacity`. Never animate layout properties like `width`, `height`, `top`, `left`, `margin`, or `padding`.

/* CORRECT - GPU-accelerated */
.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);
}

/* WRONG - triggers layout recalculation every frame */
.card {
  transition: all 0.3s linear;
}
.card:hover {
  top: -8px;
  margin-top: -8px;
}

**Transform mapping:** Use `translate()` instead of `top/left`, `scale()` instead of `width/height`, pseudo-element opacity instead of `box-shadow`.

See [examples/core.md](examples/core.md) for button states, card hover effects, and the pseudo-element shadow technique.

---

Pattern 3: Prefers-Reduced-Motion

Every animation must respect user motion preferences. Two strategies:

Progressive Enhancement (Recommended)

/* Base: no motion */
.element {
  opacity: 1;
  transform: translateY(0);
}

/* Opt-in to motion */
@media (prefers-reduced-motion: no-preference) {
  .element {
    animation: fade-slide-in var(--duration-normal) var(--ease-out);
  }
}

Graceful Degradation

.notification {
  animation: slide-in-bounce var(--notification-duration) var(--ease-spring);
}

@media (prefers-reduced-motion: reduce) {
  .notification {
    animation: fade-in calc(var(--notification-duration) * 0.5) var(--ease-out);
  }
}

**Key insight:** Reduced motion does not mean no animation. Opacity fades are generally safe. Replace spatial movement with opacity-only alternatives.

See [examples/core.md](examples/core.md) for the complete reduced motion pattern.

---

Patt