UI Animation Skill

Relevant source files

The following files were used as context for generating this wiki page:

• skills/ui-animation/SKILL.md
• skills/ui-animation/references/recipes.md
• skills/README.md
• AGENTS.md
• README.md
• skills/docs-write/references/documentation-guide.md

The UI Animation skill is a workflow-based guide for AI agents and developers to implement tasteful, performant, and accessible UI animations. It provides principles and patterns for various animation types, including enter/exit transitions, layout animations, and gestures, using technologies like Tailwind CSS and Framer Motion. This skill does not execute scripts but rather provides structured guidance to ensure animations are purposeful and enhance the user experience.

The skill is triggered by terms such as animate, easing, spring, transition, motion, gesture, and reduced motion. It is one of several specialized capabilities in the AI Dev Atelier skill pack, designed to assist with production-grade development.

Sources: skills/ui-animation/SKILL.md:1-5, 153-155, skills/README.md:13, 38, AGENTS.md:32, README.md:38

Core Principles

The skill is founded on five core principles to ensure high-quality animations:

1. Natural Motion: Animations should mimic real-world physics. Linear easing is avoided as objects rarely move at a constant speed.
2. Purposeful: Every animation must have a clear purpose and add meaning to the interaction.
3. Fast: Animations should feel responsive. General UI animations should be under 300ms, and hover effects under 150ms.
4. Interruptible: Gesture-driven animations should use springs to handle user interruptions gracefully.
5. Accessible: Animations must always respect the prefers-reduced-motion user setting.

Sources: skills/ui-animation/SKILL.md:12-18

Animation Workflow

The skill defines a structured, five-step workflow for implementing any UI animation. This ensures all aspects from timing to accessibility are considered.

This diagram shows the standard workflow for implementing UI animations.

Step 1: Animation Classification

Animations are first classified by type to determine the appropriate implementation technique.

Type	Examples	Recommended 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

Sources: skills/ui-animation/SKILL.md:22-29

Step 2: Timing and Easing

Proper timing is crucial for making animations feel natural. The skill provides a decision tree for selecting the correct easing curve.

This flowchart illustrates how to choose an easing curve based on the animation's trigger.

Duration Guidelines

The perceived speed of an animation is determined by its duration.

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 include making exit animations faster than enter animations and keeping hover effects under 150ms.
Sources: skills/ui-animation/SKILL.md:76-88

Spring Animations

For physics-based, interruptible animations (e.g., gestures), springs are recommended over duration-based timing. The skill provides configurations for different "feels".

Feel	Duration-based Config	Physics-based Config	Use Case
Snappy	{ duration: 0.3, bounce: 0.15 }	{ stiffness: 400, damping: 30 }	Tabs, buttons, quick feedback
Standard	{ duration: 0.4, bounce: 0.2 }	{ stiffness: 300, damping: 20 }	Modals, menus, general UI
Gentle	{ duration: 0.5, bounce: 0.25 }	{ stiffness: 120, damping: 14 }	Smooth, human-like flow

Note: stiffness/damping will override duration/bounce. Developers must choose one approach.
Sources: skills/ui-animation/SKILL.md:90-110

Implementation Patterns & Gotchas

The skill references recipes.md for copy-paste patterns and provides guidance on common pitfalls.

Layout Animations

The layout prop in Framer Motion is used to automatically animate an element's position and size changes.

• layout={true}: Animates both position and size.
• layout="position": Animates only translation, preventing distortion of text and icons.
• layoutId: Creates a "shared element" transition between two components with the same ID. A common trap is duplicating layoutId values, which can cause elements to "teleport" unexpectedly.

Sources: skills/ui-animation/SKILL.md:112-129

AnimatePresence

To animate components as they are removed from the React tree (unmounted), they must be wrapped in <AnimatePresence>. Without this wrapper, exit animations will not run.

// ✅ Correct: Wrap in AnimatePresence to enable exit animations
import { motion, AnimatePresence } from "framer-motion";

function MyComponent({ isOpen }) {
  return (
    <AnimatePresence>
      {isOpen && (
        <motion.div
          initial={{ opacity: 0, y: 20 }}
          animate={{ opacity: 1, y: 0 }}
          exit={{ opacity: 0, y: -20 }}
        >
          My animated content
        </motion.div>
      )}
    </AnimatePresence>
  );
}

To prevent animations on initial page load in Server-Side Rendered (SSR) applications, use <AnimatePresence initial={false}>.
Sources: skills/ui-animation/SKILL.md:195-210, skills/ui-animation/references/recipes.md:118-124

Accessibility (Required)

Accessibility is a mandatory part of the workflow.

prefers-reduced-motion

All animations must respect the user's motion preference. The recommended practice is not to disable animations entirely but to simplify them, typically to a simple fade (opacity).

This can be checked in React with the useReducedMotion() hook from Framer Motion or in CSS with the motion-safe and motion-reduce variants in Tailwind.

import { useReducedMotion } from "motion/react"

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

Sources: skills/ui-animation/SKILL.md:141-151

Touch Targets

To prevent "fat finger" errors, touch targets must be adequately sized. The skill provides guidelines from different design systems.

Standard	Size	Tailwind Classes	Physical Size
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)

Sources: skills/ui-animation/SKILL.md:158-166

Performance

To ensure animations are smooth and don't cause "jank," the skill emphasizes two golden rules:

1. Only animate transform and opacity. These properties are GPU-accelerated and do not trigger expensive browser layout or paint operations.
2. Never animate layout properties like width, height, margin, or padding. Use transform: scale() or the layout prop instead.

A common performance trap is creating an element that is invisible (opacity: 0) but still clickable. This should be fixed by also setting pointer-events: "none".
Sources: skills/ui-animation/SKILL.md:168-180, skills/ui-animation/references/recipes.md:104-110

Integration with Other Skills

The UI Animation skill is designed to work in concert with other skills in the repository to maintain overall project quality.

This diagram shows how the UI Animation skill interacts with other development skills.

Summary

The UI Animation skill provides a comprehensive framework for creating high-quality, purposeful, and accessible animations. By following its structured workflow, core principles, and recommended patterns, developers and AI agents can ensure that animations enhance the user experience without compromising performance or accessibility. The skill's extensive guidance, from choosing easing curves to handling accessibility, makes it an essential tool in the AI Dev Atelier toolkit.

Sources: skills/ui-animation/SKILL.md, skills/README.md, docs-write/references/documentation-guide.md:120-123