web-animation-framer-motion

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: web-animation-framer-motion
description: Motion (formerly Framer Motion) animation patterns - motion components, variants, gestures, layout animations, scroll-linked animations, accessibility
---

# Motion Animation Patterns

> **Quick Guide:** Use Motion for declarative React animations. `motion.*` components for basic animations, variants for orchestrated sequences, AnimatePresence for exit animations, `layout`/`layoutId` for FLIP animations, `useScroll`/`useInView` for scroll-triggered effects. Always animate transform properties (x, y, scale, rotate, opacity) for GPU performance. Always respect reduced motion via `MotionConfig reducedMotion="user"`.

> **Import:** `import { motion } from "motion/react"` (v11+ package rename from `framer-motion`)

---

<critical_requirements>

## CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST wrap exiting components in AnimatePresence for exit animations to work)**

**(You MUST provide unique `key` prop to direct children of AnimatePresence)**

**(You MUST animate transform properties (x, y, scale, rotate, opacity) for GPU-accelerated performance)**

**(You MUST respect reduced motion preferences using MotionConfig or useReducedMotion)**

**(You MUST use named constants for all animation timing values - NO magic numbers)**

</critical_requirements>

---

**Auto-detection:** Motion, Framer Motion, motion.div, motion.button, AnimatePresence, useAnimation, useScroll, useInView, usePageInView, variants, whileHover, whileTap, layoutId, spring, tween, stagger, "motion/react", "framer-motion"

**When to use:**

- Animating component enter/exit/presence
- Orchestrating complex multi-element animations with variants
- Implementing gesture-based interactions (hover, tap, drag)
- Creating scroll-triggered or scroll-linked animations
- Animating layout changes and shared element transitions
- Building micro-interactions and UI feedback

**When NOT to use:**

- Simple CSS transitions (use CSS transitions instead)
- Complex timeline-based animations requiring frame-level control (consider a dedicated timeline animation library)
- Performance-critical animations on low-powered devices without careful optimization

**Key patterns covered:**

- motion components and animation props (initial, animate, exit, transition)
- Variants for reusable, orchestrated animations
- AnimatePresence for exit animations and animation modes
- Gesture props (whileHover, whileTap, whileDrag, drag)
- Layout animations (layout prop, layoutId, LayoutGroup)
- Scroll animations (useScroll, useInView, whileInView)
- Spring and tween transitions
- useAnimation for imperative control
- Reduced motion accessibility
- v12: usePageInView, enhanced stagger(), drag stop/cancel

---

**Detailed Resources:**

- [examples/core.md](examples/core.md) - Motion components, variants, AnimatePresence, gestures, accessibility
- [examples/layout.md](examples/layout.md) - Layout animations, shared elements, expandable cards
- [examples/scroll.md](examples/scroll.md) - Scroll progress, reveal, parallax
- [examples/sequences.md](examples/sequences.md) - Complex sequences, keyframes
- [examples/svg.md](examples/svg.md) - SVG path animations
- [reference.md](reference.md) - Decision frameworks, migration guide, anti-patterns, performance, quick reference

---

<philosophy>

## Philosophy

Motion is a declarative animation library for React that makes animations feel natural and accessible. It uses a physics-based approach with spring animations as defaults, creating fluid motion that matches real-world expectations.

**Core principles:**

1. **Declarative over imperative** - Describe what the animation should look like, not how to achieve it
2. **Props over keyframes** - Use `initial`, `animate`, `exit` props instead of CSS keyframes
3. **Variants for orchestration** - Group related animations and control timi