创建动效规范 是做什么的?
直接在 Figma 中生成动效规范——时间线条和详细表格,记录 After Effects 合成中的所有动画属性。
超出组件 Markdown(
.md)消费者合同范围。 其他create-*技能需要组件.md(由 {{skill:create-component-md}} 生成)并从中渲染render-meta。create-motion是有意例外:其输入是 After Effects 时间线导出({{ref:motion/export-timeline.jsx}}),而不是 Figma 组件遍历——没有_base.json,没有extract-motion,也没有.md中的动效部分。此技能不需要.md,也不参与需要.md/快速失败/白名单读取的重构。
执行合同(请先阅读)。
- 此文件是运行指令,而非可编辑文档。调用技能 = 从 AE 时间线 JSON 将动效规范渲染到 Figma 中。
- 即使有任何技能文件在编辑器中打开或聚焦,也绝不编辑此
SKILL.md或任何其他技能文件作为响应。仅当用户明确要求更改技能本身时才修改技能。 - 输入时间线 JSON 是只读的真相源。绝不要编辑它。 此技能产生的唯一工件是 Figma 标注;将渲染请求发送到 Figma,从不作为文件编辑。
- 绝不调用
AskQuestion、请求确认或暂停以等待输入(包括在 Figma 写入之前,即预期输出)。存在歧义时,选择最合理的选项并继续。 - 只有两种合法停止情况:(a) 缺少或无效的 AE 时间线 JSON(第 4/5 步收集 + 验证关卡);(b) 如果 Figma MCP 连接断开,则单行中止。
MCP 适配器
读取 uspecs.config.json → mcpProvider。对于此技能中的每个 MCP 调用,遵循匹配列。
| 操作 | figma-console | figma-mcp |
|---|---|---|
| 验证连接 | figma_get_status | 跳过——隐式。如果第一次 use_figma 调用失败,引导用户检查 MCP 设置。 |
| 导航到文件 | figma_navigate 使用 URL | 从 URL 提取 fileKey(figma.com/design/:fileKey/...)。无需导航。 |
| 截图 | figma_take_screenshot | get_screenshot 使用 fileKey + nodeId |
| 执行插件 JS | figma_execute 使用 code | use_figma 使用 fileKey、code、description。JS 代码相同——无需更改包装器。 |
| 搜索组件 | figma_search_components | search_design_system 使用 query + fileKey + includeComponents: true |
| 获取文件/组件数据 | figma_get_file_data / figma_get_component | get_metadata 或 get_design_context 使用 fileKey + nodeId |
| 获取变量(文件范围) | figma_get_variables | use_figma 脚本:return await figma.variables.getLocalVariableCollectionsAsync(); |
| 获取令牌值 | figma_get_token_values | use_figma 脚本读取每个模式/集合的变量值 |
| 获取样式 | figma_get_styles | search_design_system 使用 includeStyles: true,或 use_figma:return figma.getLocalPaintStyles(); |
| 获取选区 | figma_get_selection | use_figma 脚本:return figma.currentPage.selection.map(n => ({id: n.id, name: n.name, type: n.type})); |
figma-mcp 每次调用都需要 fileKey。 在工作流开始时从用户的 Figma URL 中提取一次。对于分支 URL(figma.com/design/:fileKey/branch/:branchKey/:fileName),使用 :branchKey 作为 fileKey。
figma-mcp 页面上下文: use_figma 每次调用都会将 figma.currentPage 重置为第一页。当脚本通过 getNodeByIdAsync(ID) 访问上一步的节点时,页面内容可能未加载——findAll、findOne 和 characters 会抛出 TypeError,直到页面被激活。在 getNodeByIdAsync 之后立即插入此页面加载块:
let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);
这会向上遍历到 PAGE 祖先并加载其内容。Console MCP 不需要这个——figma_execute 继承桌面页面上下文。
预期输入
用户通过以下模式之一触发此技能:
- {{skill:create-motion}} + 粘贴的 JSON(从剪贴板,通过 {{ref:motion/export-timeline.jsx}} 导出)
- {{skill:create-motion}} + 文件引用(例如
@motion-ex.json或.json文件的路径) - {{skill:create-motion}} + Figma 链接(目标页面/文件,标注应放置的位置)
必需: 导出的 JSON 数据——可以内联粘贴或作为文件引用。
可选:
- Figma 链接到目标页面(如果未提供,则放置在当前页面的视口中心)
- 动画截图或录制
- 动画用途描述
工作流
复制此检查表并根据进度更新:
任务进度:
- [ ] 步骤 1:读取指令文件
- [ ] 步骤 2:验证 MCP 连接
- [ ] 步骤 3:从 uspecs.config.json 读取模板键
- [ ] 步骤 4:收集上下文(从粘贴、文件引用或提示用户获取 JSON)
- [ ] 步骤 5:解析并验证 JSON(包括 segments[] 和 hasAnimatedSegments)
- [ ] 步骤 6:转换数据(读取预计算的分段,计算轨道宽度,时间线位置)
- [ ] 步骤 7:重新读取指令文件(错误和反模式、验证检查表)并审计
- [ ] 步骤 8:导入并分离动效模板
- [ ] 步骤 9:填充头部字段
- [ ] 步骤 10:生成时间标尺
- [ ] 步骤 11:渲染时间图层(每层一个 figma_execute)
- [ ] 步骤 12:隐藏模板
- [ ] 步骤 13:渲染表格行
- [ ] 步骤 14:视觉验证
步骤 1:读取指令
读取 agent-motion-instruction.md
步骤 2:验证 MCP 连接
从 uspecs.config.json 读取 mcpProvider 以确定使用哪个 Figma MCP。
如果 figma-console:
figma_get_status— 确认 Desktop Bridge 插件处于活动状态- 如果连接失败:“请打开 Figma 桌面版并运行 Desktop Bridge 插件。然后重试。”
如果 figma-mcp:
- 连接在第一次
use_figma调用时隐式验证。无需显式检查。 - 如果第一次调用失败:“请验证您的 FIGMA_API_KEY 已在 MCP 配置中正确设置。”
步骤 3:读取模板键
读取文件 uspecs.config.json 并提取:
templateKeys对象中的motionSpec值 → 保存为MOTION_TEMPLATE_KEY
如果模板键为空,告知用户:
动效规范模板键未配置。请先使用您的 Figma 模板库链接运行 {{skill:firstrun}}。
步骤 4:收集上下文
检查用户提供了什么:
- 已提供 JSON(内联粘贴或作为文件引用,如
@motion-ex.json)→ 读取并直接继续步骤 5。不要再次询问。 - 仅提供 Figma 链接(目标)但无 JSON → 提示:
请粘贴导出的 JSON 或引用
.json文件(例如@motion-ex.json)。 - 未提供任何内容 → 提示:
请粘贴从
export-timeline.jsx导出的 JSON,或引用.json文件。
如果提供了 Figma 目标链接,在渲染之前(步骤 8)使用 figma_navigate 打开它。
同时接受用户提供的任何可选截图、录制或描述以获取更多上下文。
步骤 5:解析并验证 JSON
根据指令文件中的模式和验证规则(JSON 模式和 JSON 验证规则部分)验证剪贴板 JSON。如果验证失败,准确告知用户哪个字段缺失或格式错误,并要求他们重新导出。
步骤 6:转换数据
导出脚本预计算分段、值格式化、条形标签、缓动标签和无变化过滤。代理直接读取这些值,仅计算布局相关的值。
6a. 跳过非动画图层 — 检查 layer.hasAnimatedSegments。如果为 false,从时间线和表格中省略该图层。
6b. 读取预计算的分段 — 每个属性都有一个 segments[] 数组,包含 startMs、endMs、durationMs、fromValue、toValue、barLabel、easing 和 easingType。直接使用这些值——无需手动计算。
6c. 计算轨道宽度和 pxPerMs — pxPerMs 固定速率;trackWidth 动态变化,右侧为刻度标签留出内边距:
compDurationMs = composition.durationMs // 直接从 JSON 读取
pxPerMs = 0.64 // 固定速率——约 320px 每 500ms 刻度
trackWidth = max(compDurationMs * pxPerMs + 50, 1600) // 数据区域 + 50px 标签内边距,最小 1600
将 trackWidth 和 pxPerMs 传递给 Figma 渲染代码。pxPerMs 是固定速率(0.64),不是从 trackWidth / compDurationMs 派生。条形位置(barX、barWidth)在渲染时在 Figma 代码内部计算——代理不计算每个分段的位置。
在渲染时,将 #track-area 和 #ruler-track 调整为此计算出的 trackWidth。父容器使用 HUG 尺寸并自动扩展。
6d. 按照指令文件的合成元数据规则格式化合成元数据。保存为 COMPOSITION_META。
步骤 7:审计
重新读取指令文件,重点关注:
- 错误和反模式部分
- 输出前验证检查表
根据每条规则检查您的转换数据。修复任何违规。
步骤 8:导入并分离模板
通过 figma_execute 运行(替换 __MOTION_TEMPLATE_KEY__ 和 __COMPONENT_NAME__):
const TEMPLATE_KEY = '__MOTION_TEMPLATE_KEY__';
const templateComponent = await figma.importComponentByKeyAsync(TEMPLATE_KEY);
const instance = templateComponent.createInstance();
const { x, y } = figma.viewport.center;
instance.x = x - instance.width / 2;
instance.y = y - instance.height / 2;
const frame = instance.detachInstance();
frame.name = '__COMPONENT_NAME__ 动效';
figma.currentPage.selection = [frame];
figma.viewport.scrollAndZoomIntoView([frame]);
return { frameId: frame.id };
保存返回的 frameId——您在所有后续步骤中都需要它。
步骤 9:填充头部字段
通过 figma_execute 运行(替换 __FRAME_ID__、__COMPONENT_NAME__、__COMPOSITION_META__):
const FRAME_ID = '__FRAME_ID__';
const frame = await figma.getNodeByIdAsync(FRAME_ID);
const textNodes = frame.findAll(n => n.type === 'TEXT');
const fontSet = new Set();
const fontsToLoad = [];
for (const tn of textNodes) {
try {
const fn = tn.fontName;
if (fn && fn !== figma.mixed && fn.family) {
const key = fn.family + '|' + fn.style;
if (!fontSet.has(key)) { fontSet.add(key); fontsToLoad.push(fn); }
}
} catch {}
}
await Promise.all(fontsToLoad.map(f => figma.loadFontAsync(f).catch(() => {})));
const compName = frame.findOne(n => n.name === '#component-name');
if (compName) {
const t = compName.type === 'TEXT' ? compName : compName.findOne(n => n.type === 'TEXT');
if (t) t.characters = '__COMPONENT_NAME__';
}
const compDesc = frame.findOne(n => n.name === '#component-description');
if (compDesc) {
const t = compDesc.type === 'TEXT' ? compDesc : compDesc.findOne(n => n.type === 'TEXT');
if (t) t.characters = '动效规范';
}
const compMeta = frame.findOne(n => n.name === '#composition-meta');
if (compMeta) {
const t = compMeta.type === 'TEXT' ? compMeta : compMeta.findOne(n => n.type === 'TEXT');
if (t) t.characters = '__COMPOSITION_META__';
}
return { success: true };
步骤 10:生成时间标尺
通过 figma_execute 运行。计算理想的轨道宽度,调整 #ruler-track 和所有 #track-area 节点的大小,然后为每个间隔克隆 #tick。
替换 __FRAME_ID__、__COMP_DURATION_MS__(从 composition.durationMs 读取)、__TRACK_WIDTH__(在步骤 6c 中计算)和 __PX_PER_MS__(固定为 0.64):
const FRAME_ID = '__FRAME_ID__';
const COMP_DURATION_MS = __COMP_DURATION_MS__;
const TRACK_WIDTH = __TRACK_WIDTH__;
const PX_PER_MS = __PX_PER_MS__;
const frame = await figma.getNodeByIdAsync(FRAME_ID);
const rulerTrack = frame.findOne(n => n.name === '#ruler-track');
if (!rulerTrack) return { error: '未找到 #ruler-track' };
// 将标尺轨道调整为计算宽度
rulerTrack.resize(TRACK_WIDTH, rulerTrack.height);
// 调整所有 #track-area 节点的大小(在图层模板和任何克隆图层中)
const trackAreas = frame.findAll(n => n.name === '#track-area');
for (const ta of trackAreas) {
ta.resize(TRACK_WIDTH, ta.height);
}
// 在标尺轨道内找到 #tick 模板
const tickTemplate = rulerTrack.findOne(n => n.name === '#tick');
if (!tickTemplate) return { error: '在 #ruler-track 中未找到 #tick 模板' };
// 从 tick 模板的文本节点加载字体
const tickTextNodes = tickTemplate.findAll(n => n.type === 'TEXT');
for (const tn of tickTextNodes) {
if (tn.characters.length > 0) {
try { await figma.loadFontAsync(tn.fontName); } catch {}
}
}
// 刻度间隔:目标是 6–12 个刻度
const tickInterval = COMP_DURATION_MS <= 300 ? 50
: COMP_DURATION_MS <= 600 ? 100
: COMP_DURATION_MS <= 1500 ? 250
: COMP_DURATION_MS <= 4000 ? 500
: COMP_DURATION_MS <= 10000 ? 1000
: 2000;
for (let ms = 0; ms <= COMP_DURATION_MS; ms += tickInterval) {
const xPos = ms * PX_PER_MS;
const tick = tickTemplate.clone();
rulerTrack.appendChild(tick);
tick.name = ms + 'ms';
tick.visible = true;
tick.x = xPos;
const label = tick.findOne(n => n.type === 'TEXT');
if (label) {
try { await figma.loadFontAsync(label.fontName); } catch {}
label.characters = ms + 'ms';
}
}
tickTemplate.visible = false;
return { success: true, trackWidth: TRACK_WIDTH, tickInterval: tickInterval };
步骤 11:渲染时间图层
每个图层运行一次 figma_execute 调用以避免超时。对于每个图层(其中 hasAnimatedSegments 为 true),克隆 #layer-template,设置图层名称,然后为每个动画属性克隆 #property-template 并定位条形。
替换所有 __PLACEHOLDER__ 值。
…
[因翻译而截断]