motion

Motion

将此技能用于 Motion for React（motion / 原名 Framer Motion）以及产品动效设计（目的、令牌、无障碍、性能）。优先查阅最新的 motion.dev React 文档，不要依赖记忆——将说明限定在 [email protected]（最新版本为 13.5.0）。

**范围：**仅限 React 及基于 React 的框架（Next.js、Vite+React、Remix 等）。不要实现 Motion for Vue、仅使用原生技术的页面或 React Native。

并非每个悬停效果都需要 Motion。保留通用设计门槛；仅当项目已使用 Motion，或需要 CSS 之外的进入/退出、布局、手势或滚动联动动效时，才使用 Motion 实现。

核心规则（始终遵守）

在提出或编写动画前，先回答：

1. 界面发生了什么变化？
2. 为什么会发生变化？
3. 发生变化的对象从哪里来，要去哪里？
4. 用户接下来应该注意什么？
5. 用户能否不等装饰性效果完成就继续操作？
6. 对应的减少动态效果方案是什么？
7. 该动画会在合成器上运行，还是会触发布局或绘制？

如果不符合要求，就移除或简化。然后选择最小化工具：CSS → motion/react-mini / LazyMotion → 完整的 motion/react → 仅在适合截图式变形时使用 AnimateView / animateView（View Transitions）。

工作流

1. 确认 React 环境：motion/react 或 motion/react-client（Next App Router）。优先使用 bun add motion。不要为新的 React UI 生成 framer-motion、motion-v 或通过原生 CDN 使用的 Motion。
2. 从 source-map.md 更新版本、入口点和文档 URL。目标版本为 13.x。在 13.0+ 中，Emotion/Styled Components 需要显式使用 isValidProp 或反转组合方式——参见 packages-react.md。
3. 根据 foundations.md 应用产品动效原则（目的、令牌、时长/缓动）。
4. 对于声明式 API（motion.*、变体、过渡、arc()、手势、AnimatePresence、SVG），使用 setup-react-core.md。
5. 对于 MotionValues、useAnimate、滚动、布局/layoutId、Reorder 及相关 Hooks，使用 values-scroll-layout.md。
6. 对于通过 animateView（来自 "motion"）或 React AnimateView 组件（motion/react-animate-view，React 19.3+）实现的 View Transitions，使用 view-animations.md。
7. 对于 Next/RSC、Mini、LazyMotion 体积、迁移和 Motion+，使用 packages-react.md。
8. 对于 LazyMotion 配方、MotionConfig、减少动态效果、性能、测试和 AI 常见陷阱，使用 production-a11y.md。
9. 对于 CSS / WAAPI / FLIP / View Transitions / CSS 滚动驱动动画（不使用 Motion 时），使用 web-implementation.md。
10. 对于 UI 模式配方，使用 component-recipes.md。
11. 对于审查、交接和 QA，使用 deliverables-qa.md。如果重点涉及无障碍或性能，也加载 accessibility.md 和 performance.md。

实现判断

• 规范导入：import { motion, AnimatePresence } from "motion/react"。Next App Router：import * as motion from "motion/react-client" 或 "use client"。
• 根节点使用 <MotionConfig reducedMotion="user">——库的默认值是 "never"（除非主动启用，否则会忽略操作系统偏好）。
• 优先使用 transform / opacity；尺寸/位置变形使用 layout / layoutId（而非通过 animate 设置宽度/高度）。需要时使用 layout="x" / layout="y" / layout="position" 锁定轴向。
• 将 AnimatePresence 放在条件判断外部；使用稳定的 key；mode="wait" 仅适用于单个子元素。
• 编写新代码时，优先使用 delayChildren: stagger(...)，而不是旧版 staggerChildren。
• 曲线路径移动：使用 transition={{ path: arc() }} 或 transition.layout.path，而非 mini animate()。
• 自定义组件：只调用一次 motion.create(Component)（不要在渲染期间调用）；转发 refs。Motion 13：除非设置 MotionConfig isValidProp={isPropValid}，否则不要假定 Emotion 会过滤 prop。
• 高频滚动/拖动：使用 MotionValues + style，不要每帧都调用 useState。
• 包体积：使用 LazyMotion + 来自 motion/react-m 的 m；domAnimation 与 domMax（layout/drag）。
• Mini（motion/react-mini）不支持 x / y 等独立变换——请使用完整的 useAnimate 或 CSS transform。
• 视图过渡：使用来自 motion/react-animate-view 的 AnimateView（自 13.4 起免费；需要 React/React DOM 19.3+，且状态变更需在 startTransition 中进行）；对于较旧版本的 React，使用来自 "motion" 的命令式 animateView。不要假定 OSS 中包含 Motion+ / motion-plus。
• **Reorder：**除非要覆盖默认值，否则省略 axis；网格使用 "xy"；支持 RTL。

验证

• 从 motion/react（或 motion/react-client / react-m / react-mini / react-animate-view）导入，而不是从 framer-motion / motion-v 导入。
• 验证减少动态效果路径（MotionConfig 和/或 useReducedMotion）。
• 退出动画：使用 presence 包裹并设置 keys；中断/transition 设置应适合任务速度。
• Layout：使用 popLayout 时，父元素不能是 static；需要时使用 layoutScroll / layoutRoot。
• 测试：使用 transition={{ duration: 0 }} 或 false；需要时，在断言样式前等待 frame.postRender。
• 如果添加完整的 motion 而非 LazyMotion/mini，检查包体积。
• 13.0 之后的 CSS-in-JS：确保 style props 不会泄漏到 DOM（或使用 isValidProp / 反向组合）。