UI Animation

Tasteful UI animation with proper timing, accessibility, and performance.

Quick Start

Technique Decision:

Simple transition? → CSS/Tailwind (
```
transition-*
```
,
```
animate-*
```
)
Enter/exit with unmount? → Motion +
```
AnimatePresence
```
Gesture-driven? → Motion springs
Layout changes? → Motion
```
layout
```
prop

Default: Start with Easing Decision Tree → Duration Guidelines → Implement → Add a11y → Verify

Core Principles

Natural Motion: Mimic physics. Avoid linear easing - nothing moves at constant speed.
Purposeful: Every animation must add meaning. If you can't explain its benefit, remove it.
Fast: UI animations under 300ms. Hover effects under 150ms. Over 500ms feels sluggish.
Interruptible: Use springs for gesture-driven animations - they handle interruption gracefully.
Accessible: Always respect
```
prefers-reduced-motion
```
. Non-negotiable.

Workflow

Step 1: Classify Animation Type

Type	Examples	Technique
Micro-interaction	Button press, toggle, checkbox	CSS/Tailwind
Enter/Exit	Modal, toast, dropdown	Motion + AnimatePresence
Layout change	Accordion, reorder, expand	Motion `layout` prop
Shared element	Tab indicator, card expand	Motion `layoutId`
Gesture	Drag, swipe, pull-to-refresh	Motion springs

Step 2: Choose Timing

Use Easing Decision Tree below to select curve
Use Duration Guidelines to select timing
For gestures, use Spring Animations config

Step 3: Implement

Check
```
references/recipes.md
```
for copy-paste patterns
Apply timing from Step 2
Wrap unmounting elements in
```
AnimatePresence
```

Use

ui_to_artifact

when starting from a design screenshot or mockup. Use

ui_diff_check

to compare expected vs implemented UI.

Step 4: Accessibility (Required)

Check

prefers-reduced-motion

with

useReducedMotion()

motion-safe:

Simplify to opacity-only for reduced motion users
Verify focus timing (move focus AFTER animation starts)

Step 5: Verify

Exit animations run (not instant unmount)
```
opacity: 0
```
elements have
```
pointerEvents: none
```
Focus moves after animation starts, not before
Only animating
```
transform
```
and
```
opacity
```

Easing

Decision Tree

text

What triggers the animation?
│
├─ User action (click, tap, open)?
│  └─ Use: ease-out (fast start, slow end = responsive)
│
├─ Element moving on-screen (tab switch, reorder)?
│  └─ Use: ease-in-out (accelerate then decelerate)
│
├─ Continuous/looping (spinner, marquee)?
│  └─ Use: linear (constant speed appropriate here)
│
├─ Gesture-based (drag, swipe, pull)?
│  └─ Use: Spring animation (physics-based, interruptible)
│
└─ Hover/focus effect?
   └─ Use: CSS ease, 150ms (subtle, immediate)

Quick Reference

Purpose	CSS	Tailwind	Duration
Modal/drawer enter	`cubic-bezier(0.32, 0.72, 0, 1)`	`ease-out duration-200`	200ms
Modal/drawer exit	`cubic-bezier(0.32, 0.72, 0, 1)`	`ease-out duration-150`	150ms
On-screen movement	`cubic-bezier(0.4, 0, 0.2, 1)`	`ease-in-out duration-200`	200-300ms
Hover effect	`ease`	`ease duration-150`	150ms
Button press	—	`active:scale-[0.97]`	instant

Pro Curves

Name	Value	Use Case
Vaul (buttery)	`cubic-bezier(0.32, 0.72, 0, 1)`	Sheets, drawers, modals
Emphasized	`cubic-bezier(0.2, 0, 0, 1)`	Material Design 3
Snappy	`cubic-bezier(0.25, 1, 0.5, 1)`	Fast UI transitions

Avoid: Built-in

ease-in

—starts slow, feels sluggish.

Duration Guidelines

Type	Duration	Notes
Micro-feedback	100-150ms	Button press, toggle, checkbox
Small transition	150-250ms	Tooltip, icon morph
Medium transition	200-300ms	Modal, popover, dropdown
Large transition	300-400ms	Page transition, complex layout
Maximum	<500ms	Exceptions: onboarding, data viz

Key Rules:

Exit faster than enter: 200ms enter → 150ms exit
Hover = fast: Under 150ms
High-frequency = instant: Keyboard nav, scrolling—<100ms or none

Spring Animations

Duration-based (Recommended)

Easier to compose with other timed animations. Use

visualDuration

(time to visually reach target) and

bounce

(0 = no bounce, 1 = very bouncy).

Feel	Config	Use Case
Snappy	`{ duration: 0.3, bounce: 0.15 }`	Tabs, buttons, quick feedback
Standard	`{ duration: 0.4, bounce: 0.2 }`	Modals, menus, general UI
Gentle	`{ duration: 0.5, bounce: 0.25 }`	Smooth, human-like flow

Physics-based (Legacy/Advanced)

Use when integrating with physics libraries or when precise control over spring dynamics is needed.

Feel	Config	Use Case
Snappy	`{ stiffness: 400, damping: 30 }`	High-frequency interactions
Standard	`{ stiffness: 300, damping: 20 }`	Framer Handshake convention
Gentle	`{ stiffness: 120, damping: 14 }`	react-motion preset

Gotcha:
stiffness
/
damping
/
mass
overrides
duration
/
bounce
. Pick one approach—don't mix.

Layout Animations

The

layout

Prop

Add

layout

to animate position/size changes automatically. Use

layout="position"

for text (prevents distortion).

Prop Value	Effect	Use Case
`layout={true}`	Animates position AND size	Default for flexible elements
`layout="position"`	Animates only translation	Text/icons that shouldn't stretch
`layout="size"`	Animates only dimensions	Fixed-position expanding panels

Shared Element Transitions (

layoutId

)

Elements with matching

layoutId

animate between each other when entering/exiting.

Critical Trap: Duplicate

layoutId

values cause elements to teleport across the page. Use unique IDs per context or wrap in

<LayoutGroup id="...">

Layout Gotchas

Text distortion: Apply
```
layout="position"
```
to text elements
Border radius: Can warp during scale—Motion auto-corrects, but test it
SVG elements:
```
layout
```
doesn't work on
```
<path>
```
—use manual morphing

Gesture Gotchas

Problem	Solution
Touch scroll conflicts	`dragPropagation={false}`
Element snaps back	Check `dragConstraints` + `dragElastic`
Momentum feels wrong	`dragMomentum={false}` for precise UIs
One-direction only	`dragElastic={{ top: 0, bottom: 0.5 }}`

Swipe dismiss: Check BOTH distance AND velocity—users expect flicks to work.

Accessibility

prefers-reduced-motion (REQUIRED)

tsx

import { useReducedMotion } from "motion/react"

const shouldReduce = useReducedMotion()
const variants = shouldReduce 
  ? { opacity: 1 }                    // Fade only
  : { opacity: 1, scale: 1, y: 0 }    // Full animation

Tailwind:

motion-safe:animate-pulse

motion-reduce:transition-none

Best practice: Don't disable—simplify. Remove spatial movement, keep opacity.

Focus Management

Move focus AFTER animation starts:

requestAnimationFrame(() => ref.focus())

Restore focus to trigger on close
Don't animate inside
```
aria-live
```
regions

Touch Targets

Standard	Size	Tailwind	Physical
Material Design	48×48 dp	`min-h-12 min-w-12`	~9mm (recommended)
Apple HIG	44×44 pt	`min-h-11 min-w-11`	~7mm
WCAG 2.2 (AA)	24×24 px	`min-h-6 min-w-6`	~5mm (minimum)

Why? Average adult finger pad is ~9mm. Targets below 7mm cause "fat finger" errors. Use Material's 48dp for cross-platform; Apple's 44pt is iOS-specific minimum.

Performance

Golden Rules

Only animate
transform
and
opacity
—GPU-accelerated
Never animate:
```
width
```
,
```
height
```
,
```
top
```
,
```
left
```
,
```
margin
```
,
```
padding
```
will-change
sparingly—only during animation, remove after
Blur thresholds:
- ≤10px: Safe for animation
- 11-20px: May cause jank on mobile/4K—test thoroughly
- 20px: Avoid for real-time effects; use pre-blurred images instead
Prefer CSS over JS for simple transitions

Key Traps

Height animation: Use
```
layout
```
prop, not
```
animate={{ height }}
```
Invisible but clickable:
```
opacity: 0
```
still receives clicks—add
```
pointerEvents: "none"
```
will-change everywhere: Causes layer explosion, mobile crashes

See

references/recipes.md

for detailed examples.

Examples

Copy-paste patterns organized by category in

references/recipes.md

Common UI Patterns: Button press, modal enter/exit, error shake, staggered lists, accordion
Touch & Interaction: Accessible touch targets, hover on touch devices, instant tooltips
Layout Animations:
```
layout
```
prop,
```
layoutId
```
shared elements, collision fixes
Radix UI Integration:
```
forceMount
```
pattern,
```
asChild
```
, origin-aware popovers
Accessibility: Focus timing, focus restoration, reduced motion variants
Performance: Height animation (use
```
layout
```
), invisible-but-clickable fix,
```
will-change
```
Exit Patterns:
```
popLayout
```
with
```
forwardRef
```
, SSR hydration (
```
initial={false}
```
)
Gestures: Swipe dismiss with velocity check, elastic drag boundaries

AnimatePresence

Mode	Behavior	Use Case
`sync` (default)	Simultaneous enter/exit	Crossfades, overlays
`wait`	Exit completes before enter	Page transitions, tabs
`popLayout`	Exiting elements leave flow	List removals (with `layout` )

Exit Animation Trap

Exit animations require

AnimatePresence

—without it, unmount is instant:

tsx

// ❌ Exit never runs
{isOpen && <motion.div exit={{ opacity: 0 }}>...</motion.div>}

// ✅ Wrap in AnimatePresence
<AnimatePresence>
  {isOpen && <motion.div exit={{ opacity: 0 }}>...</motion.div>}
</AnimatePresence>

SSR: Use

<AnimatePresence initial={false}>

to prevent animation on page load.

Anti-patterns

Don't	Do Instead	Why
`scale(0)` start	`scale(0.9)` or higher	Avoids "popping" effect
`linear` for UI	`ease-out` or springs	Linear feels robotic
Animations >500ms	Keep under 300ms	Feels sluggish
Same tooltip delay	First: 400ms, subsequent: 0ms	User mental model
Skip reduced-motion	Always `motion-safe:`	Accessibility
Animate layout props	Use `transform: scale()`	Performance
Excessive bounce	`bounce: 0-0.2`	Unprofessional

tailwindcss-animate

Tailwind v4: Define keyframes via
@theme
in CSS, not config.

Category	Classes
Enter	`animate-in fade-in zoom-in-95 slide-in-from-top`
Exit	`animate-out fade-out zoom-out-95 slide-out-to-top`
Timing	`delay-150 duration-500`
Fill Mode	`fill-mode-forwards fill-mode-backwards`

Integration with Other Skills

When	Skill	Why
After implementing	`code-quality`	Ensure code passes checks
Reusable patterns	`docs-write`	Document component API
Before committing	`git-commit`	Use `feat(ui):` or `style:`
Integration issues	`search`	Look up latest patterns

Output

Artifacts: Code changes only (no
```
.ada/
```
outputs)
Modifications: Component animations, CSS/Tailwind styles, Motion configs
Type: Workflow skill (guidance only, no scripts)

References

Internal

```
references/recipes.md
```
- Copy-paste patterns, integration examples, detailed traps

External

Motion Documentation
Material Design 3 Motion
Apple HIG - Motion
tailwindcss-animate
easings.net - Easing function cheat sheet

ui-animation

NPX Install

Tags

SKILL.md Content