figma-use-motion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

use_figma — Figma Plugin API Skill for Motion

use_figma — 面向动效的Figma Plugin API技能

Motion context for the

use_figma

MCP tool. figma-use covers the foundational Plugin API rules — load both together.

Always pass
skillNames: "figma-use-motion"
(comma-separated alongside
figma-use
) when calling
use_figma
for motion work. Logging only.

use_figma

MCP工具的动效上下文。figma-use涵盖了基础的Plugin API规则——需同时加载两者。

在调用
use_figma
处理动效工作时，务必传入
skillNames: "figma-use-motion"
（与
figma-use
以逗号分隔）。仅用于日志记录。

Runtime Gating

运行时权限控制

Motion APIs are gated behind the

metronome

user feature flag. When the calling user doesn't have it, every motion property and helper referenced in this skill throws

"<name>" is not a supported API

Bail out fast on that error. Do not retry; tell the user motion isn't enabled for them and stop. Otherwise you'll burn calls and confuse the user with repeated identical failures.

动效API受

metronome

用户功能标志限制。当调用用户未开启该标志时，本技能中引用的所有动效属性和辅助函数都会抛出

"<name>" is not a supported API

错误。

遇到该错误时立即终止操作。请勿重试；告知用户其动效功能未启用并停止执行。否则会浪费调用次数，且多次重复的相同失败会让用户困惑。

When to use this skill

何时使用本技能

Load this skill whenever a

use_figma

task involves:

Adding, editing, or removing keyframes on a node (

manualKeyframeTracks

applyManualKeyframeTrack

removeManualKeyframeTrack

Animating fill or stroke colors over time.

Applying, editing, or removing animation styles (

applyAnimationStyle

removeAnimationStyle

animationStyles

Reading or writing timeline duration via

node.timelines

node.setTimelineDuration(id, seconds)

Choosing easing for any of the above.

Static design work (creating shapes, components, variables, layout) goes through figma-use alone — this skill is only for the time dimension.

当

use_figma

任务涉及以下内容时，加载本技能：

在节点上添加、编辑或删除关键帧（

manualKeyframeTracks

、

applyManualKeyframeTrack

、

removeManualKeyframeTrack

）。

随时间动态变化填充色或描边色。

应用、编辑或删除动画样式（

applyAnimationStyle

、

removeAnimationStyle

、

animationStyles

）。

通过

node.timelines

node.setTimelineDuration(id, seconds)

读取或写入时间线时长。

为上述任意操作选择缓动效果。

静态设计工作（创建形状、组件、变量、布局）仅需通过figma-use完成——本技能仅用于处理时间维度相关的动效。

Exposed motion API surface

暴露的动效API接口

```
node.manualKeyframeTracks
```
— read/write manual keyframes (including fill, stroke, and effect tracks).
```
node.applyManualKeyframeTrack(field, track)
```
/
```
node.removeManualKeyframeTrack(field)
```
— add, replace, or remove one manual keyframe track without rewriting the whole object.
```
node.animationStyles
```
— read/write animation-style metadata applied to a node.
```
node.applyAnimationStyle(styleId, presetData?)
```
/
```
node.removeAnimationStyle(id)
```
— apply a discovered style and remove an applied style instance by its returned/read-back
```
id
```
.
```
node.timelines
```
— read-only timeline list for the containing top-level frame, with durations in seconds.
```
node.setTimelineDuration(id, durationSeconds)
```
— write the containing top-level frame timeline duration.
```
node.animations
```
— read-only resolved keyframe data (currently manual tracks only — see motion-patterns.md).
```
figma.motion.figmaAnimationStyles()
```
— read-only list of Figma's first-party animation styles.

Authoring custom

"figma:motion"

preset module source code is out of scope. If the user wants a brand-new animation style, say so and stop; don't fabricate one.

```
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官方内置动画样式的只读列表。

编写自定义

"figma:motion"

预设模块源代码不在本技能范围内。如果用户需要全新的动画样式，请直接告知并停止操作；切勿自行编造。

Reference docs

参考文档

Load these as needed based on what the task involves:

Doc	When to load	What it covers
motion-patterns.md	Adding/editing motion animation	Manual keyframes, animated fills/strokes, applying animation styles, timeline duration
motion-easing.md	Setting animation easing	Keyframe easing objects, custom cubic/spring, `HOLD` , applying easing inside an animation style

根据任务需求按需加载以下文档：

文档	加载时机	涵盖内容
motion-patterns.md	添加/编辑动效动画时	手动关键帧、动态填充/描边、应用动画样式、时间线时长
motion-easing.md	设置动画缓动时	关键帧缓动对象、自定义贝塞尔曲线/弹簧效果、 `HOLD` 、在动画样式内应用缓动

Verifying the animation

验证动效

get_screenshot

shows only the timeline's resting state, never motion. To check motion,

export_video

and sample frames — but it renders server-side and is slow and expensive (~10s to minutes), so make each render count.

Plan before rendering — cost scales with pixels × frames, so keep both no larger than the frames need:

Pick the moments first. You need one frame per phase (e.g. per stagger step, or start / mid / settle), not smooth playback — usually 4–6. This count sets your fps.
Size to what you must read. Start small —
```
constraint: { type: 'WIDTH', value: 320 }
```
,
```
quality: "low"
```
— but text and small elements blur there, so raise
```
WIDTH
```
(768+) when you need to judge fine detail. Omitting
```
constraint
```
= full size (1x; server clamps to 10x / 4096px).
Set fps just high enough to land those frames:
```
fps: 5
```
covers a handful; 10 is an upper bound. Higher just bloats the render.

Mechanics:

export_video

works only on a top-level frame whose children carry the animation (pass that frame, not the descendant you keyframed). It returns a

jobId

with

status: "processing"

— re-invoke with

{ fileKey, jobId }

to poll. Then extract frames locally with

ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png

— extraction is free, so once you've paid for the render, mine it for every frame that tells you something rather than re-exporting. Without a frame extractor like

ffmpeg

, skip the export and reason about the keyframes instead.

Iterate until it's right. The export is a diagnostic, not a sign-off: if the frames are wrong (bad order, off timing, a missing element, a mask blanking the composite), fix the keyframes/styles and re-export. Read all the frames and batch every fix into one pass before re-rendering — every render carries real overhead, so make each one count instead of re-exporting after each small change.

Skip the export entirely for trivial or self-evident changes.

get_screenshot

仅显示时间线的静止状态，不会展示动效。要检查动效，需使用

export_video

并采样帧——但该操作在服务器端渲染，速度慢且成本高（约10秒至数分钟），因此务必确保每次渲染都有价值。

渲染前做好规划——成本与像素×帧数成正比，因此两者都不要超过实际需求：

先确定采样时刻。 每个阶段（如每个交错步骤，或开始/中间/结束状态）只需一帧，无需平滑播放——通常4–6帧即可。该数量决定了帧率。
尺寸按需设置。 从小尺寸开始——
```
constraint: { type: 'WIDTH', value: 320 }
```
，
```
quality: "low"
```
——但文本和小元素会模糊，因此当需要判断细节时，提高宽度值（768+）。省略
```
constraint
```
表示使用原始尺寸（1倍；服务器限制为10倍/4096px）。
设置刚好满足采样需求的帧率：
```
fps: 5
```
足以覆盖少量采样；10是上限。更高帧率只会增加渲染体积。

操作机制：

export_video

仅对包含动效子元素的顶级帧生效（传入该帧，而非添加了关键帧的子元素）。它会返回一个

jobId

，状态为

"processing"

——需传入

{ fileKey, jobId }

重新调用以轮询状态。然后使用

ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png

在本地提取帧——提取操作无成本，因此一旦完成渲染付费，就尽可能提取所有有价值的帧，而非重新导出。如果没有ffmpeg这类帧提取工具，可跳过导出，直接通过关键帧逻辑判断动效是否正确。

迭代至动效正确。 导出只是诊断手段，并非最终确认：如果帧存在问题（顺序错误、时机不对、元素缺失、遮罩导致合成内容空白），修复关键帧/样式后重新导出。读取所有帧，将所有修复批量处理后再重新渲染——每次渲染都有实际开销，因此确保每次渲染都有价值，而非每次小修改后都重新导出。

对于微小或逻辑自明的修改，可完全跳过导出步骤。

Pre-flight checklist

预检查清单

In addition to the figma-use pre-flight checklist, verify:

Easing uses the public

{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }

shape — not internal scenegraph names like

OUT_CUBIC

Ease-in-out uses the exact public enum
```
EASE_IN_AND_OUT
```
(or
```
EASE_IN_AND_OUT_BACK
```
); never emit the invalid alias
```
EASE_IN_OUT
```
.
The node being animated is not a top-level frame (direct child of a page). Animate descendants instead.
Timeline values are seconds in the public Plugin API. Extend via
```
setTimelineDuration
```
; never shorten unless the user asked.
Transform keyframe fields use public names (
```
TRANSLATION_X
```
,
```
TRANSLATION_Y
```
,
```
ROTATION
```
,
```
SCALE_X
```
,
```
SCALE_Y
```
,
```
SCALE_XY
```
), not internal
```
MOTION_*
```
scenegraph names.
Manual keyframe fields come from the public allowlist in motion-patterns.md; generated/internal scenegraph fields intentionally throw.
Mutated node IDs are returned (per
```
figma-use
```
Rule 15).
When motion correctness isn't self-evident and a frame extractor (
```
ffmpeg
```
) is available, verify via
```
export_video
```
+ frame sampling — render small, low
```
fps
```
, iterate until right (see the Verifying the animation section above).
```
get_screenshot
```
shows only the resting state.

除了figma-use预检查清单，还需验证：

缓动使用公开的格式

{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }

——而非内部场景图名称如

OUT_CUBIC

。

缓动入出使用精确的公开枚举值
```
EASE_IN_AND_OUT
```
（或
```
EASE_IN_AND_OUT_BACK
```
）；切勿使用无效别名
```
EASE_IN_OUT
```
。
被动画的节点不是顶级帧（页面的直接子元素）。应改为为其子元素添加动画。
时间线值使用公开Plugin API中的秒为单位。仅可通过
```
setTimelineDuration
```
延长时长；除非用户要求，否则切勿缩短。
变换关键帧字段使用公开名称（
```
TRANSLATION_X
```
、
```
TRANSLATION_Y
```
、
```
ROTATION
```
、
```
SCALE_X
```
、
```
SCALE_Y
```
、
```
SCALE_XY
```
），而非内部的
```
MOTION_*
```
场景图名称。
手动关键帧字段来自motion-patterns.md中的公开允许列表；生成的/内部场景图字段会主动抛出错误。
返回修改后的节点ID（遵循
```
figma-use
```
规则15）。
当动效正确性无法自证且有帧提取工具（如ffmpeg）可用时，通过
```
export_video
```
+帧采样验证——使用小尺寸、低帧率渲染，迭代至动效正确（详见上述「验证动效」部分）。
```
get_screenshot
```
仅显示静止状态。