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 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:

bash

npm run lint
npm run build

For repo audits or skill iteration, also run:

bash

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

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
```

nextjs-framer-motion-animations

NPX Install

Tags

SKILL.md Content

Next.js + Motion/Framer Motion

Mission

Use this skill for

Do not use this skill for

Non-negotiables

Default workflow

1) Audit the codebase first

2) Choose a package strategy

3) Choose the lightest correct API

4) Wire it correctly for the router

App Router

Pages Router

5) Apply the motion budget

6) Validate before finishing

Implementation rules

Scripts

Reference map

Output expectations

Typical request mapping