实现运动
概述
本技能指导如何将 Figma 中的动画和过渡转换为可运行的代码(motion.dev、CSS keyframes 或特定框架的动画库)。
Figma 通过两个工具暴露运动数据:
get_motion_context— 权威的运动工具。返回完整的动画节点清单、预计算的代码片段(CSS@keyframes+ motion.dev)、当无可用片段时的回退关键帧绑定,以及递归的时间线协作提示(timelineCohorts)。是动画数据和哪些节点 ID 具有动画效果的唯一真实来源。get_design_context— 设计的结构:布局、尺寸、资产、样式、Code Connect 提示、截图上下文,有时还包括动画元素上的运动放置标记(data-node-id,以及在拆分节点上的data-motion-keys/data-motion-wrapper-for/data-motion-transform-template)。它可能将动画节点渲染为普通元素(div、p、span等)或 motion 元素(motion.div);但不会内联实际的动画值。
两者通过节点 ID 关联,这就是整个工作流的核心。 get_motion_context 告诉你哪些节点有动画,并提供关键帧值、缓动、时序和代码片段。get_design_context 告诉你这些节点的外观和位置。对于 get_motion_context.nodes 中的每个节点,在设计上下文中找到匹配的 data-node-id,并将运动合并到该结构中——当结构性元素为普通元素时,添加或包装成 motion.{tag}。当设计上下文复用了 Figma 组件时,运动节点可能还包含 fallbackNodeId;只有在精确的 nodeId 匹配失败后才使用它作为回退。
技能边界
- 当交付物是用户仓库中的运动代码时,使用此技能。
- 如果用户要求在 Figma 内部创建/编辑动画,请切换到 figma-use 并遵循该技能。
- 本技能目前涵盖
get_motion_context输出的动画(代码片段加上回退关键帧轨道,包括通过预设生成的动画,这些动画已解析为这些形式)。更广泛的交互式变体流程可能仍需要在代码中进行特定产品的状态处理。
前提条件
- Figma MCP 服务器已连接并可访问。
- 从用户提供的 Figma URL 中解析出节点 ID。URL 格式:
https://figma.com/design/:fileKey/:fileName?node-id=1-2— 提取fileKey(/design/后的段)和nodeId(node-id查询参数的值,例如42-15)。 - 目标代码库。运动输出格式会根据技术栈进行适配(参见框架推荐)。
工具选择
对于运动实现,需同时使用两个工具,它们具有不同的角色:
| 情况 | 工具 | 原因 |
|---|---|---|
| 理解静态结构、资产、样式、Code Connect 或视觉布局 | get_design_context | 提供正确放置动画节点所需的组件/页面代码引用和资产 URL。 |
| 获取任何节点的动画数据 | get_motion_context | 专为运动构建,是时序、缓动、代码片段和关键帧的唯一真实来源。 |
节点具有运动标记(data-motion-keys、data-motion-wrapper-for) | 标记用于拆分放置,get_motion_context 用于值 | 拆分标记告诉你哪些轨道放在哪个元素上;关键帧/缓动/时序和动画节点清单来自 get_motion_context。 |
get_motion_context 接受 recursive: true(上限 500 个节点),当你需要一次调用获取所有后代的运动数据时使用。
必需工作流
步骤 1:确认静态设计上下文可用
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
如果该节点的 get_design_context 已经被调用过,则复用该输出。否则,正常调用它。
将其用作记录的结构 — 层级、尺寸、样式、资产、Code Connect 提示、截图上下文以及它可能包含的任何运动放置标记(步骤 3)。动画节点清单和动画值来自 get_motion_context(步骤 2)。
步骤 2:获取权威运动数据
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
响应形状(每个动画节点一个条目):
codeSnippets— 预生成的 CSS@keyframes和 motion.dev 字符串。直接使用这些。 不要从回退轨道数据重新生成。keyframeBindings— 绑定的关键帧轨道,包括从预设派生的运动解析为轨道数据,当两种代码片段格式都缺失时,仅作为回退数据包含。motionSummary— 每行一个字段的自然语言描述动画。仅在无代码片段时存在(仅有关键帧绑定的运动代码生成无法表示为 CSS/motion.dev)。当它存在时,基于它构建;当存在任何代码片段时忽略它。fallbackNodeId— 可选的用于匹配组件化设计上下文的回退 ID。如果nodeId是一个实例限定的 ID,例如I4005:6111;30:8005,D2R 可能会改用底层组件 ID(例如4002:3957)渲染可重用组件的主体。在这种情况下,fallbackNodeId是当精确nodeId查找失败时要查找的data-node-id。
递归响应还包括 timelineCohorts — 一个顶层数组(不是每个节点的)共享同一时间线的节点:{ rootNodeId, durationMs, loopMode: 'once' | 'loop' | 'boomerang', memberNodeIds[] }。对于协调的多节点运动,使用 durationMs(÷1000 转换为秒)和 loopMode 从一个共享的生命周期驱动所有 memberNodeIds — 不要从兄弟顺序推断时序。
对 LLM 有意义的实现细节:
- 当代码片段存在时,
motionSummary、timelineDurationMs和transformOrigin可能会被省略以减小有效载荷 — 代码片段已经包含了持续时间和 transform-origin(motion.dev 的duration/style={{ transformOrigin }},或 CSS 的animation/transform-origin),而 cohort 包含了durationMs。缺失字段绝不意味着“无动画”。 - 递归响应会去重完全相同的代码片段。代码片段可能会被替换为指向具有相同运动的首个节点的注释;复用相同的组件、变体、类或常量,而不是编写第二个动画。
- MCP 服务器会根据
clientFrameworks推断 CSS 还是 motion.dev 代码片段;如果响应只包含一种代码片段格式,则将该格式适应用户的技术栈,而不是假定另一种格式失败。
步骤 3:合并静态和运动上下文
- 从
get_motion_context.nodes开始,而不是从静态 JSX 中可见的motion.*标签。返回的每个节点都是有动画的。 首先通过精确的nodeId/data-node-id将每个运动节点匹配回get_design_context。当且仅当没有精确匹配时,尝试使用fallbackNodeId/data-node-id。仅在这两个 ID 都失败后,才根据节点名称/类型和截图位置进行回退。 - 精确 ID 匹配优先于
fallbackNodeId。fallbackNodeId指向 D2R 可能在可重用组件内部发出的底层组件 ID。该组件的每个实例都共享它。如果精确的nodeId存在于设计上下文中,则将运动应用于该处并忽略回退。这对于根实例动画至关重要:一个实例可以旋转或移动得与同一组件的另一个实例不同,如果将那个运动应用于共享的组件主体,则会导致所有实例错误地一起动画。 - 将每个运动节点应用于匹配的设计上下文结构,以
data-node-id为键。 匹配的data-node-id是结构定位点,但不总是接收运动的最终 DOM 元素。使用代码片段形状和放置标记来决定运动是放在精确元素、包装器、内部元素还是内联 SVG 路径上。get_design_context可能已经发出带有剥离值的motion.{tag},或者可能发出一个普通的结构性元素(div、p、span、组件根等)。如果它是普通元素并且代码片段目标是该元素本身,则将其转换为适当的motion.{tag}或添加一个 motion 包装器,同时保留节点的文本、子元素、类/样式、属性和data-node-id。加载 references/examples-and-anti-examples.md 查看此合并步骤的示例。 - 组件化的子运动通常通过回退匹配。 当设计上下文将 Figma 实例提取为可重用的 React 组件时,该组件主体内的子元素通常具有底层组件 ID(
4002:3957),而运动上下文报告实时实例 ID(I4005:6111;30:8005)。在这种情况下,使用fallbackNodeId找到组件主体的data-node-id,但将运动范围限定在你正在实现的渲染实例上。如果有多个实例且只有一个具有不同的根运动,则精确 ID 匹配可保持该实例特定的运动分离。 - 拆分节点带有
data-motion-keys/data-motion-wrapper-for标记 — 参见下面的处理交错变换。 - 保留
display: contents包装器 — 除非组本身有动画。 布局透明的组包装器会以contents(Tailwindcontents)的形式出现,通常伴随着一个无效的absolute/inset-[…](这些对contents框无效)。对于一个静态组,保留display: contents并让子元素相对于最近的真正祖先进行定位 — 将包装器的inset转换为定位框会导致子元素被重新定位到一个更小的框,从而使得它们渲染得太小/向内偏移。对于一个有动画的组(组节点本身具有运动),display: contents无法承载变换 — 将其替换为真正的定位包装器并在那里应用组运动。在实现此案例之前,请加载 references/gotchas.md。 get_motion_context是完整的动画节点清单。 一些动画节点渲染为普通(非motion)元素 — 组件实例根(普通定位<div>)、文本(<p>)、遮罩 — 这些元素仍然带有data-node-id。遍历运动响应中的每个节点,并将其运动应用于具有匹配data-node-id的元素,根据需要进行包装或转换。如果输出中根本不存在某个动画节点的元素(例如,扁平化为静态mask-image的动画遮罩),不要静默地丢弃它 — 留下一个// TODO:<nodeId> 运动不支持注释并在你的摘要中提及。- 如果节点出现在运动上下文中但不在静态 JSX 中,则添加表示它所需的元素 — 设计上下文代码是一个参考,而不是完整的动画清单。
- 在设计和运动上下文之间存在冲突时(时序/缓动/动画值),优先使用
get_motion_context。 - 路径级 SVG 运动:内联 SVG 并为真正的
<path>制作动画。 当get_motion_context目标是矢量的路径(PATH_TRIM、motion.path、stroke-dasharray)但设计上下文将其渲染为<img>时,内联 SVG 并将代码片段应用于<path>,同时保留布局包装器。加载 references/svg-and-path-motion.md 获取此情况(motion.path、pathLength="1"、包装器+路径分层、CSS 路径修剪)的完整指南。
处理交错变换
一个同时具有静态基础变换和动画变换的节点会被拆分到嵌套的元素上,以便两者正确合成而不会冲突:一个没有 ID 的 motion.div 带有 data-motion-wrapper-for="<nodeId>"(外部包装器),它包裹着一个包含静态变换的 div(例如 rotate-45 + hypot() 尺寸处理 — 或者包装器本身带有 data-motion-transform-template="<css>"),而这个 div 又包裹着内部的节点(data-node-id)。保持 包装器 > 静态变换 div > 内部元素 的嵌套 — 折叠它会破坏尺寸和基础变换。
- 通过
data-motion-keys放置轨道。 包装器的data-motion-keys(变换轨道 —x/y/rotate/scaleX/scaleY/skewX)放在外部包装器上;内部元素的data-motion-keys放在内部元素上。 - 重新应用
data-motion-transform-template。 如果包装器带有该模板,则设置transformTemplate={(_, generated) => "<css> " + generated},以便动画变换在此基础上与静态布局变换组合。 - 使动画变换偏移静态基础(避免双重旋转)。
get_motion_context提供节点的绝对变换,这已经包含了那些 div 应用的任何静态基础。一个在rotate-45基础之上的rotate代码片段[45, 125, 125]意味着包装器对偏移量[0, 80, 80](= 绝对值 − 45)进行动画,而不是绝对值 — 否则 45° 会应用两次,元素在静止时会处于 90° 位置。没有静态基础的轨道(例如从 0 开始的x/y)保持不变。请参见交错变换示例。 - 将布局变换与 Motion 变换分开。 对于每个动画
rotate、scale或skew的motion.*元素,验证它不依赖 Tailwind 布局变换(例如用于居中/定位的-translate-x-1/2或-translate-y-1/2)。这些工具共享 Motion.dev 内联写入的 CSStransform属性,因此 Motion 的变换可能会擦除布局平移。如果两者都需要,则将元素拆分为一个承载居中/定位变换的静态布局包装器和一个承载动画旋转/缩放/透明度的内部motion.*元素,或者在 Motion 本身中对布局偏移进行编码(x: "-50%")并使其在每个关键帧中都存在。
步骤 4:在代码中应用运动
- 代码片段中存在 motion.dev? 对于 React 目标,直接使用 motion.dev 代码。从
motion/react导入 — 除非代码库已经使用另一个 motion 库(Framer Motion、React Spring、GSAP),在这种情况下,将代码片段适配到该库。在适配到其他技术栈或选择库时,请加载 references/framework-recommendations.md。 - 存在 CSS 关键帧? 用于普通/非 React 目标,或者当代码库中没有 React motion 库时。
- 没有代码片段(仅有关键帧绑定)? 从
keyframeBindings数据构建等效的 motion.dev/CSS。 - 始终在应用过程中引用
get_motion_context的motionSummary以理解动画意图(例如,"浮动" 与 "脉动"),并确保代码反映预期的用户体验。 - 为 motion.dev 使用
AnimatePresence实现进入/离开动画 当在条件渲染或列表中使用motion.*组件时。 - 当存在
timelineCohorts时,设置loopMode和协调的durationMs。 对于协调组内的节点,使用durationMs(/1000 转换为秒)来设置动画持续时间。对于loopMode:'once'— 播放一次,然后停止。'loop'— 无限循环。'boomerang'— 向前播放然后向后播放,形成一个连续循环。 对于协调组,从父级或一个集中的生命周期(例如使用motion的useAnimatehook,或 React 组件挂载/状态)驱动所有成员节点,而不是为每个子元素独立触发它们。
框架推荐
motion.dev(首选 React 目标)
- 从
motion/react导入motion。 - 如果
get_motion_context提供了 motion.dev 代码片段,直接使用。 - 对于关键帧动画,使用
motion.div(或适当的标签)并设置animate属性,可选择性地指定initial、transition和whileInView。
CSS 关键帧(非 React 或任何 Web 项目)
- 从
get_motion_context的codeSnippets.css复制 CSS@keyframes。 - 使用
animation-name、animation-duration、animation-timing-function和animation-iteration-count将它们应用到正确的选择器。
重要考虑因素
- 不要重新生成或修改代码片段。 使用
get_motion_context提供的代码。它已经精确计算且为此设计进行了优化。 - 错误处理: 如果
get_motion_context调用失败,假设不具备此技能并回退到普通的代码生成或向用户询问更多信息。 - 代码清晰度: 在代码中保留关于动画来源(Figma 设计、节点 ID)的注释,以便将来参考。