Library Selection by Complexity/Performance

Project Requirements → Library Choice
├── Simple transitions (hover, fade, slide)?
│   └── Use CSS transitions/animations
│       - Low bundle size impact
│       - Hardware accelerated
│       - Good enough for 80% of needs
├── Layout animations, gesture handling, or complex sequences?
│   ├── React project?
│   │   └── Use Framer Motion
│   │       - Layout animations automatic
│   │       - AnimatePresence for mount/unmount
│   │       - Spring physics built-in
│   └── Vanilla JS or non-React?
│       └── Use GSAP
│           - Maximum control and performance
│           - ScrollTrigger for scroll effects
│           - Complex timeline orchestration
├── Scroll-driven effects only?
│   ├── Browser support modern (Chrome 115+)?
│   │   └── Use CSS scroll-driven animations
│   │       - Zero JavaScript overhead
│   │       - Runs off main thread
│   └── Need older browser support?
│       └── Use GSAP ScrollTrigger
└── Cross-page transitions?
    ├── Shared elements between pages?
    │   └── Use View Transitions API
    │       - Browser handles morphing automatically
    │       - Fallback to regular page load
    └── Simple page-level effects?
        └── CSS animations with navigation events

Timing Decision Tree

Animation Purpose → Duration Range
├── Instant feedback (hover acknowledgment)?
│   └── 100-150ms with ease-out
├── State change confirmation (toggle, selection)?
│   └── 200-250ms with ease-in-out
├── Content reveal (dropdown, accordion)?
│   └── 300-400ms with spring physics
├── Major context change (modal, page)?
│   └── 400-600ms with anticipation + follow-through
└── Background activity (loading, progress)?
    └── 1.5-2s cycle or tied to actual progress

Spring Physics Tuning

Interaction Type → Spring Config
├── Snappy UI controls (buttons, switches)?
│   └── stiffness: 400, damping: 28
├── Smooth panels (modals, cards)?
│   └── stiffness: 200, damping: 24
├── Playful elements (success animations)?
│   └── stiffness: 300, damping: 15 (more bounce)
├── Heavy elements (full-page sheets)?
│   └── stiffness: 120, damping: 20, mass: 1.5
└── Gesture-driven (drag, swipe)?
    └── stiffness: 300, damping: 20, velocity inheritance

Failure Modes

Layout Thrashing Jank

Detection: Animation drops below 60fps, DevTools Performance tab shows purple "Layout" blocks during animation Symptoms: Choppy motion, especially on slower devices; scrolling feels laggy during transitions Root Cause: Animating properties that trigger layout recalculation (width, height, margin, padding, top, left) Fix: Only animate transform, opacity, filter, clip-path; use transform: scale() instead of width/height changes

Spring Oscillation Hell

Detection: Elements bounce for >1 second after interaction; users wait for UI to settle before next action Symptoms: Damping too low (<15) or stiffness too high (>500) with low damping; feels like everything is made of jello Root Cause: Misunderstanding that lower damping = more bounce = longer settle time Fix: Keep damping ≥20 for interactive elements; test on actual devices, not fast desktop; use duration-based transitions for predictable timing

Animation Soup Chaos

Detection: Multiple elements animating simultaneously with no clear visual hierarchy; user doesn't know where to look Symptoms: Everything moves at once on page load; competing animations fight for attention Root Cause: Ignoring Disney's "staging" principle; treating each animation in isolation Fix: Stagger children by 40-80ms; animate hero/primary element first; max 1-2 simultaneous animation groups

Accessibility Violation Seizures

Detection: No @media (prefers-reduced-motion) styles; animations run at full intensity for all users Symptoms: User reports motion sensitivity issues; fails accessibility audits Root Cause: Treating reduced motion as optional nice-to-have instead of legal/safety requirement Fix: Always provide crossfade or instant alternatives; test with prefers-reduced-motion: reduce enabled

Bundle Bloat Performance Hit

Detection: Animation library adds >50KB to bundle; first-page animations cause layout shift or delay Symptoms: Slow initial page load; animations start late after JavaScript parses Root Cause: Loading heavy animation library for simple transitions; not code-splitting animation features Fix: Use CSS for simple effects; lazy-load Framer Motion/GSAP; inline critical animation CSS; measure Core Web Vitals impact

Worked Examples

Example: Card Hover with Performance Monitoring

Scenario: Product card needs hover effect that feels premium but performs well on mobile.

Novice approach:

.card:hover {
  width: 102%;
  height: 102%;
  margin-top: -4px;
  border-width: 2px;
}

Expert analysis: This will trigger layout recalculation on every frame. Width/height changes force reflow. Border-width change affects box model.

Expert solution with decision points:

Library choice: CSS only (simple hover state, no React needed)
Properties: Transform + box-shadow only (GPU-composited)
Timing: 200ms ease-out (quick acknowledgment, not dramatic)
Accessibility: Honor reduced motion preference

.card {
  transition: transform 200ms ease-out, box-shadow 200ms ease-out;
  will-change: transform; /* Hint for layer promotion */
}

.card:hover {
  transform: translateY(-4px) scale(1.01); /* Lift + subtle scale */
  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.08); /* Depth increase */
}

@media (prefers-reduced-motion: reduce) {
  .card {
    transition: box-shadow 200ms ease-out; /* Keep depth change, remove movement */
  }
  .card:hover {
    transform: none; /* No movement for motion-sensitive users */
  }
}

Performance validation: DevTools Performance tab shows no Layout blocks during hover, maintains 60fps on mid-range mobile device.

Quality Gates

NOT-FOR Boundaries

Do NOT use this skill for:

Canvas/WebGL animations → Use threejs-expert for 3D graphics and particle systems
SVG illustration animation → Use After Effects + Lottie or dedicated SVG animation libraries
Video editing or motion graphics production → Use video editing tools, not web animation APIs
Native mobile animations → Use ios-app-beauty for SwiftUI or Android animation systems
Game animations → Use game engines; web animation APIs not optimized for 60+ entity coordination

Delegate to other skills:

Performance optimization → Use react-performance-optimizer for bundle analysis and render optimization
Complex scroll interactions → Use scroll-experience-designer for scroll-jacking and custom scroll behaviors
Design systems → Use design-system-architect for consistent animation tokens and guidelines

motion-design-web

Motion Design for Web

Decision Points