UI Animation Skill | Agent Skills

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() or 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

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)

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:

// ❌ 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

Agent Skills: UI Animation

Skill Files