nextjs-framer-motion-animations
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
- 最近更新
- 2026-10-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- nextjs-framer-motion-animations
- license
- MIT
- metadata
- { "author": "openai", "version": "4.0.0", "category": "frontend-animation", "keywords": "nextjs,framer-motion,motion,react,animation,ui" }
- 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.
- allowed-tools
- Bash(node:*) Bash(npm:*) Bash(pnpm:*) Bash(yarn:*) Bash(bun:*) Read Write
- 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.
02 资源文件 76
- 资产文件assets/app-template.tsx243 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/app/layout.tsx210 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/app/page.tsx572 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/components/bad-factory.tsx247 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/components/bad-list.tsx379 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/components/bad-passive.tsx361 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/components/bad-tabs.tsx667 B
- 资产文件assets/evaluation-pack/fixtures/anti-pattern-broken/package.json211 B
- 资产文件assets/evaluation-pack/fixtures/app-router-client-modal/app/settings/page.tsx264 B
- 资产文件assets/evaluation-pack/fixtures/app-router-client-modal/components/settings-drawer.tsx780 B
- 资产文件assets/evaluation-pack/fixtures/app-router-client-modal/package.json183 B
- 资产文件assets/evaluation-pack/fixtures/app-router-passive-card/app/page.tsx698 B
- 资产文件assets/evaluation-pack/fixtures/app-router-passive-card/components/product-card.tsx465 B
- 资产文件assets/evaluation-pack/fixtures/app-router-passive-card/package.json183 B
- 资产文件assets/evaluation-pack/fixtures/app-router-route-shell/app/dashboard/[team]/page.tsx304 B
- 资产文件assets/evaluation-pack/fixtures/app-router-route-shell/app/dashboard/page.tsx252 B
- 资产文件assets/evaluation-pack/fixtures/app-router-route-shell/app/layout.tsx410 B
- 资产文件assets/evaluation-pack/fixtures/app-router-route-shell/package.json182 B
- 资产文件assets/evaluation-pack/fixtures/design-system-button/app/page.tsx182 B
- 资产文件assets/evaluation-pack/fixtures/design-system-button/components/ui/button.tsx460 B
- 资产文件assets/evaluation-pack/fixtures/design-system-button/package.json180 B
- 资产文件assets/evaluation-pack/fixtures/pages-router-legacy-route-transition/package.json203 B
- 资产文件assets/evaluation-pack/fixtures/pages-router-legacy-route-transition/pages/_app.tsx148 B
- 资产文件assets/evaluation-pack/fixtures/pages-router-legacy-route-transition/pages/blog/[slug].tsx367 B
- 资产文件assets/evaluation-pack/fixtures/shared-layout-tabs/app/settings/page.tsx321 B
- 资产文件assets/evaluation-pack/fixtures/shared-layout-tabs/components/settings-tabs.tsx709 B
- 资产文件assets/evaluation-pack/fixtures/shared-layout-tabs/package.json178 B
- 资产文件assets/evaluation-pack/goldens/anti-pattern-broken.json379 B
- 资产文件assets/evaluation-pack/goldens/anti-pattern-broken.md447 B
- 资产文件assets/evaluation-pack/goldens/app-router-client-modal.json259 B
- 资产文件assets/evaluation-pack/goldens/app-router-client-modal.md258 B
- 资产文件assets/evaluation-pack/goldens/app-router-passive-card.json298 B
- 资产文件assets/evaluation-pack/goldens/app-router-passive-card.md278 B
- 资产文件assets/evaluation-pack/goldens/app-router-route-shell.json330 B
- 资产文件assets/evaluation-pack/goldens/app-router-route-shell.md267 B
- 资产文件assets/evaluation-pack/goldens/design-system-button.json272 B
- 资产文件assets/evaluation-pack/goldens/design-system-button.md207 B
- 资产文件assets/evaluation-pack/goldens/pages-router-legacy-route-transition.json287 B
- 资产文件assets/evaluation-pack/goldens/pages-router-legacy-route-transition.md254 B
- 资产文件assets/evaluation-pack/goldens/shared-layout-tabs.json262 B
- 资产文件assets/evaluation-pack/goldens/shared-layout-tabs.md203 B
- 资产文件assets/evaluation-pack/manifest.json2.9 KB
- 资产文件assets/evaluation-pack/output-contract.json888 B
- 资产文件assets/evaluation-pack/trigger-tests.json1.3 KB
- 资产文件assets/fade-in-on-mount.tsx447 B
- 资产文件assets/imperative-list-reveal.tsx610 B
- 资产文件assets/modal-shell.tsx998 B
- 资产文件assets/motion-button.tsx359 B
- 资产文件assets/motion-link-button.tsx471 B
- 资产文件assets/motion-provider.tsx390 B
- 资产文件assets/pages-app.tsx391 B
- 资产文件assets/reorder-list.tsx460 B
- 资产文件assets/reveal.tsx489 B
- 资产文件assets/route-transition-shell.tsx918 B
- 资产文件assets/scroll-progress.tsx393 B
- 资产文件assets/server-motion-card.tsx560 B
- 资产文件assets/shared-tabs.tsx957 B
- 资产文件assets/stagger-list.tsx638 B
- 许可证LICENSE.txt1.0 KB
- 参考文档references/ACCESSIBILITY.md2.0 KB
- 参考文档references/APP_ROUTER.md5.0 KB
- 参考文档references/CHECKLIST.md2.3 KB
- 参考文档references/DECISION_TREE.md3.5 KB
- 参考文档references/EVALUATION.md3.4 KB
- 参考文档references/EXPERT_PLAYBOOK.md4.9 KB
- 参考文档references/MIGRATION.md2.1 KB
- 参考文档references/PAGES_ROUTER.md2.1 KB
- 参考文档references/PERFORMANCE.md2.7 KB
- 参考文档references/RECIPES.md8.5 KB
- 参考文档references/TROUBLESHOOTING.md4.5 KB
- 脚本scripts/audit-nextjs-motion.mjs13.4 KB
- 脚本scripts/check-motion-antipatterns.mjs9.4 KB
- 脚本scripts/inspect-motion-target.mjs7.6 KB
- 脚本scripts/plan-motion-change.mjs17.7 KB
- 脚本scripts/run-evaluation-pack.mjs6.1 KB
- 脚本scripts/scaffold-motion-primitives.mjs4.2 KB
03 SKILL.md 正文
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
layoutandlayoutId - 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
motionandframer-motionimports 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 withuseReducedMotion()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
motionpackage with imports frommotion/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-clientcan 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.*withLazyMotion - 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:
useScrollplus 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
AnimatePresencestays mounted. - Segment replay on navigation:
template.tsxis useful when you want remount semantics at a specific segment boundary.
See references/APP_ROUTER.md.
Pages Router
- Keep
AnimatePresencestable inpages/_app.tsxfor route transitions. - Key routed children by a stable value that changes when you actually want a transition. For dynamic routes,
router.asPathis usually safer thanrouter.route. - Do not rewrite
_app.tsxfor 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
mplusLazyMotion, use:domAnimationfor standard animations, variants, exit, hover, tap, and focus.domMaxonly 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
layoutbefore manual height choreography. If content stretches, addlayoutto the affected children or switch tolayout="position"for aspect-ratio changes. - If the scroll container is not the window, configure
viewport.rootor useuseInViewwith the correct root. - When animating
next/imageor 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 fromassets/into a target directory, with optional import rewriting for legacyframer-motion.
Reference map
references/EXPERT_PLAYBOOK.md- API selection, heuristics, motion tokens, anti-patternsreferences/DECISION_TREE.md- fast pattern and boundary selectionreferences/APP_ROUTER.md- App Router boundaries, route shells,template.tsx, and server-friendly patternsreferences/PAGES_ROUTER.md-_app.tsx, keys, dynamic route nuancesreferences/RECIPES.md- copy/paste implementationsreferences/PERFORMANCE.md- bundle size, LazyMotion, layout and scroll performancereferences/ACCESSIBILITY.md- reduced motion, focus, modal guidancereferences/MIGRATION.md-framer-motiontomotionpackage strategyreferences/TROUBLESHOOTING.md- failure modes and fixesreferences/CHECKLIST.md- final review before finishingreferences/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
04 同仓库更多 Skills
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
seo-audit
Full website SEO audit with parallel subagent delegation. Crawls up to 500 pages, detects business type, delegates to up to 15 specialists (8 always + 7 conditional), generates health score. Use when user says audit, full SEO check, analyze my site, or website health check.
playwright
Use when the task requires automating a real browser from the terminal (navigation, form filling, snapshots, screenshots, data extraction, UI-flow debugging) via `playwright-cli` or the bundled wrapper script.
gsap-performance
Official GSAP skill for performance — prefer transforms, avoid layout thrashing, will-change, batching. Use when optimizing GSAP animations, reducing jank, or when the user asks about animation performance, FPS, or smooth 60fps.
firecrawl-seo-audit
Audit a website's SEO with Firecrawl. Use when the user asks for an SEO audit, metadata and heading review, sitemap/site-structure analysis, keyword opportunities, competitor SERP comparison, or prioritized search optimization recommendations.
firecrawl-qa
QA test a live website with Firecrawl browser and scrape evidence. Use when the user wants exploratory QA, form testing, navigation/link checks, responsive checks, performance observations, bug reports, or a pre-launch quality review.