Communitygithub.com

Devin-AXIS/iPolloWork

将 Figma 中的动态和动画效果转换为可用于生产的应用程序代码。当用户提到“实现此动画”、“从 Figma 添加动画”、“为该组件添加动画”,提供包含动画节点的 Figma URL,或当 `get_design_context` 返回运动数据或指示你调用 `get_motion_context` 时使用此技能。

iPolloWork 是什么?

该技能专注于将 Figma 设计中的动画和过渡效果精确转换为可运行的代码,支持 motion.dev、CSS keyframes 或特定框架的动画库。其核心工作流是协同使用两个工具:`get_motion_context` 提供权威的动画数据(关键帧、缓动函数、时序、代码片段),`get_design_context` 提供静态结构、样式和资产。技能通过节点 ID 将两者关联,指导开发者将运动数据合并到正确的 DOM 元素上,处理组件实例化、嵌套变换和路径级 SVG 动画等复杂情况。该技能适用于任何需要将 Figma 动画落地为代码的场景,并且提供了详细的规则和反例来避免常见错误,最终输出可直接集成的动画代码。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Devin-AXIS/iPolloWork/tree/HEAD/examples/plugin-packages/figma/skills/figma-implement-motion

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

实现运动

概述

本技能指导如何将 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(Tailwind contents)的形式出现,通常伴随着一个无效的 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 内联写入的 CSS transform 属性,因此 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 的 useAnimate hook,或 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)的注释,以便将来参考。

Individual skills in this repo

This repo contains 17 individual skills — each has its own dedicated page.

Devin-AXIS/iPolloWork

Create deterministic animation and transitions for the active iPollo Video project.

Devin-AXIS/iPolloWork

Inspect, validate, preview, and render the active iPollo Video project with its bundled HyperFrames CLI.

Devin-AXIS/iPolloWork

Apply the core composition, timing, media, and determinism contract used by iPollo Video.

Devin-AXIS/iPolloWork

Plan visual direction, typography, pacing, audio, and composition for iPollo Video projects.

Devin-AXIS/iPolloWork

Build seek-safe keyframe animation for the active iPollo Video timeline.

Devin-AXIS/iPolloWork

Reuse approved HyperFrames blocks and components inside the active iPollo Video project.

Devin-AXIS/iPolloWork

Route video creation and editing through the active iPollo Video project and its built-in HyperFrames runtime.

Devin-AXIS/iPolloWork

Create or edit the active iPolloWork video's visual assets, installed recipes, editable composition and seek-safe motion; use for assembly or local picture/text/theme changes.

Devin-AXIS/iPolloWork

Add or revise music, sound effects and their mix in the active iPolloWork video, using authorized sources, real editable tracks and measured event cues.

Devin-AXIS/iPolloWork

Write or revise the active iPolloWork video's native STORYBOARD.md, with source coverage, content-led sequence and provisional timing; use for script-only work.

Devin-AXIS/iPolloWork

Route the active iPolloWork video request to its current storyboard, compose, voiceover or soundtrack work, preserving the client-owned delivery flow.

Devin-AXIS/iPolloWork

Add or revise scene-bound narration or speech-linked captions in the active iPolloWork video using actual voice settings, measured audio and alignment.

Devin-AXIS/iPolloWork

Create product launch and promotional videos through the active iPollo Video workflow.

Devin-AXIS/iPolloWork

Develop or update reusable visual components for iPolloWork Video, including maps, charts, rankings, diagrams, openings and endings. Use for component authoring rules, manifests, editable variables, shared data forms, inherited design themes, AI editing slots and seekable HyperFrames timelines. Not for producing a whole video, authoring a full-project template, or packaging a DeepSeek host plugin.

Devin-AXIS/iPolloWork

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

Devin-AXIS/iPolloWork

Plan and create short videos using the installed short-video-studio workspace app. Manage its creative canvas, scripts, storyboards, characters and local assets, generate images or video through connected Work channels, and hand off editable tracks to Work Video Studio.

Devin-AXIS/iPolloWork

Find, generate, process, and reuse media through the active iPollo Video session's media services.

相关技能