nextjs-framer-motion-animations

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: nextjs-framer-motion-animations
description: Adds production-safe Motion for React or Framer Motion animations to Next.js apps, including reveal, hover and tap micro-interactions, whileInView, stagger, AnimatePresence, layout and layoutId transitions, reorder, scroll-linked UI, and lightweight route-content transitions. Use when the user asks to add, refactor, or debug Motion or Framer Motion in App Router or Pages Router codebases, especially around server/client boundaries, reduced motion, LazyMotion, bundle size, hydration, or route transitions. Avoid for GSAP-style timelines, WebGL or 3D scenes, heavy scroll storytelling, or CSS-only effects unless Motion is explicitly requested.
license: MIT
compatibility: Designed for Next.js projects with React 18.2+ and Node package tooling. Works with App Router and Pages Router. Supports legacy framer-motion repos and the current motion package. Bundled scripts use Node.js.
metadata:
  author: openai
  version: "4.0.0"
  category: frontend-animation
  keywords: nextjs,framer-motion,motion,react,animation,ui
allowed-tools: Bash(node:*) Bash(npm:*) Bash(pnpm:*) Bash(yarn:*) Bash(bun:*) Read Write
---

# Next.js + Motion/Framer Motion

## Mission
Build small, purposeful, accessible animations in Next.js using Motion for React (the current package) or legacy `framer-motion`, without breaking server/client boundaries, performance, or usability.

## Use this skill for
- First-render reveals and section entrances
- Hover, tap, and focus feedback on buttons, links, cards, tabs, and navigation
- Scroll-triggered reveals and modest scroll-linked effects
- Modals, drawers, dropdowns, accordions, tabs, and other enter/exit UI
- Layout and shared-element transitions with `layout` and `layoutId`
- Reorderable lists and light route-content transitions
- Debugging Motion behaviour in Next.js

## Do not use this skill for
- GSAP-style timelines or cinematic sequences
- Canvas, WebGL, Three.js, or Lottie-led animation systems
- Heavy parallax or scroll-jacking storytelling
- Large creative-direction rewrites
- Pure CSS effects that do not justify client JavaScript, unless Motion is explicitly requested

## Non-negotiables
- Prefer the lightest Motion API that solves the task.
- Preserve repo consistency. Do not mix `motion` and `framer-motion` imports in the same diff unless the task is an explicit migration.
- Keep animated logic in the smallest possible Client Component boundary.
- Respect reduced motion globally with `MotionConfig reducedMotion="user"` and locally with `useReducedMotion()` when behaviour must change.
- Prefer reusable primitives, variants, and motion tokens over repeated inline animation objects.
- Do not add a global provider, root-layout Client Component, or route-wide animation system unless the request genuinely needs it.

## Default workflow

### 1) Audit the codebase first
Inspect:
- Router type: `app/`, `pages/`, or both.
- Current package: `motion`, `framer-motion`, or neither.
- Existing animation patterns and design-system components.
- Candidate transition boundaries: `app/layout.tsx`, `app/template.tsx`, `pages/_app.tsx`, shared UI shells.
- Whether the change is local animation, mount/unmount animation, layout animation, shared-element animation, reorder, or scroll-linked animation.

If shell access is available, run:
```bash
node scripts/audit-nextjs-motion.mjs --root /path/to/repo
node scripts/inspect-motion-target.mjs path/to/target-file.tsx --root /path/to/repo
node scripts/plan-motion-change.mjs --root /path/to/repo --target path/to/target-file.tsx --task "user request"
```

For broad skill iteration or repo-health checks, also run:
```bash
node scripts/check-motion-antipatterns.mjs --root /path/to/repo
```

### 2) Choose a package strategy
Default rules:
- **New work or modernised motion layer:** prefer the current `motion` package with imports from `motion/react`.
- **Existing repo already on `framer-motion`:** stay consistent unless the task explicitl