motion

Motion

Use this skill for Motion for React (motion / formerly Framer Motion) and for product motion design (purpose, tokens, a11y, performance). Prefer current motion.dev React docs over memory — pin narrative to [email protected] (latest 13.5.0).

Scope: React and React-based frameworks only (Next.js, Vite+React, Remix, etc.). Do not implement Motion for Vue, vanilla-only pages, or React Native.

Motion is not required for every hover. Keep general design gates; implement with Motion when the project already uses it or needs enter/exit, layout, gestures, or scroll-linked motion beyond CSS.

Core Rule (always)

Before proposing or coding animation, answer:

1. What changed in the interface?
2. Why did it change?
3. Where did the changed thing come from, and where is it going?
4. What should the user notice next?
5. Can the user keep working without waiting for decoration?
6. What is the reduced-motion equivalent?
7. Will this animate on the compositor, or does it trigger layout or paint?

If it fails, remove it or simplify. Then choose the smallest tool: CSS → motion/react-mini / LazyMotion → full motion/react → AnimateView / animateView (View Transitions) only when a screenshot-style morph fits.

Workflow

1. Confirm React surface: motion/react or motion/react-client (Next App Router). Prefer bun add motion. Do not generate framer-motion, motion-v, or vanilla CDN Motion for new React UI.
2. Refresh versions, entry points, and doc URLs from source-map.md. Target 13.x. On 13.0+, Emotion/Styled Components need explicit isValidProp or reversed composition — packages-react.md.
3. Apply product motion judgment from foundations.md (purpose, tokens, duration/easing).
4. For declarative APIs (motion.*, variants, transitions, arc(), gestures, AnimatePresence, SVG), use setup-react-core.md.
5. For MotionValues, useAnimate, scroll, layout/layoutId, Reorder, and related hooks, use values-scroll-layout.md.
6. For View Transitions via animateView (from "motion") or the React AnimateView component (motion/react-animate-view, React 19.3+), use view-animations.md.
7. For Next/RSC, Mini, LazyMotion sizing, migration, and Motion+, use packages-react.md.
8. For LazyMotion recipes, MotionConfig, reduced motion, performance, testing, and AI traps, use production-a11y.md.
9. For CSS / WAAPI / FLIP / View Transitions / scroll-driven CSS (when not using Motion), use web-implementation.md.
10. For UI pattern recipes, use component-recipes.md.
11. For audits, handoff, and QA, use deliverables-qa.md. Also load accessibility.md and performance.md when those are the focus.

Implementation Judgment

• Canonical import: import { motion, AnimatePresence } from "motion/react". Next App Router: import * as motion from "motion/react-client" or "use client".
• Root <MotionConfig reducedMotion="user"> — library default is "never" (OS preference ignored until you opt in).
• Prefer transform / opacity; use layout / layoutId for size/position morphs (not animate width/height). Axis-lock with layout="x" / layout="y" / layout="position" when needed.
• AnimatePresence outside the conditional; stable keys; mode="wait" is single-child only.
• Prefer delayChildren: stagger(...) over legacy staggerChildren for new code.
• Curved travel: transition={{ path: arc() }} or transition.layout.path — not mini animate().
• Custom components: motion.create(Component) once (never inside render); forward refs. Motion 13: do not assume Emotion prop filtering unless MotionConfig isValidProp={isPropValid}.
• High-frequency scroll/drag: MotionValues + style, not useState every frame.
• Bundle: LazyMotion + m from motion/react-m; domAnimation vs domMax (layout/drag).
• Mini (motion/react-mini) cannot use independent transforms like x / y — use full useAnimate or CSS transform.
• View Transitions: AnimateView from motion/react-animate-view (free since 13.4; needs React/React DOM 19.3+, state changes in startTransition) or imperative animateView from "motion" on older React. Do not assume Motion+ / motion-plus in OSS.
• Reorder: omit axis unless overriding; "xy" for grids; RTL is supported.

Verification

• Imports from motion/react (or motion/react-client / react-m / react-mini / react-animate-view), not framer-motion / motion-v.
• Reduced-motion path exercised (MotionConfig and/or useReducedMotion).
• Exit animations: presence wrapping + keys; interrupt/transition sensible for task speed.
• Layout: non-static parent for popLayout; layoutScroll / layoutRoot when needed.
• Tests: transition={{ duration: 0 }} or false; await frame.postRender before style asserts when needed.
• Bundle check if adding full motion vs LazyMotion/mini.
• CSS-in-JS after 13.0: no leaked style props on the DOM (or isValidProp / reverse composition).