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:
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:
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 explicitly includes migration.
- Passive App Router component with no hooks or client-only logic:
motion/react-client can be appropriate, but it is an exception, not the default.
- Leaf animations with hooks, route state, presence, reorder, or interactivity: use a small Client Component boundary.
See references/MIGRATION.md and references/DECISION_TREE.md.
3) Choose the lightest correct API
Use this decision rule:
- Simple local animation:
motion.*
- Bundle-sensitive shared shell:
m.* with LazyMotion
- Repeated parent/child orchestration: variants plus
stagger
- Mount/unmount or route exits:
AnimatePresence
- Layout changes from React re-render:
layout
- Shared-element transition:
layoutId
- Sibling layout coordination or namespaced shared layout IDs:
LayoutGroup
- Simple scroll reveal:
whileInView
- Scroll-linked progress or parallax:
useScroll plus motion values
- Imperative sequence or external trigger:
useAnimate
- Design-system component wrapper:
motion.create() with ref forwarding
See references/EXPERT_PLAYBOOK.md and references/DECISION_TREE.md.
4) Wire it correctly for the router
App Router
- Passive, hook-free animation in a server-friendly file: consider
motion/react-client.
- Interactive or hook-driven UI: create a small Client Component leaf and keep data fetching server-side.
- Client wrapper around server-rendered children: useful for modal shells, drawers, and local visibility wrappers.
- Route enter/exit choreography: mount a persistent Client shell from a layout so
AnimatePresence stays mounted.
- Segment replay on navigation:
template.tsx is useful when you want remount semantics at a specific segment boundary.
See references/APP_ROUTER.md.
Pages Router
- Keep
AnimatePresence stable in pages/_app.tsx for route transitions.
- Key routed children by a stable value that changes when you actually want a transition. For dynamic routes,
router.asPath is usually safer than router.route.
- Do not rewrite
_app.tsx for a one-off local animation.
See references/PAGES_ROUTER.md.
5) Apply the motion budget
Default ranges unless the user or design system says otherwise:
- Micro-interactions: 0.12s to 0.22s, scale no larger than 1.03, travel no more than 4px.
- Reveal / list entrance: 0.18s to 0.35s, travel 8px to 24px.
- Page / route transition: 0.22s to 0.45s, mostly opacity plus small Y translation.
- Layout animation: prefer Motion springs or
layout; do not fake these with large manual transforms.
See references/EXPERT_PLAYBOOK.md and references/PERFORMANCE.md.
6) Validate before finishing
Always check:
- No server/client boundary mistakes
- Reduced motion works
- Focus is preserved for interactive UI
- No unnecessary layout shift or stretched content
- No duplicate or conflicting route wrappers
- Project still builds
Run repo checks when available:
npm run lint
npm run build
For repo audits or skill iteration, also run:
node scripts/check-motion-antipatterns.mjs --root /path/to/repo
Use references/CHECKLIST.md before finalising. When improving the skill itself, use references/EVALUATION.md and node scripts/run-evaluation-pack.mjs.
Implementation rules
- Prefer animating transform and opacity. Avoid animating
top, left, large filters, and large shadows on big surfaces.
- When possible, turn the existing root element into a Motion element instead of adding a new wrapper. Extra wrappers often break layout, refs, selectors, or spacing.
- If using
m plus LazyMotion, use:
domAnimation for standard animations, variants, exit, hover, tap, and focus.
domMax only when you need layout animations or drag/pan.
- Use
AnimatePresence initial={false} for app-level wrappers unless first-load animation is explicitly desired.
- Use
AnimatePresence mode="wait" only when a single child should fully exit before the next enters.
- Never key exit-sensitive children by array index.
- Start with
layout before manual height choreography. If content stretches, add layout to the affected children or switch to layout="position" for aspect-ratio changes.
- If the scroll container is not the window, configure
viewport.root or use useInView with the correct root.
- When animating
next/image or image wrappers, preserve the layout box and animate transform or opacity rather than intrinsic size.
- When wrapping design-system components, call
motion.create() outside render and make sure the wrapped component forwards its ref.
- If the user did not explicitly ask for Motion and the effect is just a tiny hover or focus style on a static server-rendered element, CSS may be the cleaner answer.
Scripts
scripts/audit-nextjs-motion.mjs - inspects a repo, ranks likely target files, and emits JSON recommendations.
scripts/inspect-motion-target.mjs - inspects one file and recommends boundary, import path, risks, and likely pattern fit.
scripts/plan-motion-change.mjs - combines repo audit, target inspection, and task wording into a structured expert plan.
scripts/check-motion-antipatterns.mjs - scans a repo for common Motion and Framer Motion anti-patterns and emits JSON findings.
scripts/run-evaluation-pack.mjs - runs the bundled fixture-and-golden evaluation pack for skill iteration.
scripts/scaffold-motion-primitives.mjs - copies template components from assets/ into a target directory, with optional import rewriting for legacy framer-motion.
Reference map
references/EXPERT_PLAYBOOK.md - API selection, heuristics, motion tokens, anti-patterns
references/DECISION_TREE.md - fast pattern and boundary selection
references/APP_ROUTER.md - App Router boundaries, route shells, template.tsx, and server-friendly patterns
references/PAGES_ROUTER.md - _app.tsx, keys, dynamic route nuances
references/RECIPES.md - copy/paste implementations
references/PERFORMANCE.md - bundle size, LazyMotion, layout and scroll performance
references/ACCESSIBILITY.md - reduced motion, focus, modal guidance
references/MIGRATION.md - framer-motion to motion package strategy
references/TROUBLESHOOTING.md - failure modes and fixes
references/CHECKLIST.md - final review before finishing
references/EVALUATION.md - trigger tests, scenario fixtures, anti-pattern scans, and golden-output review
Output expectations
When modifying a repo, finish with:
- The files changed
- The Motion API and pattern chosen
- Boundary strategy and package migration decision, if any
- Reduced-motion handling
- Performance or bundle-size choices, if relevant
- Manual validation notes or commands run
- Any caveats the developer should know
Typical request mapping
- "Make this button feel better" -> micro-interaction recipe
- "Animate cards in on scroll" -> reveal recipe; variants if staggered
- "Add a smooth route transition in App Router" -> persistent layout-mounted shell or content wrapper, not a root rewrite by default
- "Animate this accordion or tab underline" ->
layout / layoutId / LayoutGroup
- "Make this drag list reorder smoothly" ->
Reorder.Group / Reorder.Item
- "This breaks in App Router" -> inspect boundary and import path before editing
- "Modernise our Framer Motion setup" -> audit first, then use
references/MIGRATION.md
1---
2name: nextjs-framer-motion-animations
3description: 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.
4license: MIT
5compatibility: 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.
6metadata:
7 source: https://skillmd.com/skills/tristanmanchester/nextjs-framer-motion-animations
8 author: openai
9 version: "4.0.0"
10 category: frontend-animation
11 keywords: nextjs,framer-motion,motion,react,animation,ui
12allowed-tools: Bash(node:*) Bash(npm:*) Bash(pnpm:*) Bash(yarn:*) Bash(bun:*) Read Write
13---
14
15# Next.js + Motion/Framer Motion
16
17## Mission
18Build 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.
19
20## Use this skill for
21- First-render reveals and section entrances
22- Hover, tap, and focus feedback on buttons, links, cards, tabs, and navigation
23- Scroll-triggered reveals and modest scroll-linked effects
24- Modals, drawers, dropdowns, accordions, tabs, and other enter/exit UI
25- Layout and shared-element transitions with `layout` and `layoutId`
26- Reorderable lists and light route-content transitions
27- Debugging Motion behaviour in Next.js
28
29## Do not use this skill for
30- GSAP-style timelines or cinematic sequences
31- Canvas, WebGL, Three.js, or Lottie-led animation systems
32- Heavy parallax or scroll-jacking storytelling
33- Large creative-direction rewrites
34- Pure CSS effects that do not justify client JavaScript, unless Motion is explicitly requested
35
36## Non-negotiables
37- Prefer the lightest Motion API that solves the task.
38- Preserve repo consistency. Do not mix `motion` and `framer-motion` imports in the same diff unless the task is an explicit migration.
39- Keep animated logic in the smallest possible Client Component boundary.
40- Respect reduced motion globally with `MotionConfig reducedMotion="user"` and locally with `useReducedMotion()` when behaviour must change.
41- Prefer reusable primitives, variants, and motion tokens over repeated inline animation objects.
42- Do not add a global provider, root-layout Client Component, or route-wide animation system unless the request genuinely needs it.
43
44## Default workflow
45
46### 1) Audit the codebase first
47Inspect:
48- Router type: `app/`, `pages/`, or both.
49- Current package: `motion`, `framer-motion`, or neither.
50- Existing animation patterns and design-system components.
51- Candidate transition boundaries: `app/layout.tsx`, `app/template.tsx`, `pages/_app.tsx`, shared UI shells.
52- Whether the change is local animation, mount/unmount animation, layout animation, shared-element animation, reorder, or scroll-linked animation.
53
54If shell access is available, run:
55```bash
56node scripts/audit-nextjs-motion.mjs --root /path/to/repo
57node scripts/inspect-motion-target.mjs path/to/target-file.tsx --root /path/to/repo
58node scripts/plan-motion-change.mjs --root /path/to/repo --target path/to/target-file.tsx --task "user request"
59```
60
61For broad skill iteration or repo-health checks, also run:
62```bash
63node scripts/check-motion-antipatterns.mjs --root /path/to/repo
64```
65
66### 2) Choose a package strategy
67Default rules:
68- **New work or modernised motion layer:** prefer the current `motion` package with imports from `motion/react`.
69- **Existing repo already on `framer-motion`:** stay consistent unless the task explicitly includes migration.
70- **Passive App Router component with no hooks or client-only logic:** `motion/react-client` can be appropriate, but it is an exception, not the default.
71- **Leaf animations with hooks, route state, presence, reorder, or interactivity:** use a small Client Component boundary.
72
73See `references/MIGRATION.md` and `references/DECISION_TREE.md`.
74
75### 3) Choose the lightest correct API
76Use this decision rule:
77- **Simple local animation:** `motion.*`
78- **Bundle-sensitive shared shell:** `m.*` with `LazyMotion`
79- **Repeated parent/child orchestration:** variants plus `stagger`
80- **Mount/unmount or route exits:** `AnimatePresence`
81- **Layout changes from React re-render:** `layout`
82- **Shared-element transition:** `layoutId`
83- **Sibling layout coordination or namespaced shared layout IDs:** `LayoutGroup`
84- **Simple scroll reveal:** `whileInView`
85- **Scroll-linked progress or parallax:** `useScroll` plus motion values
86- **Imperative sequence or external trigger:** `useAnimate`
87- **Design-system component wrapper:** `motion.create()` with ref forwarding
88
89See `references/EXPERT_PLAYBOOK.md` and `references/DECISION_TREE.md`.
90
91### 4) Wire it correctly for the router
92#### App Router
93- **Passive, hook-free animation in a server-friendly file:** consider `motion/react-client`.
94- **Interactive or hook-driven UI:** create a small Client Component leaf and keep data fetching server-side.
95- **Client wrapper around server-rendered children:** useful for modal shells, drawers, and local visibility wrappers.
96- **Route enter/exit choreography:** mount a persistent Client shell from a layout so `AnimatePresence` stays mounted.
97- **Segment replay on navigation:** `template.tsx` is useful when you want remount semantics at a specific segment boundary.
98
99See `references/APP_ROUTER.md`.
100
101#### Pages Router
102- Keep `AnimatePresence` stable in `pages/_app.tsx` for route transitions.
103- Key routed children by a stable value that changes when you actually want a transition. For dynamic routes, `router.asPath` is usually safer than `router.route`.
104- Do not rewrite `_app.tsx` for a one-off local animation.
105
106See `references/PAGES_ROUTER.md`.
107
108### 5) Apply the motion budget
109Default ranges unless the user or design system says otherwise:
110- **Micro-interactions:** 0.12s to 0.22s, scale no larger than 1.03, travel no more than 4px.
111- **Reveal / list entrance:** 0.18s to 0.35s, travel 8px to 24px.
112- **Page / route transition:** 0.22s to 0.45s, mostly opacity plus small Y translation.
113- **Layout animation:** prefer Motion springs or `layout`; do not fake these with large manual transforms.
114
115See `references/EXPERT_PLAYBOOK.md` and `references/PERFORMANCE.md`.
116
117### 6) Validate before finishing
118Always check:
119- No server/client boundary mistakes
120- Reduced motion works
121- Focus is preserved for interactive UI
122- No unnecessary layout shift or stretched content
123- No duplicate or conflicting route wrappers
124- Project still builds
125
126Run repo checks when available:
127```bash
128npm run lint
129npm run build
130```
131
132For repo audits or skill iteration, also run:
133```bash
134node scripts/check-motion-antipatterns.mjs --root /path/to/repo
135```
136
137Use `references/CHECKLIST.md` before finalising. When improving the skill itself, use `references/EVALUATION.md` and `node scripts/run-evaluation-pack.mjs`.
138
139## Implementation rules
140- Prefer animating **transform** and **opacity**. Avoid animating `top`, `left`, large filters, and large shadows on big surfaces.
141- When possible, turn the existing root element into a Motion element instead of adding a new wrapper. Extra wrappers often break layout, refs, selectors, or spacing.
142- If using `m` plus `LazyMotion`, use:
143 - `domAnimation` for standard animations, variants, exit, hover, tap, and focus.
144 - `domMax` only when you need layout animations or drag/pan.
145- Use `AnimatePresence initial={false}` for app-level wrappers unless first-load animation is explicitly desired.
146- Use `AnimatePresence mode="wait"` only when a single child should fully exit before the next enters.
147- Never key exit-sensitive children by array index.
148- Start with `layout` before manual height choreography. If content stretches, add `layout` to the affected children or switch to `layout="position"` for aspect-ratio changes.
149- If the scroll container is not the window, configure `viewport.root` or use `useInView` with the correct root.
150- When animating `next/image` or image wrappers, preserve the layout box and animate transform or opacity rather than intrinsic size.
151- When wrapping design-system components, call `motion.create()` outside render and make sure the wrapped component forwards its ref.
152- If the user did not explicitly ask for Motion and the effect is just a tiny hover or focus style on a static server-rendered element, CSS may be the cleaner answer.
153
154## Scripts
155- `scripts/audit-nextjs-motion.mjs` - inspects a repo, ranks likely target files, and emits JSON recommendations.
156- `scripts/inspect-motion-target.mjs` - inspects one file and recommends boundary, import path, risks, and likely pattern fit.
157- `scripts/plan-motion-change.mjs` - combines repo audit, target inspection, and task wording into a structured expert plan.
158- `scripts/check-motion-antipatterns.mjs` - scans a repo for common Motion and Framer Motion anti-patterns and emits JSON findings.
159- `scripts/run-evaluation-pack.mjs` - runs the bundled fixture-and-golden evaluation pack for skill iteration.
160- `scripts/scaffold-motion-primitives.mjs` - copies template components from `assets/` into a target directory, with optional import rewriting for legacy `framer-motion`.
161
162## Reference map
163- `references/EXPERT_PLAYBOOK.md` - API selection, heuristics, motion tokens, anti-patterns
164- `references/DECISION_TREE.md` - fast pattern and boundary selection
165- `references/APP_ROUTER.md` - App Router boundaries, route shells, `template.tsx`, and server-friendly patterns
166- `references/PAGES_ROUTER.md` - `_app.tsx`, keys, dynamic route nuances
167- `references/RECIPES.md` - copy/paste implementations
168- `references/PERFORMANCE.md` - bundle size, LazyMotion, layout and scroll performance
169- `references/ACCESSIBILITY.md` - reduced motion, focus, modal guidance
170- `references/MIGRATION.md` - `framer-motion` to `motion` package strategy
171- `references/TROUBLESHOOTING.md` - failure modes and fixes
172- `references/CHECKLIST.md` - final review before finishing
173- `references/EVALUATION.md` - trigger tests, scenario fixtures, anti-pattern scans, and golden-output review
174
175## Output expectations
176When modifying a repo, finish with:
1771. The files changed
1782. The Motion API and pattern chosen
1793. Boundary strategy and package migration decision, if any
1804. Reduced-motion handling
1815. Performance or bundle-size choices, if relevant
1826. Manual validation notes or commands run
1837. Any caveats the developer should know
184
185## Typical request mapping
186- "Make this button feel better" -> micro-interaction recipe
187- "Animate cards in on scroll" -> reveal recipe; variants if staggered
188- "Add a smooth route transition in App Router" -> persistent layout-mounted shell or content wrapper, not a root rewrite by default
189- "Animate this accordion or tab underline" -> `layout` / `layoutId` / `LayoutGroup`
190- "Make this drag list reorder smoothly" -> `Reorder.Group` / `Reorder.Item`
191- "This breaks in App Router" -> inspect boundary and import path before editing
192- "Modernise our Framer Motion setup" -> audit first, then use `references/MIGRATION.md`