figma-use

use_figma — Figma 插件 API 技能

使用 use_figma MCP 通过插件 API 在 Figma 文件中执行 JavaScript。所有详细的参考文档都位于 references/ 中。

调用 use_figma 时，务必传入 skillNames: "figma-use"。 这是用于跟踪技能使用情况的日志参数，不会影响执行。

如果任务涉及通过代码在 Figma 中构建或更新完整页面、屏幕或多分区布局，还需加载 figma-generate-design。它提供了相关工作流，用于通过 search_design_system 查找设计系统组件、导入组件，并逐步组装屏幕。这两项技能可以配合使用：本技能负责 API 规则，另一项负责屏幕构建工作流。

开始前，先加载 plugin-api-standalone.index.md，了解可实现的功能。收到编写插件 API 代码的请求时，根据这些背景信息，在 plugin-api-standalone.d.ts 中搜索相关类型、方法和属性。该文件是 API 范围的权威信息来源。类型定义文件很大，因此不要一次性全部加载；按需搜索相关部分。

重要：每当处理设计系统时，先从 working-with-design-systems/wwds.md 开始，了解在 Figma 中使用设计系统的关键概念、流程和指南。然后按需加载有关组件、变量、文本样式和效果样式的更具体参考资料。

1. 关键规则

1. 使用 return 返回数据。 返回值会自动序列化为 JSON（对象、数组、字符串、数字）。不要调用 figma.closePlugin()，也不要将代码包装在异步 IIFE 中——这些都由系统处理。
2. 使用顶层 await 和 return 编写纯 JavaScript。 代码会自动包装在异步上下文中。不要将代码包装在 (async () => { ... })() 中。
3. figma.notify() 会抛出“not implemented”错误——切勿使用它 3a. getPluginData() / setPluginData() 在 use_figma 中不受支持——不要使用。请改用 getSharedPluginData() / setSharedPluginData()（这些方法受支持），或者通过返回节点 ID 并在后续调用中传入它们来跟踪节点。
4. console.log() 的内容不会返回——请使用 return 输出
5. 分小步逐步操作。 将大型操作拆分为多个 use_figma 调用，并在每一步后进行验证。这是避免错误最重要的做法。
6. 颜色取值范围为 0–1（不是 0–255）：{r: 1, g: 0, b: 0} = 红色
7. 填充和描边是只读数组——请先克隆，再修改并重新赋值
8. 执行任何文本操作前，必须先加载字体：await figma.loadFontAsync({family, style})
9. 页面会逐步加载——使用 await figma.setCurrentPageAsync(page) 切换页面并加载其内容（见下文“页面规则”）
10. setBoundVariableForPaint 会返回一个新的 Paint——必须捕获并重新赋值
11. createVariable 接受集合对象或 ID 字符串（优先使用对象）
12. 必须在 parent.appendChild(child) 之后设置 layoutSizingHorizontal/Vertical = 'FILL'——在追加之前设置会抛出错误。对非自动布局节点设置 'HUG' 时也一样。
13. 将新的顶层节点放在远离 (0,0) 的位置。 直接追加到页面的节点默认位于 (0,0)。扫描 figma.currentPage.children，找到空闲位置（例如，最右侧节点的右边）。这仅适用于页面级节点——嵌套在其他框架或自动布局容器中的节点由其父级定位。参见 常见问题。
14. use_figma 出错时，立即停止。不要马上重试。 失败的脚本是原子性的——如果脚本报错，就完全不会执行，也不会更改文件。仔细阅读错误消息，修正脚本后再重试。参见 错误恢复。
15. 必须 return 所有已创建或修改的节点 ID。 每当脚本在画布上创建新节点或修改现有节点时，都要收集每个受影响节点的 ID，并以结构化对象返回（例如 return { createdNodeIds: [...], mutatedNodeIds: [...] }）。后续调用需要引用、验证或清理这些节点，因此这一步至关重要。
16. 创建变量时，始终显式设置 variable.scopes。 默认的 ALL_SCOPES 会污染每个属性选择器——几乎从来不是你想要的结果。请使用特定作用域，例如背景使用 ["FRAME_FILL", "SHAPE_FILL"]，文本颜色使用 ["TEXT_FILL"]，间距使用 ["GAP"] 等。完整列表请参见 variable-patterns.md。
17. 对每个 Promise 都使用 await。 切勿留下未等待的 Promise——未等待的异步调用（例如，不带 await 的 figma.loadFontAsync(...) 或 figma.setCurrentPageAsync(page)）会以即发即弃的方式执行，导致静默失败或竞态条件。脚本可能会在异步操作完成前返回，从而造成数据缺失或更改只应用了一半。

每条规则的详细错误/正确示例，请参见 常见问题与错误做法。

2. 页面规则（重要）

每次 use_figma 调用之间，页面上下文都会重置——每次调用时，figma.currentPage 都从第一页开始。

切换页面

使用 await figma.setCurrentPageAsync(page) 切换页面并加载其内容。在 use_figma 运行时中，同步设置器 figma.currentPage = page 会抛出错误。

// Switch to a specific page (loads its content)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children is now populated

// Iterate over all pages
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // page.children is now loaded — read or modify them here
}

跨脚本运行

每次调用 use_figma 时，figma.currentPage 都会重置为第一页。如果工作流跨越多次调用且目标是非默认页面，请在每次调用开始时调用 await figma.setCurrentPageAsync(page)。

你可以多次调用 use_figma，逐步构建文件状态，也可以先获取信息，再编写另一个脚本。例如，编写脚本获取现有节点的元数据，return 这些数据，然后在后续脚本中使用这些数据修改节点。

3. return 是你的输出通道

Agent 只能看到你 return 的值。其他所有内容都不可见。

• 返回 ID（至关重要）：每个创建或修改画布节点的脚本都必须返回所有受影响节点的 ID，例如：return { createdNodeIds: [...], mutatedNodeIds: [...] }。这是硬性要求，并非可选项。
• 进度报告：return { createdNodeIds: [...], count: 5, errors: [] }
• 错误信息：抛出的错误会自动被捕获并返回——只需让错误继续传播，或显式 throw。
• console.log() 的输出绝不会返回给 Agent。
• 始终返回可操作的数据（ID、计数、状态），以便后续调用引用已创建的对象。

4. 编辑器模式

use_figma 在设计模式下工作（editorType 为 "figma"，这是默认值）。FigJam（"figjam"）提供了不同的可用节点类型，其中大多数设计节点在该模式下不可用。

设计模式下可用：Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Page、Section、TextPath。

设计模式下不可用：Sticky、Connector、ShapeWithText、CodeBlock、Slide、SlideRow、Webpage。

5. 增量式工作流（如何避免错误）

最常见的错误原因是在单次 use_figma 调用中尝试做太多事情。分小步操作，并在每一步之后进行验证。

操作模式

1. 先检查。 创建任何内容之前，先运行只读的 use_figma，了解文件中已有的内容——页面、组件、变量和命名约定。与现有内容保持一致。
2. 每次调用只做一件事。 在一次调用中创建变量，下一次创建组件，再用另一次调用组合布局。不要试图在一个脚本中构建整个屏幕。
3. 每次调用都返回 ID。 始终将创建的节点 ID、变量 ID、集合 ID 作为对象 return，例如：return { createdNodeIds: [...] }。后续调用需要将它们作为输入。
4. 每一步之后都进行验证。 使用 get_metadata 检查结构（数量、名称、层级、位置）。在重要里程碑之后使用 get_screenshot 检查视觉问题。
5. 解决问题后再继续。 如果验证发现问题，请先修复，再进行下一步。不要在有问题的基础上继续构建。

复杂任务的建议步骤顺序

Step 1: Inspect file — discover existing pages, components, variables, conventions
Step 2: Create tokens/variables (if needed)
       → validate with get_metadata
Step 3: Create individual components
       → validate with get_metadata + get_screenshot
Step 4: Compose layouts from component instances
       → validate with get_screenshot
Step 5: Final verification

每一步要验证的内容

完成操作后……	使用 get_metadata 检查	使用 get_screenshot 检查
创建变量	集合数量、变量数量、模式名称	—
创建组件	子项数量、变体名称、属性定义	变体可见且未折叠，网格清晰可读
绑定变量	节点属性反映绑定关系	颜色／设计令牌正确解析
组合布局	实例节点具有 mainComponent，层级正确	没有裁切或截断的文本、没有重叠元素、间距正确

6. 错误恢复与自我修正

use_figma 是原子操作——脚本失败时不会执行。 如果脚本出错，文件不会发生任何更改，状态与调用前相同。这意味着不会留下部分节点或失败脚本产生的孤立元素，修复后重试是安全的。

当 use_figma 返回错误时

1. 停止。 不要立即修复代码并重试。
2. 仔细阅读错误消息。 准确了解问题所在——API 用法错误、缺少字体、属性值无效等。
3. 如果错误不明确， 调用 get_metadata 或 get_screenshot 了解当前文件状态。
4. 根据错误消息修复脚本。
5. 重试修正后的脚本。

常见的自我纠正模式

错误消息	可能原因	修复方法
"not implemented"	使用了 figma.notify()	移除它——使用 return 返回输出
"node must be an auto-layout frame..."	在添加到自动布局父级之前设置了 FILL/HUG	将 appendChild 移到 layoutSizingX = 'FILL' 之前
"Setting figma.currentPage is not supported"	使用了同步页面设置器	使用 await figma.setCurrentPageAsync(page)
属性值超出范围	颜色通道 > 1（使用了 0–255，而不是 0–1）	除以 255
"Cannot read properties of null"	节点不存在（ID 错误或页面错误）	检查页面上下文，并验证 ID
脚本挂起／无响应	无限循环或未解决的 Promise	检查是否存在 while(true) 或遗漏的 await；确保代码能够终止
"The node with id X does not exist"	子节点调用 detachInstance() 后，父实例被隐式分离，导致 ID 发生变化	从稳定的（非实例）父级框架开始遍历，重新查找节点

当脚本成功运行但结果看起来不对时

1. 调用 get_metadata 检查结构是否正确（层级、数量、位置）。
2. 调用 get_screenshot 检查视觉效果。仔细查看是否有文字被裁切（行高导致内容被截断）或元素重叠——这些问题很常见，也容易被忽略。
3. 找出差异——是结构问题（层级错误、缺少节点），还是视觉问题（颜色错误、布局异常、内容被裁切）？
4. 编写有针对性的修复脚本，只修改出问题的部分——不要重新创建所有内容。

如需了解完整的验证工作流，请参阅 验证与错误恢复。

7. 提交前检查清单

提交任何 use_figma 调用之前，请确认：

• 代码使用 return 返回数据（不要使用 figma.closePlugin()）
• 代码没有包装在异步 IIFE 中（系统会自动包装）
• return 值包含带有可操作信息的结构化数据（ID、数量）
• 任何地方都没有使用 figma.notify()
• 没有使用 console.log() 输出内容（请改用 return）
• 所有颜色都使用 0–1 范围（不是 0–255）
• 填充和描边都作为新数组重新赋值（不要原地修改）
• 页面切换使用 await figma.setCurrentPageAsync(page)（同步设置器会抛出错误）
• layoutSizingVertical/Horizontal = 'FILL' 在 parent.appendChild(child) 之后设置
• 更改任何文本属性之前都调用 loadFontAsync()
• lineHeight/letterSpacing 使用 {unit, value} 格式（不是裸数字）
• 设置尺寸模式之前先调用 resize()（resize() 会将其重置为 FIXED）
• 对于多步骤工作流：将上一次调用得到的 ID 作为字符串字面量传入（不要使用变量）
• 新建的顶层节点放置在远离 (0,0) 的位置，以避免与现有内容重叠
• 收集所有创建或修改的节点 ID，并将其包含在 return 值中
• 每个异步调用（loadFontAsync、setCurrentPageAsync、importComponentByKeyAsync 等）都使用 await 等待完成——不要创建即弃用的 Promise

8. 创建前了解约定

创建任何内容之前，务必检查 Figma 文件。 不同文件使用的命名约定、变量结构和组件模式各不相同。你的代码应与现有内容保持一致，而不是另行规定新约定。

如果不确定任何约定（命名、作用域、结构），请先检查 Figma 文件，再检查用户的代码库。只有两者都没有相关约定时，才采用常见模式。

快速检查脚本

列出所有页面和顶层节点：

const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
return pages.join('\n');

列出所有页面中现有的组件：

const results = [];
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  page.findAll(n => {
    if (n.type === 'COMPONENT' || n.type === 'COMPONENT_SET')
      results.push(`[${page.name}] ${n.name} (${n.type}) id=${n.id}`);
    return false;
  });
}
return results.join('\n');

列出现有的变量集合及其约定：

const collections = await figma.variables.getLocalVariableCollectionsAsync();
const results = collections.map(c => ({
  name: c.name, id: c.id,
  varCount: c.variableIds.length,
  modes: c.modes.map(m => m.name)
}));
return results;

9. 参考文档

根据任务内容按需加载：

文档	加载时机	涵盖内容
gotchas.md	在任何 use_figma 操作之前	所有已知陷阱及错误/正确代码示例
common-patterns.md	需要可运行的代码示例时	脚本框架：形状、文本、自动布局、变量、组件、多步骤工作流
plugin-api-patterns.md	创建/编辑节点时	填充、描边、自动布局、效果、分组、克隆、样式
api-reference.md	需要准确的 API 范围时	节点创建、变量 API、核心属性、支持与不支持的功能
validation-and-recovery.md	多步骤写入或错误恢复时	get_metadata 与 get_screenshot 工作流、强制错误恢复步骤
component-patterns.md	创建组件/变体时	combineAsVariants、组件属性、INSTANCE_SWAP、变体布局、发现现有组件、元数据遍历
variable-patterns.md	创建/绑定变量时	集合、模式、作用域、别名、绑定模式、发现现有变量
text-style-patterns.md	创建/应用文本样式时	字号阶梯、字体探测、样式列表、将样式应用到节点
effect-style-patterns.md	创建/应用效果样式时	投影、样式列表、将样式应用到节点
plugin-api-standalone.index.md	需要了解完整 API 范围时	Plugin API 中所有类型、方法和属性的索引
plugin-api-standalone.d.ts	需要准确的类型签名时	完整类型定义文件——搜索特定符号，不要一次性加载全部内容

10. 代码片段示例

你会在本文档中看到各种代码片段。这些片段包含实用的 Plugin API 代码，可以改作他用。可以直接使用，也可以将其作为起始代码。如果有适合以通用代码片段形式记录的关键概念，请将其标出并写入磁盘，以便日后复用。