---
name: Animation Craft
description: Motion design and micro-interaction craft for production UI
category: craft
activateOn: component-creation
freedomLevel: high
version: 1.0.0
tags:
- animation
- motion
- framer-motion
- micro-interactions
- transitions
- choreography
---
# Animation Craft
Production-grade motion design for UI components. This skill covers animation
principles adapted for interfaces, timing systems, Framer Motion patterns,
CSS transitions, loading choreography, scroll-triggered motion, accessibility,
and performance optimization.
For video deliverables, do not duplicate renderer-specific guidance here. Load
`remotion-video` for React/Remotion production, `hyperframes-video` for
HTML-first rendering, `website-to-video` for browser-flow capture, and
`motion-performance` for queue, accessibility, and export checks.
---
## 1. The 12 Principles of Animation — Adapted for UI
Disney's 12 principles translate directly into interface motion when reframed
for digital interaction rather than character animation.
### 1.1 Squash and Stretch
In UI: scale transforms on press states. A button compresses slightly on tap
(`scale: 0.97`) and rebounds on release (`scale: 1.0`). Preserves the feeling
of physicality without literal deformation.
### 1.2 Anticipation
In UI: a brief preparatory motion before the main action. A card about to fly
off-screen nudges 4px in the opposite direction first. A delete action shakes
the target element before removal. Primes the user for what comes next.
### 1.3 Staging
In UI: direct attention to the primary action. Dim or blur surrounding elements
when a modal opens. Use motion to guide the eye — the element that moves is the
element that matters. Never animate two competing things simultaneously.
### 1.4 Straight Ahead vs. Pose to Pose
In UI: pose-to-pose dominates. Define keyframes (initial state, final state)
and let easing handle interpolation. Straight-ahead is rare — reserved for
particle effects or generative motion where each frame builds on the last.
### 1.5 Follow Through and Overlapping Action
In UI: staggered children. When a panel slides in, its contents arrive 50-80ms
later. A card's shadow settles after the card itself. Elements within a group
resolve at slightly different times, creating organic layered motion.
### 1.6 Slow In, Slow Out (Ease In, Ease Out)
In UI: the foundation of all easing. Nothing moves linearly except progress
bars. Entrances use ease-out (fast start, gentle landing). Exits use ease-in
(gentle start, fast departure). State changes use ease-in-out.
### 1.7 Arcs
In UI: curved motion paths for elements traversing significant distance. A FAB
expanding into a full sheet follows an arc, not a straight diagonal. Implemented
via simultaneous x/y transforms with different easing curves.
### 1.8 Secondary Action
In UI: supporting animations that reinforce the primary. A success checkmark
draws itself (primary) while the surrounding circle fills green (secondary).
A notification badge bounces in while a subtle ring pulse radiates outward.
### 1.9 Timing
In UI: duration is meaning. Fast (100-150ms) = direct manipulation, the user
caused this. Medium (200-350ms) = state transition, something changed. Slow
(400-600ms) = page-level, a significant context shift occurred.
### 1.10 Exaggeration
In UI: used sparingly and intentionally. Error states shake with slightly more
amplitude than physics would suggest. Success animations overshoot their final
scale by 5-10% before settling. Subtle exaggeration creates delight; heavy
exaggeration creates cartoon interfaces.
### 1.11 Solid Drawing
In UI: consistent transform origins and spatial relationships. Elements scale
from their visual center. Panels slide from the edge they are anchored to.
Maintain the illusion of physical consistency — objects have weight, position,
and spatial logic.
### 1.12 Appeal
In UI: motion should feel inevitable, not decorative. Every animation answers
"what changed and why." If removing an animation makes the interface harder to
understand, it belongs. If removing it changes nothing, delete it.
---
## 2. Timing and Easing Reference
### 2.1 Cubic-Bezier Values
```
Snappy cubic-bezier(0.2, 0, 0, 1)
Fast attack, smooth settle. Best for: toggles, switches, small state changes.
Feels responsive and decisive.
Smooth cubic-bezier(0.4, 0, 0.2, 1)
Material Design standard. Best for: general transitions, panels, modals.
Feels polished and professional.
Bouncy cubic-bezier(0.34, 1.56, 0.64, 1)
Overshoots target, settles back. Best for: success states, playful UI,
notification badges. Use at durations under 400ms to avoid feeling sluggish.
Gentle cubic-bezier(0.4, 0, 0.6, 1)
Symmetric ease-in-out. Best for: looping animations, hover states,
ambient motion. Feels calm and unhurried.
Sharp Enter cubic-bezier(0, 0, 0.2, 1)
Pure ease-out. Best for: elements entering the viewport. Fast arrival,
gentle deceleration into final position.
Sharp Exit cubic-bezier(0.4, 0, 1, 1)
Pure ease-in. Best for: elements leaving the viewport. Gentle start,
accelerates away. User does not need to watch it leave.
Spring cubic-bezier(0.175, 0.885, 0.32, 1.275)
Slight overshoot with natural settle. Best for: popovers, tooltips,
dropdown menus. Feels alive without being distracting.
```
### 2.2 Framer Motion Spring Presets
```typescript
// Snappy spring — direct manipulation, toggles
const snappySpring = { type: "spring", stiffness: 500, damping: 30 };
// Smooth spring — general transitions
const smoothSpring = { type: "spring", stiffness: 300, damping: 25 };
// Bouncy spring — playful feedback
const bouncySpring = { type: "spring", stiffness: 400, damping: 15 };
// Gentle spring — ambient, decorative
const gentleSpring = { type: "spring", stiffness: 120, damping: 20 };
// Heavy spring — large panels, sheets
const heavySpring = { type: "spring", stiffness: 200, damping: 30, mass: 1.5 };
```
---
## 3. Duration Guidelines by Interaction Type
### 3.1 Micro Interactions (100-200ms)
Direct responses to user input. The user caused this and expects instant feedback.
| Pattern | Duration | Easing |
|---------|----------|--------|
| Button press scale | 100ms | Snappy |
| Toggle switch | 150ms | Snappy |
| Checkbox/radio | 120ms | Snappy |
| Ripple effect | 200ms | Sharp Enter |
| Tooltip appear | 150ms | Sharp Enter |
| Focus ring | 100ms | Snappy |
| Color change (hover) | 150ms | Gentle |
| Icon swap | 120ms | Snappy |
### 3.2 State Transitions (200-400ms)
The interface is changing state. Something happened — a panel opened, content
loaded, a filter applied.
| Pattern | Duration | Easing |
|---------|----------|--------|
| Dropdown open | 200ms | Sharp Enter |
| Dropdown close | 150ms | Sharp Exit |
| Accordion expand | 300ms | Smooth |
| Modal enter | 300ms | Spring |
| Modal exit | 200ms | Sharp Exit |
| Tab content swap | 250ms | Smooth |
| Sidebar toggle | 300ms | Smooth |
| Toast notification | 350ms | Spring |
| Card expand | 350ms | Smooth |
| Filter results | 250ms | Smooth |
### 3.3 Page Transitions (300-600ms)
Significant context shift. A new view, a navigation event, a major layout change.
| Pattern | Duration | Easing |
|---------|----------|--------|
| Page crossfade | 300ms | Gentle |
| Slide navigation | 400ms | Smooth |
| Shared layout morph | 500ms | Smooth |
| Full-screen expand | 500ms | Smooth |
| Route change fade | 300ms | Gentle |
| Stagger children (page) | 400ms total | Smooth + stagger 50ms |
### 3.4 The Exit Rule
Exits should be 30-50% faster than entrances. Users do not need to watch
something leave — they have already moved on mentally. A modal that enters in
300ms should exit in 180-200ms.
---
## 4. Framer Motion Patterns
### 4.1 Basic: animate / initial / exit
```tsx
import { motion } from "framer-motion";
// Fade in on mount
function FadeIn({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
// Slide up on mount, slide down on unmount
function SlideUp({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
### 4.2 Variants and Orchestration
Variants define named animation states. Orchestration controls how children
animate relative to parents.
```tsx
const containerVariants = {
hidden: { opacity: 0 },
visible: {
opacity: 1,
transition: {
staggerChildren: 0.06,
delayChildren: 0.1,
when: "beforeChildren",
},
},
exit: {
opacity: 0,
transition: {
staggerChildren: 0.03,
staggerDirection: -1,
when: "afterChildren",
},
},
};
const itemVariants = {
hidden: { opacity: 0, y: 16 },
visible: {
opacity: 1,
y: 0,
transition: { duration: 0.3, ease: [0.2, 0, 0, 1] },
},
exit: {
opacity: 0,
y: -8,
transition: { duration: 0.15, ease: [0.4, 0, 1, 1] },
},
};
function StaggerList({ items }: { items: Item[] }) {
return (
{items.map((item) => (
{item.content}
))}
);
}
```
### 4.3 AnimatePresence for Mount/Unmount
AnimatePresence enables exit animations. Without it, removed elements
disappear instantly.
```tsx
import { AnimatePresence, motion } from "framer-motion";
function NotificationStack({ notifications }: { notifications: Notification[] }) {
return (
{notifications.map((notif) => (
))}
);
}
```
**AnimatePresence modes:**
- `"sync"` (default) — children animate in/out simultaneously
- `"wait"` — outgoing completes before incoming starts
- `"popLayout"` — exiting elements are popped from layout flow immediately,
remaining elements reflow while exit animation plays
### 4.4 Layout Animations
The `layout` prop auto-animates any layout change — position, size, or
order caused by DOM reflow. This is extremely powerful and often the only
animation you need.
```tsx
function ExpandableCard({ isOpen, title, content }: ExpandableCardProps) {
return (
{title}
{isOpen && (
{content}
)}
);
}
```
**Layout prop values:**
- `layout={true}` — animate position and size
- `layout="position"` — only animate position, not size
- `layout="size"` — only animate size, not position
- `layoutId="shared-id"` — shared layout animation across components
### 4.5 Gesture Animations
```tsx
function InteractiveCard({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
// Draggable element with constraints
function DraggableItem() {
const constraintsRef = useRef(null);
return (
);
}
```
### 4.6 useSpring and useMotionValue
For imperative, physics-based animations that respond to changing values
rather than declarative state.
```tsx
import { useMotionValue, useSpring, useTransform, motion } from "framer-motion";
function ProgressRing({ progress }: { progress: number }) {
const motionProgress = useMotionValue(0);
const springProgress = useSpring(motionProgress, {
stiffness: 100,
damping: 20,
});
// Derived values
const strokeDashoffset = useTransform(
springProgress,
[0, 100],
[283, 0] // circumference of r=45 circle
);
const color = useTransform(
springProgress,
[0, 50, 100],
["#ef4444", "#eab308", "#22c55e"]
);
// Update when prop changes
useEffect(() => {
motionProgress.set(progress);
}, [progress, motionProgress]);
return (
);
}
```
### 4.7 staggerChildren Patterns
Stagger creates cascading reveals. The key is finding the right delay:
too short feels simultaneous, too long feels sluggish.
```
Items Stagger Delay Total Stagger Time Feel
3-5 60-80ms 180-400ms Natural
6-10 40-60ms 240-600ms Flowing
11-20 25-40ms 275-800ms Cascading
20+ 15-25ms Cap at 600ms Wave
```
**Rule: cap total stagger time at 600ms.** Beyond that, the last items feel
delayed rather than choreographed. For 30 items at 20ms stagger = 600ms total,
which is the upper limit.
```tsx
// Dynamic stagger calculation
function getStaggerDelay(itemCount: number): number {
const maxTotalStagger = 0.6; // 600ms
const minDelay = 0.015;
const maxDelay = 0.08;
const calculated = maxTotalStagger / itemCount;
return Math.max(minDelay, Math.min(maxDelay, calculated));
}
```
---
## 5. CSS Transition Patterns
Use CSS transitions when:
- The animation is simple (opacity, transform, color)
- The element never unmounts (hover, focus, active states)
- Bundle size matters and Framer Motion is not already in the project
- The animation is purely decorative
### 5.1 Transition Utility Classes
```css
/* Base transitions — apply to elements that need animation */
.transition-micro {
transition-property: transform, opacity, box-shadow;
transition-duration: 150ms;
transition-timing-function: cubic-bezier(0.2, 0, 0, 1);
}
.transition-state {
transition-property: transform, opacity, background-color, border-color, box-shadow;
transition-duration: 250ms;
transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}
.transition-page {
transition-property: opacity, transform;
transition-duration: 350ms;
transition-timing-function: cubic-bezier(0.4, 0, 0.6, 1);
}
/* Color-only transition (no layout properties) */
.transition-colors-fast {
transition-property: color, background-color, border-color, fill, stroke;
transition-duration: 150ms;
transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}
```
### 5.2 CSS Keyframe Patterns
```css
@keyframes fade-in {
from { opacity: 0; }
to { opacity: 1; }
}
@keyframes slide-up {
from { opacity: 0; transform: translateY(16px); }
to { opacity: 1; transform: translateY(0); }
}
@keyframes scale-in {
from { opacity: 0; transform: scale(0.95); }
to { opacity: 1; transform: scale(1); }
}
@keyframes shimmer {
0% { background-position: -200% 0; }
100% { background-position: 200% 0; }
}
@keyframes pulse-subtle {
0%, 100% { opacity: 1; }
50% { opacity: 0.7; }
}
@keyframes spin {
from { transform: rotate(0deg); }
to { transform: rotate(360deg); }
}
@keyframes shake {
0%, 100% { transform: translateX(0); }
20% { transform: translateX(-4px); }
40% { transform: translateX(4px); }
60% { transform: translateX(-3px); }
80% { transform: translateX(2px); }
}
```
### 5.3 When to Use CSS vs. Framer Motion
| Scenario | Use CSS | Use Framer Motion |
|----------|---------|-------------------|
| Hover/focus/active states | Yes | No |
| Element never unmounts | Yes | Optional |
| Mount animation only | Yes (animation-fill-mode: both) | Optional |
| Unmount animation needed | No | Yes (AnimatePresence) |
| Layout animation | No | Yes (layout prop) |
| Gesture-driven | No | Yes (whileHover, drag) |
| Physics-based spring | No | Yes (useSpring) |
| Shared layout transition | No | Yes (layoutId) |
| Stagger orchestration | Possible but brittle | Yes (staggerChildren) |
| Scroll-linked values | Possible (scroll-timeline) | Yes (useScroll) |
---
## 6. Loading State Choreography
Loading is not a waiting room. It is a sequence of progressive reveals that
communicate progress and maintain spatial stability.
### 6.1 Skeleton to Content Transition
```tsx
const skeletonVariants = {
loading: {
opacity: 1,
},
loaded: {
opacity: 0,
transition: { duration: 0.15 },
},
};
const contentVariants = {
loading: {
opacity: 0,
y: 8,
},
loaded: {
opacity: 1,
y: 0,
transition: {
duration: 0.3,
ease: [0.2, 0, 0, 1],
delay: 0.1, // overlap with skeleton fade
},
},
};
function DataCard({ data, isLoading }: DataCardProps) {
const state = isLoading ? "loading" : "loaded";
return (
{data && }
);
}
```
### 6.2 Progressive Reveal Pattern
When a page has multiple data sources loading at different speeds, reveal
each section as it arrives rather than waiting for all data.
```tsx
const sectionVariants = {
hidden: { opacity: 0, y: 16 },
visible: {
opacity: 1,
y: 0,
transition: { duration: 0.35, ease: [0.2, 0, 0, 1] },
},
};
function Dashboard({ metrics, chart, activity }: DashboardProps) {
return (
{metrics && (
)}
{chart && (
)}
{activity && (
)}
);
}
```
### 6.3 Shimmer Skeleton
```tsx
function Skeleton({ className }: { className?: string }) {
return (
);
}
```
Tailwind config addition:
```js
animation: {
shimmer: "shimmer 2s ease-in-out infinite",
},
keyframes: {
shimmer: {
"0%": { backgroundPosition: "200% 0" },
"100%": { backgroundPosition: "-200% 0" },
},
},
```
---
## 7. Page Transition Patterns
### 7.1 Shared Layout Transition
When navigating between a list view and a detail view, morph the clicked
item into the detail page for spatial continuity.
```tsx
// List view
function ProjectList({ projects }: { projects: Project[] }) {
return (
// With delay via style (Tailwind does not have animation-delay utilities)
Delayed content
// Stagger via inline delay
{items.map((item, i) => (
{item.content}
))}
```
---
## 14. Common Patterns Library
### 14.1 Fade In
```tsx
// Framer Motion
const fadeIn = {
initial: { opacity: 0 },
animate: { opacity: 1 },
exit: { opacity: 0 },
transition: { duration: 0.3, ease: [0.4, 0, 0.2, 1] },
};
// CSS class
// animate-fade-in
```
### 14.2 Slide Up
```tsx
const slideUp = {
initial: { opacity: 0, y: 24 },
animate: { opacity: 1, y: 0 },
exit: { opacity: 0, y: 12 },
transition: { duration: 0.35, ease: [0.2, 0, 0, 1] },
};
```
### 14.3 Scale In (Popover/Tooltip)
```tsx
const scaleIn = {
initial: { opacity: 0, scale: 0.95 },
animate: { opacity: 1, scale: 1 },
exit: { opacity: 0, scale: 0.95 },
transition: { type: "spring", stiffness: 400, damping: 25 },
};
```
### 14.4 Stagger List
```tsx
const staggerContainer = {
hidden: { opacity: 0 },
visible: {
opacity: 1,
transition: { staggerChildren: 0.05, delayChildren: 0.1 },
},
};
const staggerItem = {
hidden: { opacity: 0, y: 12 },
visible: {
opacity: 1,
y: 0,
transition: { duration: 0.3, ease: [0.2, 0, 0, 1] },
},
};
```
### 14.5 Pulse (Status Indicator)
```tsx
// CSS only — no Framer needed
```
### 14.6 Shimmer (Skeleton)
```tsx
```
### 14.7 Number Counter
```tsx
import { useSpring, motion, useMotionValue, useTransform } from "framer-motion";
function AnimatedNumber({ value }: { value: number }) {
const motionValue = useMotionValue(0);
const springValue = useSpring(motionValue, { stiffness: 100, damping: 20 });
const display = useTransform(springValue, (v) => Math.round(v).toLocaleString());
useEffect(() => {
motionValue.set(value);
}, [value, motionValue]);
return {display};
}
```
### 14.8 Typewriter Effect
```tsx
function Typewriter({ text, speed = 40 }: { text: string; speed?: number }) {
const [displayed, setDisplayed] = useState("");
useEffect(() => {
setDisplayed("");
let i = 0;
const interval = setInterval(() => {
if (i < text.length) {
setDisplayed(text.slice(0, i + 1));
i++;
} else {
clearInterval(interval);
}
}, speed);
return () => clearInterval(interval);
}, [text, speed]);
return (
{displayed}
|
);
}
```
---
## 15. Anti-Patterns
### 15.1 Too Much Motion
Every element animates on mount, scroll, and hover. The page feels like a
pinball machine. Fix: reserve animation for state changes and user-initiated
actions. Static content should appear instantly.
### 15.2 Jarring Timing
A modal flies in at 600ms with a heavy bounce, then snaps shut in 50ms.
The asymmetry is disorienting. Fix: exits should be 30-50% faster than
entrances, not 90% faster. Maintain proportional timing.
### 15.3 Competing Animations
A sidebar slides in while the main content also slides, while a toast also
animates, while the header reorganizes. The user cannot track any single
change. Fix: stage animations sequentially. Primary action first, secondary
follows. Use stagger and delay, not parallelism.
### 15.4 Linear Easing Everywhere
Movement without easing feels robotic and unnatural. Every element slides
at constant speed. Fix: always apply appropriate easing. The only acceptable
use of linear is for continuous rotation (spinners) and progress bars.
### 15.5 Animating Layout Properties
Animating `width`, `height`, `margin`, `padding`, `top`, `left` causes
layout recalculation on every frame. 60fps becomes 15fps. Fix: use
`transform` and `opacity`. Use Framer Motion's `layout` prop for
automatic layout animation that handles compositing correctly.
### 15.6 Infinite Ambient Animation on Content
Continuously pulsing, rotating, or bouncing content elements. The eye
cannot settle. Fix: ambient animation belongs on status indicators and
decorative elements only. Content should be still after its entrance
animation completes.
### 15.7 Missing Exit Animations
Elements pop in smoothly but vanish instantly when removed. The lack of
exit creates a jarring cut. Fix: always define exit animations via
AnimatePresence. Even a 150ms opacity fade is better than instant removal.
### 15.8 Stagger Without Purpose
Every list uses staggerChildren even when items are already visible or
when the list has 100+ items. Fix: stagger only on first reveal. Cap
total stagger time at 600ms. For already-visible content that updates,
use layout animation instead of stagger.
### 15.9 Ignoring Reduced Motion
Elaborate animations play regardless of user preference. Users with
motion sensitivity or vestibular disorders experience discomfort. Fix:
always check `prefers-reduced-motion`. Replace spatial transforms with
opacity crossfade. Keep functional animations (spinners, progress) but
remove decorative motion.
### 15.10 Spring Without Damping Tuning
Using `type: "spring"` with default values produces wobbly, slow-settling
animation. Fix: always specify stiffness and damping. Test springs
visually. A spring that takes more than 800ms to fully settle is too soft
for UI. Increase damping or stiffness.
---
## Quick Reference Card
```
ENTERS: ease-out cubic-bezier(0, 0, 0.2, 1) fast start, gentle land
EXITS: ease-in cubic-bezier(0.4, 0, 1, 1) gentle start, fast leave
MOVES: ease-both cubic-bezier(0.4, 0, 0.2, 1) smooth both ends
MICRO: 100-200ms toggles, presses, hovers
STATE: 200-400ms panels, modals, tabs
PAGE: 300-600ms navigation, shared layout
EXIT: 30-50% faster than enter
STAGGER: cap 600ms total, 15-80ms per item
GPU: only transform, opacity, filter
REDUCE: always respect prefers-reduced-motion
```