Animate

Next.js Animations

Overview

This skill provides comprehensive guidance for implementing smooth, performant, and accessible animations in Next.js and React applications. It covers CSS animations, Framer Motion, easing principles, and accessibility considerations.

Quick Reference

Easing Cheat Sheet

CSS Custom Properties (Recommended)

:root {
  --ease-out-quint: cubic-bezier(.23, 1, .32, 1);
  --ease-in-out-cubic: cubic-bezier(.645, .045, .355, 1);
  --ease-out-cubic: cubic-bezier(.33, 1, .68, 1);
}

Common Animation Patterns

1. Hover Lift Effect

.card {
  transition: transform 200ms var(--ease-out-quint),
              box-shadow 200ms var(--ease-out-quint);
}
.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15);
}

2. Button Press

.button {
  transition: transform 100ms ease-out;
}
.button:active {
  transform: scale(0.97);
}

3. Fade In on Mount (Framer Motion)

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.3, ease: [.23, 1, .32, 1] }}
>
  Content
</motion.div>

4. Modal with Exit Animation

<AnimatePresence>
  {isOpen && (
    <motion.div
      initial={{ opacity: 0, scale: 0.95 }}
      animate={{ opacity: 1, scale: 1 }}
      exit={{ opacity: 0, scale: 0.95 }}
      transition={{ duration: 0.2, ease: "easeOut" }}
    >
      {children}
    </motion.div>
  )}
</AnimatePresence>

5. Tab Indicator (Shared Layout)

{tabs.map(tab => (
  <button key={tab} onClick={() => setActive(tab)} className="relative px-4 py-2">
    {tab}
    {active === tab && (
      <motion.div
        layoutId="tab-indicator"
        className="absolute inset-0 bg-blue-500 rounded -z-10"
        transition={{ type: "spring", stiffness: 400, damping: 30 }}
      />
    )}
  </button>
))}

6. Staggered List Animation

const container = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: { staggerChildren: 0.1 }
  }
}

const item = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 }
}

<motion.ul variants={container} initial="hidden" animate="visible">
  {items.map(i => <motion.li key={i} variants={item}>{i}</motion.li>)}
</motion.ul>

Golden Rules

1. Exits faster than enters: Exit animations should be ~75% of enter duration 2. Only animate transform and opacity: These are GPU-accelerated 3. 200-300ms is the sweet spot: Most animations should be in this range 4. Always respect prefers-reduced-motion: See accessibility section in references 5. Use springs for interruptible animations: Better UX when users interrupt

Examples

Complete working examples from the course are in the examples/ directory:

To use an example, read it with: Read examples/<name>.tsx

References

For detailed documentation, read the reference files:

• references/easing-and-timing.md - Easing functions, timing guidelines, spring configuration
• references/css-animations.md - Transforms, transitions, keyframes, clip-path
• references/framer-motion.md - Motion components, AnimatePresence, variants, layout animations, hooks
• references/performance-accessibility.md - 60fps optimization, prefers-reduced-motion, accessibility

When to Use What

Dependencies

For Framer Motion examples, install:

pnpm add framer-motion react-use-measure usehooks-ts

Animate Skill for Claude Code

Animation patterns and best practices for Next.js/React applications. Based on Emil Kowalski's "Animations on the Web" course.

Installation

npx skills add https://github.com/delphi-ai/animate-skill --skill animate

What's Included

• SKILL.md - Quick reference for easing, timing, and common patterns
• examples/ - 8 complete working examples (hover effects, toasts, modals, etc.)
• references/ - Detailed docs on CSS animations, Framer Motion, performance, accessibility

Usage

Once installed, the skill triggers automatically when you ask Claude Code to implement animations, transitions, hover effects, modals, or any motion in React components.

You can also invoke it directly with /animate.

Examples Included

Dependencies

For Framer Motion examples:

pnpm add framer-motion react-use-measure usehooks-ts

CSS Animations Reference

Transforms

Transforms change an element's position, size, or rotation without affecting layout. They are GPU-accelerated and performant.

Transform Functions

/* Translation (movement) */
transform: translateX(10px);
transform: translateY(-20px);
transform: translate(10px, -20px);  /* X, Y */
transform: translate3d(10px, 20px, 30px);  /* X, Y, Z */

/* Scale */
transform: scale(1.1);  /* Uniform scale */
transform: scaleX(0.5);
transform: scaleY(1.5);
transform: scale(0.5, 1.5);  /* X, Y */

/* Rotation */
transform: rotate(45deg);
transform: rotateX(45deg);  /* 3D - around X axis */
transform: rotateY(45deg);  /* 3D - around Y axis */
transform: rotateZ(45deg);  /* Same as rotate() */

/* Combining transforms */
transform: translateY(-10px) scale(1.05) rotate(5deg);

Transform Origin

Controls the point around which transforms occur:

transform-origin: center;  /* Default */
transform-origin: top left;
transform-origin: 50% 100%;  /* Center bottom */
transform-origin: 0 0;  /* Top left corner */

3D Transforms

/* Enable 3D space on parent */
.parent {
  perspective: 1000px;  /* Distance from viewer */
  perspective-origin: center;
}

/* 3D transforms on children */
.child {
  transform: rotateY(45deg);
  transform-style: preserve-3d;  /* Maintain 3D for nested elements */
  backface-visibility: hidden;  /* Hide back of element */
}

Transitions

Transitions animate property changes over time.

Syntax

/* Individual properties */
transition-property: transform, opacity;
transition-duration: 200ms;
transition-timing-function: ease-out;
transition-delay: 0ms;

/* Shorthand */
transition: transform 200ms ease-out, opacity 150ms ease-out 50ms;
/*          property  duration timing   property duration timing  delay */

Common Transition Patterns

/* Hover lift effect */
.card {
  transition: transform 200ms ease-out, box-shadow 200ms ease-out;
}
.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15);
}

/* Button press effect */
.button {
  transition: transform 100ms ease-out;
}
.button:active {
  transform: scale(0.97);
}

/* Fade in/out */
.element {
  opacity: 0;
  transition: opacity 200ms ease-out;
}
.element.visible {
  opacity: 1;
}

Performance-Safe Properties

These properties are GPU-accelerated and won't cause layout recalculation:

• transform
• opacity

Avoid animating (cause layout/paint):

• width, height
• top, left, right, bottom
• margin, padding
• border-width

Keyframe Animations

For complex, multi-step animations.

Basic Syntax

@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes pulse {
  0%, 100% {
    transform: scale(1);
  }
  50% {
    transform: scale(1.05);
  }
}

.element {
  animation: fadeIn 300ms ease-out forwards;
}

Animation Properties

animation-name: fadeIn;
animation-duration: 300ms;
animation-timing-function: ease-out;
animation-delay: 0ms;
animation-iteration-count: 1;  /* or 'infinite' */
animation-direction: normal;  /* or 'reverse', 'alternate' */
animation-fill-mode: forwards;  /* 'none', 'forwards', 'backwards', 'both' */
animation-play-state: running;  /* or 'paused' */

/* Shorthand */
animation: fadeIn 300ms ease-out 0ms 1 normal forwards;

Fill Modes Explained

• none: No styles applied before/after animation
• forwards: Retains final keyframe styles after animation
• backwards: Applies initial keyframe styles during delay
• both: Applies both forwards and backwards

Clip-Path Animations

Clip-path creates masked areas that can be animated.

Common Shapes

/* Circle */
clip-path: circle(50% at center);
clip-path: circle(0% at center);  /* Hidden */

/* Ellipse */
clip-path: ellipse(50% 30% at center);

/* Inset (rectangle) */
clip-path: inset(0);  /* Full visibility */
clip-path: inset(50%);  /* Hidden (collapsed to center) */
clip-path: inset(0 50% 0 0);  /* Right half hidden */
/* inset(top right bottom left) */

/* Polygon */
clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);  /* Rectangle */
clip-path: polygon(50% 0, 100% 100%, 0 100%);  /* Triangle */

Clip-Path Animation Example (Image Comparison Slider)

.before-image {
  clip-path: inset(0 50% 0 0);  /* Show left half */
  transition: clip-path 0ms;  /* Instant update */
}

/* JavaScript updates the clip-path based on slider position */

Tab Indicator with Clip-Path

// Active tab background slides using clip-path
<div className="relative">
  {tabs.map((tab, index) => (
    <button
      key={tab}
      onClick={() => setActive(index)}
      className="relative z-10 px-4 py-2"
    >
      {tab}
    </button>
  ))}
  <div
    className="absolute inset-0 bg-blue-500 rounded transition-all duration-200"
    style={{
      clipPath: `inset(0 ${100 - (activeIndex + 1) * (100 / tabs.length)}% 0 ${activeIndex * (100 / tabs.length)}% round 8px)`
    }}
  />
</div>

Easing and Timing Reference

Core Principles

Animations should feel natural and purposeful. The goal is to make interfaces feel responsive without drawing attention to the animation itself.

Easing Functions

When to Use Each Easing Type

Custom Easing Variables

Define these CSS custom properties for consistent animations:

:root {
  /* Recommended easing curves */
  --ease-out-quint: cubic-bezier(.23, 1, .32, 1);
  --ease-in-out-cubic: cubic-bezier(.645, .045, .355, 1);
  --ease-out-cubic: cubic-bezier(.33, 1, .68, 1);
  --ease-in-cubic: cubic-bezier(.32, 0, .67, 0);

  /* Spring-like feel */
  --ease-out-back: cubic-bezier(.34, 1.56, .64, 1);
}

Cubic Bezier Explained

cubic-bezier(x1, y1, x2, y2) defines a curve with two control points:

• (x1, y1) - First control point (influences start of animation)
• (x2, y2) - Second control point (influences end of animation)

Values > 1 create overshoot effects (like ease-out-back).

Timing Guidelines

Duration Sweet Spots

• General animations: 200-300ms (the sweet spot)
• Hover effects: 150ms
• Modal enter: 200ms
• Modal exit: 150ms (exits should be faster than enters)
• Page transitions: 300-400ms
• Micro-interactions: 100-150ms

Rules of Thumb

1. Exits faster than enters: Exit animations should be ~75% of enter duration 2. Smaller elements = faster animations: Scale duration with element size 3. User-initiated = faster response: Direct actions should feel immediate 4. System-initiated = can be slower: Background transitions can take longer

Spring Animations

Springs are excellent for interruptible animations and natural-feeling motion.

Spring Parameters

Framer Motion Spring Config

// Snappy spring (UI elements)
const snappy = { type: "spring", stiffness: 400, damping: 30 }

// Gentle spring (larger elements)
const gentle = { type: "spring", stiffness: 200, damping: 20 }

// Bouncy spring (playful interactions)
const bouncy = { type: "spring", stiffness: 300, damping: 10 }

Duration-Based Springs (Framer Motion)

// Using duration instead of physics
const durationSpring = {
  type: "spring",
  duration: 0.3,
  bounce: 0.2  // 0 = no bounce, 1 = max bounce
}

When NOT to Animate

• Loading states that block interaction
• Error messages that need immediate attention
• Accessibility: respect prefers-reduced-motion
• When animation adds no value to the experience
• Repeated actions the user performs frequently

Framer Motion Reference

Framer Motion is the recommended animation library for React/Next.js applications.

Installation

npm install framer-motion
# or
pnpm add framer-motion

Basic Usage

Motion Components

import { motion } from "framer-motion"

// Any HTML element can become animated
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.3, ease: "easeOut" }}
>
  Content
</motion.div>

Common Props

AnimatePresence

Required for exit animations. Wraps elements that may be removed from DOM.

import { motion, AnimatePresence } from "framer-motion"

function Modal({ isOpen, onClose, children }) {
  return (
    <AnimatePresence>
      {isOpen && (
        <motion.div
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
          transition={{ duration: 0.2 }}
        >
          {children}
        </motion.div>
      )}
    </AnimatePresence>
  )
}

AnimatePresence Props

<AnimatePresence
  mode="wait"      // 'sync' | 'wait' | 'popLayout'
  initial={false}  // Disable initial animation on mount
  onExitComplete={() => {}}  // Callback when all exits complete
>

• mode="sync" (default): Enter and exit happen simultaneously
• mode="wait": Wait for exit to complete before enter
• mode="popLayout": Remove exiting elements from layout flow

Variants

Variants define animation states that can be orchestrated across parent/children.

const containerVariants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.1,  // Delay between each child
      delayChildren: 0.2,    // Initial delay before children start
    }
  }
}

const itemVariants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 }
}

function List({ items }) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
    >
      {items.map(item => (
        <motion.li key={item.id} variants={itemVariants}>
          {item.name}
        </motion.li>
      ))}
    </motion.ul>
  )
}

Layout Animations

Animate layout changes automatically with the layout prop.

// Element animates when its position/size changes
<motion.div layout>
  {isExpanded ? "Expanded content here" : "Collapsed"}
</motion.div>

// Layout types
<motion.div layout>  // Animate position and size
<motion.div layout="position">  // Only animate position
<motion.div layout="size">  // Only animate size

Shared Layout Animations (layoutId)

Elements with the same layoutId animate between each other.

function Tabs({ tabs, activeTab, setActiveTab }) {
  return (
    <div className="flex gap-2">
      {tabs.map(tab => (
        <button
          key={tab}
          onClick={() => setActiveTab(tab)}
          className="relative px-4 py-2"
        >
          {tab}
          {activeTab === tab && (
            <motion.div
              layoutId="tab-indicator"
              className="absolute inset-0 bg-blue-500 rounded -z-10"
              transition={{ type: "spring", stiffness: 400, damping: 30 }}
            />
          )}
        </button>
      ))}
    </div>
  )
}

LayoutGroup

Group layout animations to prevent conflicts between independent animations.

import { LayoutGroup } from "framer-motion"

<LayoutGroup>
  <Tabs />  {/* These layout animations */}
</LayoutGroup>
<LayoutGroup>
  <OtherTabs />  {/* Won't conflict with these */}
</LayoutGroup>

Gestures

Drag

<motion.div
  drag              // Enable both axes
  drag="x"          // Horizontal only
  drag="y"          // Vertical only
  dragConstraints={{ left: 0, right: 300, top: 0, bottom: 200 }}
  dragElastic={0.2}     // Elasticity outside constraints (0-1)
  dragMomentum={true}   // Continue after release
  dragTransition={{ bounceStiffness: 600, bounceDamping: 20 }}
  onDragStart={(event, info) => {}}
  onDrag={(event, info) => {}}
  onDragEnd={(event, info) => {}}
>
  Drag me
</motion.div>

Drag Info Object

onDrag={(event, info) => {
  info.point    // { x, y } current position
  info.delta    // { x, y } change since last frame
  info.offset   // { x, y } offset from drag start
  info.velocity // { x, y } current velocity
}}

Motion Values & Hooks

useMotionValue

Create a value that updates without re-rendering.

import { motion, useMotionValue, useTransform } from "framer-motion"

function Component() {
  const x = useMotionValue(0)

  // Transform x position to opacity
  const opacity = useTransform(x, [-100, 0, 100], [0, 1, 0])

  // Transform x to rotation
  const rotate = useTransform(x, [-100, 100], [-10, 10])

  return (
    <motion.div
      drag="x"
      style={{ x, opacity, rotate }}
    />
  )
}

useSpring

Create a spring-animated motion value.

import { useSpring, useMotionValue } from "framer-motion"

function Component() {
  const x = useMotionValue(0)
  const springX = useSpring(x, { stiffness: 300, damping: 30 })

  return (
    <motion.div
      onMouseMove={(e) => x.set(e.clientX)}
      style={{ x: springX }}
    />
  )
}

useScroll

Track scroll progress.

import { useScroll, useTransform, motion } from "framer-motion"

function ProgressBar() {
  const { scrollYProgress } = useScroll()

  return (
    <motion.div
      className="fixed top-0 left-0 right-0 h-1 bg-blue-500 origin-left"
      style={{ scaleX: scrollYProgress }}
    />
  )
}

// Scroll within a container
const { scrollYProgress } = useScroll({
  target: containerRef,
  offset: ["start end", "end start"]  // When to start/end tracking
})

useInView

Detect when element enters viewport.

import { useInView } from "framer-motion"

function Component() {
  const ref = useRef(null)
  const isInView = useInView(ref, {
    once: true,      // Only trigger once
    margin: "-100px" // Trigger 100px before entering
  })

  return (
    <motion.div
      ref={ref}
      initial={{ opacity: 0, y: 50 }}
      animate={isInView ? { opacity: 1, y: 0 } : {}}
    />
  )
}

Transition Options

const transition = {
  // Timing
  duration: 0.3,
  delay: 0.1,

  // Easing
  ease: "easeOut",  // or array: [0.23, 1, 0.32, 1]

  // Spring physics
  type: "spring",
  stiffness: 400,
  damping: 30,
  mass: 1,

  // Or duration-based spring
  type: "spring",
  duration: 0.3,
  bounce: 0.2,

  // Per-property transitions
  opacity: { duration: 0.2 },
  x: { type: "spring", stiffness: 300 },

  // Repeat
  repeat: Infinity,
  repeatType: "reverse",  // "loop" | "reverse" | "mirror"
  repeatDelay: 0.5,
}

Multi-Step Animations (Keyframes)

<motion.div
  animate={{
    x: [0, 100, 0],           // Move right then back
    opacity: [0, 1, 1, 0],    // Fade in, stay, fade out
    scale: [1, 1.2, 1],       // Grow then shrink
  }}
  transition={{
    duration: 2,
    times: [0, 0.5, 1],       // When each keyframe occurs (0-1)
    ease: "easeInOut",
  }}
/>

Performance & Accessibility Reference

Performance

Target: 60 FPS

Animations should run at 60 frames per second (16.67ms per frame) for smooth motion.

GPU-Accelerated Properties

Only these properties are hardware-accelerated and won't cause layout recalculation:

Properties to Avoid Animating

These trigger layout recalculation and are expensive:

• width, height
• top, left, right, bottom
• margin, padding
• border-width
• font-size

Instead: Use transform: scale() instead of width/height, transform: translate() instead of top/left.

will-change

Hints to the browser that an element will animate:

.will-animate {
  will-change: transform, opacity;
}

Caution: Use sparingly. Apply only to elements that actually animate, and remove after animation completes if possible. Overuse can hurt performance.

Hardware Acceleration Hack

Force GPU layer creation (use sparingly):

.force-gpu {
  transform: translateZ(0);
  /* or */
  backface-visibility: hidden;
}

Monitoring Performance

1. Chrome DevTools: Performance tab → Record during animation 2. Rendering tab: Enable "FPS meter" and "Paint flashing" 3. Layers panel: Check layer composition

Common Performance Issues

Accessibility

prefers-reduced-motion

Users can indicate they prefer reduced motion in their system settings. Always respect this preference.

CSS Implementation

/* Full animation by default */
.element {
  transition: transform 300ms ease-out;
}

/* Reduced or no motion for users who prefer it */
@media (prefers-reduced-motion: reduce) {
  .element {
    transition: none;
    /* or minimal transition */
    transition: opacity 200ms ease-out;
  }
}

React/Framer Motion Implementation

import { useReducedMotion } from "framer-motion"

function AnimatedComponent() {
  const shouldReduceMotion = useReducedMotion()

  return (
    <motion.div
      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: shouldReduceMotion ? 0 : 0.3 }}
    />
  )
}

Global Configuration with MotionConfig

import { MotionConfig, useReducedMotion } from "framer-motion"

function App() {
  const shouldReduceMotion = useReducedMotion()

  return (
    <MotionConfig reducedMotion={shouldReduceMotion ? "always" : "never"}>
      {/* All motion components inside respect this setting */}
      <YourApp />
    </MotionConfig>
  )
}

MotionConfig Options

Accessible Animation Guidelines

1. Provide alternatives: Ensure content is accessible without animation 2. Avoid flashing: No content flashing more than 3 times per second 3. Don't block interaction: Animations shouldn't prevent users from interacting 4. Keep it brief: Long animations can be frustrating 5. Purposeful motion: Only animate when it adds value 6. Pause controls: For continuous animations, provide pause/stop

Focus Management with Animations

// Ensure focus moves appropriately with animated elements
function Modal({ isOpen }) {
  const modalRef = useRef(null)

  useEffect(() => {
    if (isOpen) {
      // Wait for enter animation before focusing
      const timer = setTimeout(() => {
        modalRef.current?.focus()
      }, 300)
      return () => clearTimeout(timer)
    }
  }, [isOpen])

  return (
    <AnimatePresence>
      {isOpen && (
        <motion.div
          ref={modalRef}
          tabIndex={-1}
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
        >
          Modal content
        </motion.div>
      )}
    </AnimatePresence>
  )
}

Testing Reduced Motion

1. macOS: System Preferences → Accessibility → Display → Reduce motion 2. Windows: Settings → Ease of Access → Display → Show animations 3. iOS: Settings → Accessibility → Motion → Reduce Motion 4. Chrome DevTools: Rendering tab → Emulate CSS media feature prefers-reduced-motion