实现动效
概览
本技能指导如何将 Figma 的动画和过渡效果翻译为可运行的代码(支持 motion.dev、CSS 关键帧或特定框架库)。
Figma 通过两个工具暴露动效:
get_motion_context— 权威动效工具。返回完整的动画节点清单、预生成的代码片段(CSS@keyframes+ motion.dev)、片段不可用时的后备关键帧绑定,以及递归时间轴协调提示。是动画数据以及哪些节点 ID 会动效的来源。get_design_context— 设计的结构:布局、尺寸、资源、样式、Code Connect 提示、截图上下文,以及有时在动画元素上的动效放置标记(data-node-id,以及针对拆分节点的data-motion-keys/data-motion-wrapper-for/data-motion-transform-template)。它可能将动画节点渲染为普通元素(div、p、span等)或动效元素(motion.div);但它不会内联动画值。
两者通过节点 ID 关联,这就是整个工作流程。 get_motion_context 告诉您哪些节点有动画,并给出关键帧值、缓动函数、时间和代码片段。get_design_context 告诉您这些节点的外观及其位置。对于 get_motion_context.nodes 中的每个节点,在 design context 中找到匹配的 data-node-id,并将动效合并到该结构中 — 当结构性元素是普通元素时,添加或包裹 motion.{tag}。当 design context 复用了 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— 绑定的关键帧轨迹,包括解析为轨迹数据的预设动效,仅作为两种代码片段格式都缺失时的后备数据。fallbackNodeId— 可选的后备 ID,用于匹配组件化的设计上下文。如果nodeId是实例限定的 ID,例如I4005:6111;30:8005,D2R 可能使用后备组件 ID(如4002:3957)渲染可复用组件主体。在这种情况下,fallbackNodeId是当精确nodeId查找失败时要查找的data-node-id。
递归响应还可能包含 timelineCohorts:共享时间轴根节点、持续时间和播放模式(once、loop 或 boomerang)的动画节点 ID 组。使用 cohort 来使错开或多节点动画同步,而不是从兄弟顺序推断共享时间。
对 LLM 重要的实现细节:
- 当代码片段存在时,原始的
keyframeBindings、timelineDurationMs、motionSummary和默认transformOrigin可能被剥离以保持有效负载较小。缺少keyframeBindings并不意味着没有动画。 - 递归响应会去重完全相同的代码片段。一个片段可能被替换为指向第一个具有相同动效的节点的注释;应复用相同的组件、变体、类或常量,而不是编写第二个动画。
- 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。该组件的每个实例共享此 ID。如果精确的nodeId存在于 design context 中,则在该节点上应用动效并忽略后备。这对于根实例动画至关重要:一个实例的旋转或移动可能不同于同一组件的另一个实例,如果将动效应用于共享的组件主体,将错误地动画所有实例。 - 将每个动效节点应用于匹配的、以
data-node-id为键的设计上下文结构。 匹配的data-node-id是结构锚点,不总是最终接收动效的 DOM 元素。使用代码片段形状和放置标记来决定动效是放在该确切元素、包装器、内部元素还是内联 SVG 路径上。get_design_context可能已经发出带有值被剥离的motion.{tag},或者可能发出一个普通的结构元素(div、p、span、组件根等)。如果它是普通的,并且代码片段目标是元素本身,则将其转换为适当的motion.{tag}或添加动效包装器,同时保留节点的文本、子节点、类/样式、属性和data-node-id。加载 references/examples-and-anti-examples.md 查看此合并步骤的示例。 - 组件化的子节点动画通常通过后备 ID 匹配。 当 design context 将 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> motion unsupported注释并在总结中说明。- 如果节点出现在动效上下文中但不在静态 JSX 中,添加表示它所需的元素 — design-context 代码是参考,不是完整的动画清单。
- 当 design 和 motion 上下文之间存在冲突(时间/缓动/动画值)时,优先使用
get_motion_context。 - 路径级 SVG 动效:内联 SVG 并动画真实的
<path>。 当get_motion_context目标是矢量的路径(PATH_TRIM、motion.path、stroke-dasharray),但 design context 将其渲染为<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)。保持 wrapper > static-transform div > inner 的嵌套 — 将其折叠会破坏尺寸和基础变换。
- 通过
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 应用的任何静态基础。一个[45, 125, 125]的rotate代码片段覆盖在rotate-45基础上意味着包装器动画的是偏移[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导入 — 除非代码库已经使用了另一个动效库(Framer Motion、React Spring、GSAP),在这种情况下,将代码片段适配到该库。加载 references/framework-recommendations.md 以获取适配到其他技术栈或选择库的指导。 - 存在 CSS 关键帧? 用于纯 JS / 非 React 目标,或当代码库没有 React 动效库时。
- 没有代码片段? 使用
keyframeBindings或motionSummary作为后备数据来构建等效的 motion.dev 调用或 CSS 关键帧。通常代码片段是存在的;仅在两种片段格式都确实缺失时才执行此操作。
步骤 5:验证
- 在添加新导入之前,阅读组件现有的动效导入/约定。如果用户已经使用 Framer Motion / React Spring / anime.js,则进行适配而不是强制使用 motion.dev。
- 在批量更改多个节点之前,抽查一个动画是否端到端运行(重新加载、观察、迭代)。
- 加载 references/gotchas.md 并注意此处记录的常见陷阱列表。