web-animation-design

SKILL.md

Web Animation Design

A comprehensive guide for creating animations that feel right, based on Emil Kowalski's "Animations on the Web" course.

Initial Response

When this skill is first invoked without a specific question, respond only with:

I'm ready to help you with animations based on Emil Kowalski's animations.dev course.

Do not provide any other information until the user asks a question.

Review Format (Required)

When reviewing animations, you MUST use a markdown table. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:

Before
After

transform: scale(0)
transform: scale(0.95)

animation: fadeIn 400ms ease-in
animation: fadeIn 200ms ease-out

No reduced motion support
@media (prefers-reduced-motion: reduce) {...}

Wrong format (never do this):

Before: transform: scale(0)
After: transform: scale(0.95)
────────────────────────────
Before: 400ms duration
After: 200ms

Correct format: A single markdown table with | Before | After | columns, one row per issue.

Quick Start

Every animation decision starts with these questions:

Is this element entering or exiting? → Use ease-out

Is an on-screen element moving? → Use ease-in-out

Is this a hover/color transition? → Use ease

Will users see this 100+ times daily? → Don't animate it

The Easing Blueprint

ease-out (Most Common)

Use for user-initiated interactions: dropdowns, modals, tooltips, any element entering or exiting the screen.

/* Sorted weak to strong */
--ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
--ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
--ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
--ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
--ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
--ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);

Why it works: Acceleration at the start creates an instant, responsive feeling. The element "jumps" toward its destination then settles in.

ease-in-out (For Movement)

Use when elements already on screen need to move or morph. Mimics natural motion like a car accelerating then braking.

/* Sorted weak to strong */
--ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
--ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
--ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
--ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
--ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
--ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);

ease (For Hover Effects)

Use for hover states and color transitions. The asymmetrical curve (faster start, slower end) feels elegant for gentle animations.

transition: background-color 150ms ease;

linear (Avoid in UI)

Only use for:

Constant-speed animations (marquees, tickers)

Time visualization (hold-to-delete progress indicators)

Linear feels robotic and unnatural for interactive elements.

ease-in (Almost Never)

Avoid for UI animations. Makes interfaces feel sluggish because the slow start delays visual feedback.

Paired Elements Rule

Elements that animate together must use the same easing and duration. Modal + overlay, tooltip + arrow, drawer + backdrop—if they move as a unit, they should feel like a unit.

/* Both use the same timing */
.modal { transition: transform 200ms ease-out; }
.overlay { transition: opacity 200ms ease-out; }

Timing and Duration

Duration Guidelines

Element Type
Duration

Micro-interactions
100-150ms

Standard UI (tooltips, dropdowns)
150-250ms

Modals, drawers
200-300ms

Page transitions
300-400ms

Rule: UI animations should stay under 300ms. Larger elements animate slower than smaller ones.

The Frequency Principle

Determine how often users will see the animation:

100+ times/day → No animation (or drastically reduced)

Occasional use → Standard animation

Rare/first-time → Can add delight

Example: Raycast never animates its menu toggle because users open it hundreds of times daily.

When to Animate

Do animate:

Enter/exit transitions for spatial consistency

State changes that benefit from visual continuity

Responses to user actions (feedback)

Rarely-used interactions where delight adds value

Don't animate:

Keyboard-initiated actions

Hover effects on frequently-used elements

Anything users interact with 100+ times daily

When speed matters more than smoothness

Marketing vs. Product:

Marketing: More elaborate, longer durations allowed

Product: Fast, purposeful, never frivolous

Spring Animations

Springs feel more natural because they don't have fixed durations—they simulate real physics.

When to Use Springs

Drag interactions with momentum

Elements that should feel "alive" (Dynamic Island)

Gestures that can be interrupted mid-animation

Organic, playful interfaces

Configuration

Apple's approach (recommended):

// Duration + bounce (easier to understand)
{ type: "spring", duration: 0.5, bounce: 0.2 }

Traditional physics:

// Mass, stiffness, damping (more complex)
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }

Bounce Guidelines

Avoid bounce in most UI contexts

Use bounce for drag-to-dismiss, playful interactions

Keep bounce subtle (0.1-0.3) when used

Interruptibility

Springs maintain velocity when interrupted—CSS animations restart from zero. This makes springs ideal for gestures users might change mid-motion.

Performance

The Golden Rule

Only animate transform and opacity. These skip layout and paint stages, running entirely on the GPU.

Avoid animating:

padding, margin, height, width (trigger layout)

blur filters above 20px (expensive, especially Safari)

CSS variables in deep component trees

Optimization Techniques

/* Force GPU acceleration */
.animated-element {
  will-change: transform;
}

React-specific:

Animate outside React's render cycle when possible

Use refs to update styles directly instead of state

Re-renders on every frame = dropped frames

Framer Motion:

// Hardware accelerated (transform as string)
<motion.div animate={{ transform: "translateX(100px)" }} />

// NOT hardware accelerated (more readable)
<motion.div animate={{ x: 100 }} />

CSS vs. JavaScript

CSS animations run off main thread (smoother under load)

JS animations (Framer Motion, React Spring) use requestAnimationFrame

CSS better for simple, predetermined animations

JS better for dynamic, interruptible animations

Accessibility

Animations can cause motion sickness or distraction for some users.

prefers-reduced-motion

Whenever you add an animation, also add a media query to disable it:

.modal {
  animation: fadeIn 200ms ease-out;
}

@media (prefers-reduced-motion: reduce) {
  .modal {
    animation: none;
  }
}

Reduced Motion Guidelines

Every animated element needs its own prefers-reduced-motion media query

Set animation: none or transition: none (no !important)

No exceptions for opacity or color - disable all animations

Show play buttons instead of autoplay videos

Framer Motion Implementation

import { useReducedMotion } from "framer-motion";

function Component() {
  const shouldReduceMotion = useReducedMotion();

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

Touch Device Considerations

/* Disable hover animations on touch devices */
@media (hover: hover) and (pointer: fine) {
  .element:hover {
    transform: scale(1.05);
  }
}

Touch devices trigger hover on tap, causing false positives.

Practical Tips

Quick reference for common scenarios. See PRACTICAL-TIPS.md for detailed implementations.

Scenario
Solution

Make buttons feel responsive
Add transform: scale(0.97) on :active

Element appears from nowhere
Start from scale(0.95), not scale(0)

Shaky/jittery animations
Add will-change: transform

Hover causes flicker
Animate child element, not parent

Popover scales from wrong point
Set transform-origin to trigger location

Sequential tooltips feel slow
Skip delay/animation after first tooltip

Small buttons hard to tap
Use 44px minimum hit area (pseudo-element)

Something still feels off
Add subtle blur (under 20px) to mask it

Hover triggers on mobile
Use @media (hover: hover) and (pointer: fine)

Easing Decision Flowchart

Is the element entering or exiting the viewport?
├── Yes → ease-out
└── No
├── Is it moving/morphing on screen?
│ └── Yes → ease-in-out
└── Is it a hover change?
├── Yes → ease
└── Is it constant motion?
├── Yes → linear
└── Default → ease-out

Reference Files

PRACTICAL-TIPS.md - Detailed implementations for common animation scenarios