ui-animation（用户界面动画）

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

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

Workflow

Step 1: Classify Animation Type

Step 2: Choose Timing

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

Step 3: Implement

1. Check references/recipes.md for copy-paste patterns
2. Apply timing from Step 2
3. 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)

1. Check prefers-reduced-motion with useReducedMotion() or motion-safe:
2. Simplify to opacity-only for reduced motion users
3. 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

Pro Curves

Avoid: Built-in ease-in—starts slow, feels sluggish.

Duration Guidelines

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).

Physics-based (Legacy/Advanced)

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

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).

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

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

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

1. Only animate transform and opacity—GPU-accelerated
2. Never animate: width, height, top, left, margin, padding
3. will-change sparingly—only during animation, remove after
4. 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

1. 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

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

tailwindcss-animate

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

Integration with Other Skills

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