figma-use

use_figma — Figma Plugin API Skill

使用 use_figma 工具通过 Plugin API 在 Figma 文件中执行 JavaScript 代码。所有详细的参考文档均位于 references/ 目录中。

调用 use_figma 时，必须在以逗号分隔的 skillNames 参数中包含 figma-use。如果该 Skill 是通过 MCP 资源（resource）加载的，你必须在名称前加上 resource: 前缀（例如 resource:figma-use）。 这是用于追踪 Skill 使用情况的日志参数，不会影响具体代码执行。

如果 Figma MCP 工具显示为延迟加载工具（deferred tools），请在单次 ToolSearch 调用中使用 select: 语法一次性批量加载所有 Schema — 例如 ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"。单次往返比分 6 次加载效率高得多。

如果任务涉及通过代码在 Figma 中构建或更新完整的页面、屏幕或多板块布局，还请一并加载 figma-generate-design。它提供了通过 search_design_system 检索设计系统组件、导入组件并逐步组装界面的完整工作流。两个 Skill 配合使用：本 Skill 负责 API 规则，那个 Skill 负责界面构建工作流。

如果任务涉及在 Figma 中创建或构建组件（即便是单个组件），也请一并加载 figma-generate-library。它提供了组件创建的工作流（包含变量基础、变体集、设计 Token 绑定），这些是单靠 figma-use 无法完全涵盖的。

在开始任何操作之前，请先加载 plugin-api-standalone.index.md 以了解所有可用的 API 能力。当需要编写插件 API 代码时，利用该上下文在 plugin-api-standalone.d.ts 中 grep 检索相关的类型、方法和属性。这是该 API 最权威的单一事实来源。由于该类型定义文件体量较大，切勿一次性全部加载，应根据需要按需 grep 对应章节。

重要提示：只要处理设计系统，请务必先查阅 working-with-design-systems/wwds.md，掌握在 Figma 中使用设计系统的核心概念、流程与规范。之后再根据需要加载关于组件、变量、文本样式和效果样式的专项参考文档。

1. 关键规则

1. 使用 return 返回数据。 返回值会自动被 JSON 序列化（支持对象、数组、字符串、数字）。不要调用 figma.closePlugin()，也不要把代码包裹在异步 IIFE 中 — 这些系统都已经自动处理好了。
2. 直接编写带有顶层 await 和 return 的纯 JavaScript 代码。 代码会自动嵌入到 async 上下文中。不要用 (async () => { ... })() 进行包裹。
3. figma.notify() 会直接抛出 "not implemented" 错误 — 绝对不要使用。
   3a. getPluginData() / setPluginData() 在 use_figma 中不受支持 — 请勿使用。请改用 getSharedPluginData() / setSharedPluginData()（这两个受支持），或者通过返回节点 ID 并在后续调用中传入来跟踪节点。
4. console.log() 的内容不会被返回 — 请使用 return 来输出结果。
5. 保持小步增量操作。 将大型操作拆分为多次 use_figma 调用，每完成一步都进行校验。这是避免 Bug 最重要的一条实践。
6. 颜色使用 0–1 的数值范围（而非 0–255）：{r: 1, g: 0, b: 0} 表示红色。
7. 填充（Fills）和描边（Strokes）是只读数组 — 修改时需先深拷贝/浅拷贝数组，修改后再重新赋值。
8. 每次修改文本都要严格遵循标准步骤：加载字体 → await → 变更节点 → 返回受影响的节点 ID。 跳过加载字体步骤会抛错：Cannot write to node with unloaded font "<family> <style>"。此规则不仅适用于修改 characters 属性，还适用于对未加载字体节点进行的任何操作（包括 appendChild、insertChild、setBoundVariable、setExplicitVariableModeForCollection、setValueForMode 以及在 findAll 回调中触及文本节点）。修改既有文本时，请通过 getStyledTextSegments(['fontName']) 获取该节点当前实际使用的字体，而不是使用硬编码的默认字体。绝大多数环境下 Inter 字体会自动预加载，因此使用其他字体家族时更容易触发此 Bug — 但所有字体的处理逻辑均完全一致。如果不确定字体的 style 字符串，请先调用 await figma.listAvailableFontsAsync()。详见 文本编辑标准规范。
9. 页面采用增量加载机制 — 请使用 await figma.setCurrentPageAsync(page) 来切换页面并加载页面内容。同步设置器 figma.currentPage = page 无法工作并会抛出异常（参见下文“页面规则”）。
10. setBoundVariableForPaint 会返回一个全新的 paint 对象 — 必须接收返回值并重新赋值。
11. createVariable 接受 Collection 对象或 ID 字符串作为参数（首选对象）。
12. layoutSizingHorizontal/Vertical 的可选值受结构上下文限制 — FIXED 始终可用，而 HUG 和 FILL 则有特定限制。 'HUG' 仅在自动布局（auto-layout） Frame 本身，或该 Frame 内部的文本（TEXT）子节点上有效。'FILL' 仅在自动布局 Frame 的非绝对定位、非不可变 Frame 内部、非画布网格（canvas-grid）的子节点上有效。实际操作建议：先将节点添加到自动布局父容器中，然后再设置 HUG/FILL — 新创建或尚未挂载到父节点上的节点无法满足约束条件。该属性本身存在于每一个 SceneNode 上；报错是因为非法取值被拒绝，而不是“不存在该属性”。详见 常见陷阱与误区。
    12a. 对于存在关联关系的子节点容器，务必使用自动布局。 当子节点在结构上有关联（如垂直堆叠、水平排列、对齐、定距、抱合）时，请使用 figma.createAutoLayout() 进行包裹，而不是创建使用绝对坐标 x/y 的 figma.createFrame()。绝对坐标决定的是容器在画布上的位置，而自动布局决定的是容器内部子节点的相对关系。如果不使用自动布局容器，后续面对文本换行、内容变更或重叠时将毫无抵御能力。
    12b. layoutSizing* 与 *AxisSizingMode 是不同的枚举类型 — 切勿混用。 layoutSizingHorizontal/layoutSizingVertical（在子节点上设置）取值为 'FIXED'|'HUG'|'FILL'；而 primaryAxisSizingMode/counterAxisSizingMode（在 Frame 本身上设置）取值为 'FIXED'|'AUTO'。因此 layoutSizingVertical = 'AUTO' 是非法的（应使用 'HUG'），而设置 counterAxisSizingMode = 'FILL' 会抛出 Expected 'FIXED' | 'AUTO', received 'FILL'（应使用 'FIXED'/'AUTO'）。同一 Setter 引起的另外两个常见报错：Error: in set_layoutSizingHorizontal: node must be an auto-layout frame or a child of an auto-layout frame 以及 Error: in set_layoutSizingHorizontal: FILL can only be set on children of auto-layout frames，均意味着节点尚未处于自动布局上下文中；推荐做法：先把父容器设为自动布局（figma.createAutoLayout()），并执行 appendChild 将节点挂载进去，然后再设置尺寸属性（参见规则 12）。详见 常见陷阱与误区。
13. 新创建的顶层节点请远离原点 (0,0)。 直接添加到页面上的节点默认位于 (0,0)。请先遍历 figma.currentPage.children 找到无遮挡的空白区域（例如最右侧节点的右边）。这仅适用于页面级节点 — 嵌套在其他 Frame 或自动布局容器内部的节点由其父容器负责定位。详见 常见陷阱与误区。
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。 切勿遗漏 await — 未经过 await 处理的异步调用（例如未加 await 的 figma.loadFontAsync(...) 或 figma.setCurrentPageAsync(page)）会导致“即发即弃”（fire-and-forget），进而引发静默失败或竞态条件。脚本可能在异步操作完成前就已返回，导致数据丢失或变更仅应用了一半。

各条规则的错误/正确代码示例详见 踩坑指南与常见错误。

2. 页面规则（重中之重）

在多次 use_figma 调用之间，页面上下文会自动重置 — 每次执行脚本时 figma.currentPage 都会从首页开始。

切换页面

请使用 await figma.setCurrentPageAsync(page) 来切换页面并加载页面内容。同步设置器 figma.currentPage = page 无法工作 — 在 use_figma 中会抛出 "Setting figma.currentPage is not supported" 错误。务必使用异步方法。

// 切换到指定页面（并加载其内容）
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// 现在可以访问 targetPage.children 了

每次 use_figma 调用中，setCurrentPageAsync 至多调用一次 — 多页面任务请并行分发（Fan-out）

单个脚本中切换页面的次数不得超过一次。 严禁在循环中遍历 figma.root.children 并反复切换页面。

如果任务涉及多个页面，请将其拆分为 N 次 use_figma 工具调用（每个目标页面一次），并并行发送它们 — 即在单条 Assistant 消息中包含 N 个 use_figma tool-use 块。运行环境会并发执行它们；每个脚本仅设置一次 currentPage。

明确指令： 进行并行分发时，你必须在同一条消息中提交这 N 个工具调用。不要跨多轮对话发送，也不要在发送下一个之前 await 上一个。按顺序逐页调用的速度比该规则试图替代的“循环内切换”还要慢，会彻底浪费拆分带来的性能优势。

// 避免 — 单个脚本中切换 N 次页面，每次都会重新加载文件
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // ... 操作该页面 ...
}

// 推荐 — 先通过只读查询脚本获取所有页面 ID，然后在下一条消息中
// 一口气并行发送 N 个 use_figma 工具调用（每页一个），每个脚本只设置一次 currentPage。

对于任何跨页面的任务（无论读写），请默认使用并行分发策略。完整原理解释请参阅 gotchas.md → 单次 use_figma 调用中仅设置一次 current page。

跨脚本运行

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

你可以多次调用 use_figma 来在文件状态的基础上逐步构建，或者在编写下一个脚本前先获取信息。例如，先写一个脚本获取现有节点的元数据并 return 该数据，然后在后续脚本中利用这些数据来修改节点。