Use this skill when implementing animations, transitions, micro-interactions, or motion design in web applications. Triggers on CSS animations, Framer Motion, GSAP, keyframes, transitions, spring animations, scroll-driven animations, page transitions, loading states, and any task requiring motion or animation implementation.
Use this skill when implementing animations, transitions, micro-interactions, or motion design in web applications. Triggers on CSS animations, Framer Motion, GSAP, keyframes, transitions, spring animations, scroll-driven animations, page transitions, loading states, and any task requiring motion or animation implementation.
When this skill is activated, always start your first response with the 🧢 emoji.
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
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.
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.
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.
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.
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.
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;
}
}
// Vanilla JS - check preference before running GSAPconst 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
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.
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.
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.
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.
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
Only load a references file if the current task requires it - they are
long and will consume context.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
