figma-use-motion

use_figma — Motion 的 Figma Plugin API 技能

use_figma MCP 工具的 Motion 上下文。figma-use 涵盖基础 Plugin API 规则——请同时加载两者。

调用 use_figma 处理 Motion 任务时，务必传入 skillNames: "figma-use-motion"（与 figma-use 一起以逗号分隔）。 仅用于日志记录。

运行时门控

调用用户可能无法使用 Motion API。不可用时，本技能中引用的每个 Motion 属性和辅助函数都会抛出 "<name>" is not a supported API。

遇到此错误时，请立即停止。 不要重试；告知用户他们无法使用 Motion，然后停止。否则，你会浪费调用次数，并因重复出现相同错误而让用户困惑。

即使其他 Motion API 可用，自定义动画样式也可能不可用。请参阅 motion-custom-styles.md，了解可用性检查和回退指导。

应用 TextStagger 前，请先通过 figma.motion.figmaAnimationStyles() 查找它。如果不存在，请说明本次会话无法使用文本动效；不要绕过查找，也不要悄悄改用整个图层的动效。

何时使用此技能

只要 use_figma 任务涉及以下内容，就加载此技能：

• 在节点上添加、编辑或移除关键帧（manualKeyframeTracks、applyManualKeyframeTrack、removeManualKeyframeTrack）。
• 随时间对填充色或描边颜色进行动画处理。
• 应用、编辑或移除动画样式（applyAnimationStyle、removeAnimationStyle、animationStyles）。
• 查找、创建、编辑、整理、应用或移除本地自定义动画样式——保存在文件中的可复用命名 Motion 样式（figma.getLocalCustomAnimationStylesAsync、figma.createCustomAnimationStyle）。
• 对可编辑文本中的字符、单词、行或段落进行动画处理，包括打字机式显示，以及编辑文本动画内部的样式。编写前请加载 text-animation.md。
• 通过 node.timelines 读取或写入时间轴时长，或调用 node.setTimelineDuration(id, seconds)。
• 为上述任一内容选择缓动方式。

静态设计工作（创建形状、组件、变量、布局）仅使用 figma-use——本技能仅用于时间维度。

公开的 Motion API 范围

• node.manualKeyframeTracks — 读取/写入手动关键帧（包括填充、描边和效果轨道）。
• node.applyManualKeyframeTrack(field, track) / node.removeManualKeyframeTrack(field) — 添加、替换或移除一条手动关键帧轨道，无需重写整个对象。
• node.animationStyles — 读取/写入应用于节点的动画样式元数据。
• node.applyAnimationStyle(styleId, presetData?) / node.removeAnimationStyle(id) — 应用已查找到的样式，并通过其返回或回读的 id 移除已应用的样式实例。
• node.timelines — 只读的时间轴列表，包含所在顶层框架的时长，单位为秒。
• node.setTimelineDuration(id, durationSeconds) — 写入所在顶层框架的时间轴时长。
• node.animations — 只读的已解析关键帧数据（目前仅包含手动轨道——请参阅 motion-patterns.md）。
• figma.motion.figmaAnimationStyles() — Figma 第一方动画样式定义的只读列表。
• 可用于处理自定义动画样式的各种 API，请参阅 motion-custom-styles.md。

编写自定义 "figma:motion" 预设模块源代码不在本技能范围内。支持配置已查找到的 TextStagger 中的 Position、Rotation、Scale、Opacity 和 Blur 样式；这些是一个原生预设的属性，并非新的预设源代码。如果请求需要编写新的预设模块，请说明这一限制；不要编造预设。

参考文档

根据任务内容按需加载：

文档	加载时机	涵盖内容
motion-patterns.md	添加或编辑动画	手动关键帧、动画填充/描边、应用动画样式、时间轴时长
motion-custom-styles.md	任何可复用命名动画样式相关工作	发现、创建、编辑、整理、应用、移除和验证本地自定义动画样式
text-animation.md	创建或编辑文字显现效果、打字机效果或交错文字	原生 TextStagger、分组/顺序、组合文字样式、时间设置、编辑/移除、保留可编辑文字
motion-easing.md	设置动画缓动	关键帧缓动对象、自定义三次曲线/弹簧、HOLD、在动画样式中应用缓动

验证动画

get_screenshot 只会显示时间轴的静止状态，不会显示动画。要检查动画，请使用 export_video 并对视频采样帧——但它会在服务端渲染，而且速度慢、开销大（约需 10 秒到数分钟），因此每次渲染都应物尽其用。

渲染前先规划——成本随像素数 × 帧数增长，因此两者都不要超出所需：

1. 先选定时间点。 每个阶段需要一帧（例如，每个交错步骤，或开始/中间/结束），无需流畅播放——通常为 4–6 帧。这个数量决定 fps。
2. 根据需要读取的内容设定尺寸。 从较小尺寸开始——constraint: { type: 'WIDTH', value: 320 }、quality: "low"——但这里的文字和小元素会模糊，因此需要判断精细细节时，请提高 WIDTH（768+）。省略 constraint = 原始尺寸（1x；服务端会限制为 10x / 4096px）。
3. 将 fps 设为能捕捉这些帧的最低值： fps: 5 可覆盖少量帧；10 是上限。更高只会让渲染文件变大。

操作方式： export_video 仅适用于子元素承载动画的顶层画框（传入该画框，而不是设置了关键帧的后代元素）。它会返回一个 jobId，状态为 status: "processing"——使用 { fileKey, jobId } 再次调用以轮询状态。然后使用 ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png 在本地提取帧——提取无需额外成本，因此渲染完成后，应尽可能提取所有能提供信息的帧，而不是重新导出。若没有 ffmpeg 这类帧提取工具，请跳过导出，改为分析关键帧。

反复调整，直到效果正确。 导出是诊断手段，而非验收依据：如果帧有问题（顺序错误、时间不对、元素缺失、蒙版清空了合成结果），请修正关键帧/样式并重新导出。仔细检查所有帧，并在再次渲染前一次性完成所有修正——每次渲染都有实际开销，因此应物尽其用，而不是每做一点小改动就重新导出。

对于简单或一目了然的更改，可完全跳过导出。

预检清单

除了 figma-use 预检清单 外，请确认：

• 缓动使用公开的 { type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … } 形状，而不是 OUT_CUBIC 等内部 scenegraph 名称。
• 缓入缓出使用准确的公开枚举 EASE_IN_AND_OUT（或 EASE_IN_AND_OUT_BACK）；切勿输出无效别名 EASE_IN_OUT。
• 要制作动画的节点不是顶层框架（页面的直接子节点）。应为其后代节点制作动画。
• 公共 Plugin API 中的时间线数值单位为秒。使用 setTimelineDuration 延长时间线；除非用户提出要求，否则不要缩短。
• 文本内部的动态效果使用在现有文本节点上发现的 TextStagger。保留字符、格式、换行和无关动画；其 duration 是整个错开动画的时长，而非每个字符的时长。
• 变换关键帧字段使用公开名称（TRANSLATION_X、TRANSLATION_Y、ROTATION、SCALE_X、SCALE_Y、SCALE_XY），而不是内部 MOTION_* scenegraph 名称。
• 手动关键帧字段必须来自 motion-patterns.md 中的公开允许列表；生成的／内部 scenegraph 字段会按预期抛出异常。
• 返回已修改的节点 ID（遵循 figma-use 规则 15）。
• 如果动画是否正确并非一目了然，且可使用帧提取器（ffmpeg），请通过 export_video 和帧采样进行验证——以较小尺寸和较低 fps 渲染，并反复调整直至效果正确（参见上文“验证动画”一节）。get_screenshot 只显示静止状态。