motion

Files (14)

• SKILL.md
• accessibility-guide.md · references/
• common-patterns.md · references/
• core-concepts-deep-dive.md · references/
• motion-vs-auto-animate.md · references/
• nextjs-integration.md · references/
• performance-optimization.md · references/
• init-motion.sh · scripts/
• optimize-bundle.sh · scripts/
• layout-transitions.tsx · templates/
• motion-nextjs-client.tsx · templates/
• motion-vite-basic.tsx · templates/
• scroll-parallax.tsx · templates/
• ui-components.tsx · templates/

SKILL.md (first lines)

# Motion Animation Library

## Overview

Motion (package: `motion`, formerly `framer-motion`) is the industry-standard React animation library used in production by thousands of applications. With 30,200+ GitHub stars and 300+ official examples, it provides a declarative API for creating sophisticated animations with minimal code.

**Key Capabilities:**
- **Gestures**: drag, hover, tap, pan, focus with cross-device support
- **Scroll Animations**: viewport-triggered, scroll-linked, parallax effects
- **Layout Animations**: FLIP technique for smooth layout changes, shared element transitions
- **Spring Physics**: Natural, customizable motion with physics-based easing
- **SVG**: Path morphing, line drawing, attribute animation
- **Exit Animations**: AnimatePresence for unmounting transitions
- **Performance**: Hardware-accelerated, ScrollTimeline API, bundle optimization (2.3 KB - 34 KB)

**Production Tested**: React 19, Next.js 15, Vite 6, Tailwind v4

---

## When to Use This Skill

### ✅ Use Motion When:

**Complex Interactions**:
- Drag-and-drop interfaces (sortable lists, kanban boards, sliders)
- Hover states with scale/rotation/color changes
- Tap feedback with bounce/squeeze effects
- Pan gestures for mobile-friendly controls

**Scroll-Based Animations**:
- Hero sections with parallax layers
- Scroll-triggered reveals (fade in as elements enter viewport)
- Progress bars linked to scroll position
- Sticky headers with scroll-dependent transforms

**Layout Transitions**:
- Shared element transitions between routes (card → detail page)
- Expand/collapse with automatic height animation
- Grid/list view switching with smooth repositioning
- Tab navigation with animated underline

**Advanced Features**:
- SVG line drawing animations
- Path morphing between shapes
- Spring physics for natural bounce
- Orchestrated sequences (staggered reveals)
- Modal dialogs with backdrop blur

**Bundle Optimization**:
- Need 2.3 KB animation library (useAnimate mini)
- Want to reduce Motion from 34 KB to 4.6 KB (LazyMotion)

### ❌ Don't Use Motion When:

- **Simple list animations** (use `auto-animate` instead: 3.28 KB vs 34 KB)
- **Static content** without interactions
- **Cloudflare Workers** (use `framer-motion` v12.23.24 workaround - see Known Issues)
- **3D animations** (use Three.js or React Three Fiber instead)

---

## Installation

### Latest Stable Version

```bash
bun add motion  # preferred
# or: npm install motion
# or: yarn add motion
```

**Current Version**: 12.23.24 (verified 2025-11-07)

**Alternative for Cloudflare Workers**:
```bash
# Use framer-motion if deploying to Cloudflare Workers
bun add framer-motion
# or: npm install framer-motion
```

### Package Information

- **Bundle Size**:
  - Full `motion` component: ~34 KB minified+gzipped
  - `LazyMotion` + `m` component: ~4.6 KB
  - `useAnimate` mini: 2.3 KB (smallest React animation library)
  - `useAnimate` hybrid: 17 KB
- **Dependencies**: React 18+ or React 19+
- **TypeScript**: Native support included (no @types package needed)

---

## Core Concepts

### 1. The `motion` Component

Transform any HTML/SVG element into an animatable component:

```tsx
import { motion } from "motion/react"

// Basic animation
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  Content fades in and slides up
</motion.div>

// Gesture controls
<motion.button
  whileHover={{ scale: 1.1 }}
  whileTap={{ scale: 0.95 }}
>
  Click me
</motion.button>
```

From WannaCry081/Bunban, MIT.

More from WannaCry081/Bunban