nextjs-framer-motion-animations

# 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` 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: 1. The files changed 2. The Motion API and pattern chosen 3. Boundary strategy and package migration decision, if any 4. Reduced-motion handling 5. Performance or bundle-size choices, if relevant 6. Manual validation notes or commands run 7. 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`