Motion Design

A focused, opinionated knowledge base for implementing animations and motion in web applications. Covers CSS transitions and keyframes, Framer Motion, GSAP, scroll-driven animations, and micro-interactions - with concrete code for each pattern. Every recommendation prioritizes 60fps performance, accessibility, and purposeful motion over decoration.

The difference between good and bad animation is restraint. Most UIs need fewer animations, not more. When motion exists, it must be fast, smooth, and respect user preferences.

---

When to use this skill

Trigger this skill when the user:

• Asks to add animations or transitions to any UI element
• Needs enter/exit animations for components mounting or unmounting
• Wants to implement page transitions or route-change animations
• Asks about Framer Motion, GSAP, or CSS animation APIs
• Needs scroll-driven animations or parallax effects
• Wants loading states with skeleton screens or spinners
• Asks about spring physics, easing curves, or animation timing
• Needs a GSAP timeline for complex multi-step sequences
• Asks about micro-interactions (hover, press, toggle, checkbox states)

Do NOT trigger this skill for:

• Pure CSS layout or styling with no motion (use ultimate-ui instead)
• Canvas or WebGL rendering (use a graphics-specific resource instead)

---

Key principles

1. Motion should have purpose - Every animation must communicate something: state change, spatial relationship, feedback, or hierarchy. Decoration-only motion is noise. Ask "what does this animation tell the user?" before adding it.

2. Respect prefers-reduced-motion - Always wrap animations in a prefers-reduced-motion check. Users with vestibular disorders or epilepsy can be harmed by motion. This is a WCAG 2.1 AA requirement, not a suggestion.

3. Animate transforms and opacity only - transform and opacity are the only properties the browser can animate on the compositor thread without triggering layout or paint. Animating width, height, top, left, margin, or padding causes jank. Use transform: scale/translate instead.

4. Spring > linear easing - Natural motion uses physics-based easing, not uniform speed. Spring animations feel alive. linear feels robotic. Use ease-out for entrances, ease-in for exits, spring/bounce for interactive elements that respond to user input.

5. 60fps or nothing - If an animation drops frames, remove it. A janky animation is worse than no animation. Test on a throttled CPU (4x slowdown in Chrome DevTools). If it drops below 60fps, simplify or cut it.

---

Core concepts

Animation properties

• Duration: 100-150ms for micro (button hover), 200-300ms for UI (modal, dropdown), 300-500ms for layout (page transitions). Never over 500ms for interactive feedback.
• Easing: ease-out (fast start, soft land) for elements entering the screen. ease-in (slow start, fast end) for elements leaving. ease-in-out for elements moving across the screen. Spring for interactive/playful elements.
• Delay: Use sparingly. Stagger children by 50-75ms max. Total stagger sequence should not exceed 400ms or users feel they are waiting.

CSS vs JS animations - decision guide

• Use CSS transitions for simple state changes triggered by class or pseudo-class (hover, focus, active). Zero JS overhead.
• Use CSS keyframes for looping animations (spinners, pulses) and choreographed sequences not tied to interaction.
• Use Framer Motion (React) for enter/exit animations tied to component mount/unmount, gesture-driven motion, or layout animations.
• Use GSAP for complex multi-step timelines, SVG path animations, scroll-triggered sequences, or when you need precise programmatic control.

Spring physics A spring has two key parameters: stiffness (how fast it accelerates) and damping (how quickly it settles). High stiffness + high damping = snappy. Low stiffness + low damping = bouncy and slow. For UI: stiffness 300-500, damping 25-35 gives a natural feel without excessive bounce.

Performance - compositor vs main thread The browser renders in two stages: main thread (layout, paint) and compositor thread (transform, opacity). Animations on the compositor thread run at 60fps even when the main thread is busy. Always use transform and opacity. Add will-change: transform only for elements you know will animate - overusing will-change wastes GPU memory.

---

Common tasks

CSS transitions and keyframes

/* Reusable easing tokens */
:root {
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
  --duration-fast: 100ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
}

/* Fade in up - content appearing */
@keyframes fade-in-up {
  from { opacity: 0; transform: translateY(12px); }
  to   { opacity: 1; transform: translateY(0); }
}

/* Scale in - modals, popovers */
@keyframes scale-in {
  from { opacity: 0; transform: scale(0.95); }
  to   { opacity: 1; transform: scale(1); }
}

.modal {
  animation: scale-in var(--duration-normal) var(--ease-out);
}

/* Card hover - lift effect */
.card {
  transition: transform var(--duration-fast) var(--ease-out),
              box-shadow var(--duration-fast) var(--ease-out);
}
.card:hover {
  transform: translateY(-2px);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
}

Framer Motion enter/exit animations

import { motion, AnimatePresence } from 'framer-motion';

// Reusable animation variants
const fadeUp = {
  initial: { opacity: 0, y: 12 },
  animate: { opacity: 1, y: 0 },
  exit:    { opacity: 0, y: -8 },
  transition: { duration: 0.2, ease: [0, 0, 0.2, 1] },
};

const scaleIn = {
  initial: { opacity: 0, scale: 0.95 },
  animate: { opacity: 1, scale: 1 },
  exit:    { opacity: 0, scale: 0.95 },
  transition: { duration: 0.15, ease: [0, 0, 0.2, 1] },
};

// Component with enter/exit
function Notification({ show, message }: { show: boolean; message: string }) {
  return (
    <AnimatePresence>
      {show && (
        <motion.div
          key="notification"
          {...fadeUp}
          className="toast"
        >
          {message}
        </motion.div>
      )}
    </AnimatePresence>
  );
}

// Staggered list
function AnimatedList({ items }: { items: string[] }) {
  return (
    <motion.ul
      initial="hidden"
      animate="visible"
      variants={{
        hidden: {},
        visible: { transition: { staggerChildren: 0.06 } },
      }}
    >
      {items.map((item) => (
        <motion.li
          key={item}
          variants={{
            hidden: { opacity: 0, x: -12 },
            visible: { opacity: 1, x: 0, transition: { duration: 0.2 } },
          }}
        >
          {item}
        </motion.li>
      ))}
    </motion.ul>
  );
}

Scroll-driven animations with CSS

/* Native CSS scroll-driven animations (Chrome 115+) */
@keyframes reveal {
  from { opacity: 0; transform: translateY(20px); }
  to   { opacity: 1; transform: translateY(0); }
}

.scroll-reveal {
  animation: reveal linear both;
  animation-timeline: view();
  animation-range: entry 0% entry 25%;
}

/* Progress bar tied to page scroll */
.scroll-progress {
  position: fixed;
  top: 0;
  left: 0;
  height: 3px;
  background: var(--color-primary-500);
  transform-origin: left;
  animation: scaleX linear;
  animation-timeline: scroll(root);
}
@keyframes scaleX {
  from { transform: scaleX(0); }
  to   { transform: scaleX(1); }
}

/* IntersectionObserver fallback for broader browser support */

// IntersectionObserver - works in all browsers
const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach((entry) => {
      if (entry.isIntersecting) {
        entry.target.classList.add('in-view');
        observer.unobserve(entry.target); // animate once
      }
    });
  },
  { threshold: 0.15 }
);

document.querySelectorAll('[data-reveal]').forEach((el) => observer.observe(el));

[data-reveal] {
  opacity: 0;
  transform: translateY(16px);
  transition: opacity 0.3s var(--ease-out), transform 0.3s var(--ease-out);
}
[data-reveal].in-view {
  opacity: 1;
  transform: translateY(0);
}

Page transitions with AnimatePresence

import { AnimatePresence, motion } from 'framer-motion';
import { usePathname } from 'next/navigation';

const pageVariants = {
  initial: { opacity: 0, y: 8 },
  animate: { opacity: 1, y: 0, transition: { duration: 0.25, ease: [0, 0, 0.2, 1] } },
  exit:    { opacity: 0, y: -8, transition: { duration: 0.15, ease: [0.4, 0, 1, 1] } },
};

export function PageTransition({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();

  return (
    <AnimatePresence mode="wait">
      <motion.div key={pathname} {...pageVariants}>
        {children}
      </motion.div>
    </AnimatePresence>
  );
}

Use mode="wait" so the exiting page fully animates out before the new one enters. mode="sync" (default) can cause overlap. Keep page transitions under 250ms - users are waiting to see new content.

Micro-interactions and GSAP timelines

For detailed micro-interaction patterns (hover, press, toggle, accordion) and GSAP timeline examples (hero sequences, scroll-triggered cards), see references/advanced-patterns.md.

Respect prefers-reduced-motion

/* CSS - blanket rule as safety net */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

// Framer Motion - useReducedMotion hook
import { useReducedMotion } from 'framer-motion';

function AnimatedCard({ children }: { children: React.ReactNode }) {
  const prefersReduced = useReducedMotion();

  return (
    <motion.div
      initial={prefersReduced ? false : { opacity: 0, y: 12 }}
      animate={{ opacity: 1, y: 0 }}
      transition={prefersReduced ? { duration: 0 } : { duration: 0.2 }}
    >
      {children}
    </motion.div>
  );
}

// Vanilla JS - check preference before running GSAP
const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

if (!prefersReduced) {
  animateHero();
}

---

Anti-patterns

Mistake	Why it's wrong	What to do instead
Animating width, height, top, or left	Triggers layout recalculation every frame, causes jank	Use transform: scale() or transform: translate() instead
transition: all	Catches unexpected properties, hard to predict, performance risk	List specific properties: transition: transform 200ms, opacity 200ms
Duration over 500ms for interactive feedback	Users feel the UI is lagging or broken	Keep button/hover/toggle under 200ms, modal under 300ms
Using GSAP for simple hover effects	Massive overhead for something CSS handles natively	Use CSS transition for state changes, GSAP for timelines only
Stagger delay total over 500ms	Users wait for content instead of seeing it appear	Cap per-item delay at 75ms, total stagger at 400ms
will-change: transform on everything	Each will-change creates a GPU layer - excessive use wastes VRAM	Only add to elements you know will animate, remove after animation

---

Gotchas

1. AnimatePresence requires a stable key prop on its direct child - Without a unique key, Framer Motion cannot differentiate between the exiting and entering component, so exit animations never play. The key must change when the content changes (e.g., key={pathname} for page transitions, key={item.id} for list items). Using key={Math.random()} or omitting it are the two most common causes of broken exit animations.

2. CSS scroll-driven animations (animation-timeline: scroll()) have no Safari support as of early 2026 - The native CSS scroll timeline API is Chromium-only. Shipping it without an IntersectionObserver fallback means Safari users see no scroll animations at all. Always implement the IntersectionObserver approach as the baseline and treat scroll-driven CSS as progressive enhancement.

3. will-change: transform on many elements simultaneously tanks GPU memory - Each element with will-change gets promoted to its own GPU layer. Applying it to 20+ card elements, a background, a header, and navigation simultaneously can exhaust GPU memory on low-end devices and cause more jank than having no will-change at all. Apply it only immediately before an animation starts (via JS class add/remove) and remove it after the animation ends.

4. Framer Motion layout animations conflict with CSS transition - When a motion element has both layout prop and a CSS transition applied to transform, the two systems fight over the same property. The CSS transition animates the pre-layout position, while Framer Motion tries to animate to the post-layout position, causing a flash or jump. Remove CSS transition: transform from any element that uses the Framer Motion layout prop.

5. GSAP timelines in React components leak if not cleaned up - A GSAP timeline created in a useEffect without a cleanup function continues running after the component unmounts, animating elements that no longer exist in the DOM and throwing warnings. Always return a cleanup function from useEffect that calls tl.kill() to stop and garbage-collect the timeline.

---

References

For detailed guidance on specific motion topics, read the relevant file from the references/ folder:

• references/easing-library.md - Easing functions, spring configs, duration guidelines, named presets
• references/advanced-patterns.md - Micro-interactions (hover, press, toggle, accordion) and GSAP timeline patterns

Only load a references file if the current task requires it - they are long and will consume context.