SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场figma-use

figma-use

设计与创作

查看项目

更新于 10-15 08:27

技能介绍

用途

figma-use 是一个用于在 Figma 文件中通过 Plugin API 执行 JavaScript 的技能，配合 use_figma 工具使用。它被描述为一项强制性前置要求：在每次调用 use_figma 之前必须先加载本技能，不应在没有先加载的情况下直接调用 use_figma。该技能提供使用 Figma Plugin API 编写代码时所需的详细参考与规则。

加载本技能时，需要在调用 use_figma 的逗号分隔的 skillNames 参数中始终包含 figma-use。如果该技能是通过 MCP 资源加载的，则必须为名称加上 resource: 前缀（例如 resource:figma-use）。这是一个用于追踪技能使用情况的日志参数，不影响执行。

主要能力

该技能围绕通过 use_figma 执行 Plugin API 代码展开，提供了以下方面的指导与规则：

  • 使用 return 返回数据，返回值会自动进行 JSON 序列化；不要调用 figma.closePlugin()，也不要将代码包裹在 async IIFE 中。
  • 编写带有顶层 await 和 return 的普通 JavaScript，代码会被自动包裹在异步上下文中。
  • figma.notify() 会抛出“not implemented”，不应使用。
  • 返回节点 ID，并将工作流状态保存在 Figma 文件之外；将人类可读的组件用途与用法写入组件说明。
  • console.log() 的输出不会被返回，应使用 return 进行输出。
  • 以小的步骤增量工作，将大型操作拆分为多次 use_figma 调用，并在每一步之后进行校验。
  • 颜色为 0–1 范围（而非 0–255）：{r: 1, g: 0, b: 0} 表示红色。
  • 填充/描边是只读数组，需要克隆、修改并重新赋值。
  • 每次文本编辑都遵循规范配方：加载字体 → await → 修改 → 返回受影响的节点 ID。该规则不仅涵盖字符，还适用于任何对未加载字体的节点进行的操作（如 appendChild、insertChild、setBoundVariable 等）。
  • 页面是增量加载的，使用 await figma.setCurrentPageAsync(page) 切换页面并加载其内容；同步 setter 不工作并会抛出错误。
  • setBoundVariableForPaint 返回一个新的 paint，需要捕获并重新赋值。
  • createVariable 可接受集合对象或 ID 字符串（优先使用对象）。
  • layoutSizingHorizontal/Vertical 的取值受结构上下文限制：FIXED 总是可用，HUG 和 FILL 则不行。
  • 对于持有相关子节点的容器使用自动布局。
  • layoutSizing* 与 *AxisSizingMode 是不同的枚举，不应混用。
  • 将新的顶层节点放置在远离 (0,0) 的位置。
  • 遵循 use_figma 错误的 safeToRetryWithoutCanvasRead 指引进行错误恢复。
  • 必须返回所有创建/修改的节点 ID。
  • 创建变量时始终显式设置 variable.scopes。
  • await 每个 Promise，不要留下未 await 的 Promise。
  • 绝不要从变体组件读取 componentPropertyDefinitions。

使用方式

  • 在任何 use_figma 调用之前加载本技能。
  • 如果 Figma MCP 工具被列为延迟工具，可使用 ToolSearch 的 select: 语法在一次调用中批量加载其全部 schema，例如 ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"。
  • 如果任务涉及从代码在 Figma 中构建或更新整页、整屏或多区块布局，还应加载 figma-generate-design。
  • 如果任务涉及在 Figma 中创建或构建组件（哪怕只是单个组件），还应加载 figma-generate-library。
  • 在开始之前，加载 plugin-api-standalone.index.md 以了解可以实现什么；在需要编写插件 API 代码时，用该上下文在 plugin-api-standalone.d.ts 中 grep 相关类型、方法和属性，不要一次性加载整个大型类型文件。
  • 处理设计系统时，先从 working-with-design-systems/wwds.md 开始，然后根据需要加载关于组件、变量、文本样式和效果样式的更具体参考。
  • 页面规则：页面上下文在 use_figma 调用之间会重置；每次 use_figma 调用最多调用一次 setCurrentPageAsync，跨页任务应拆分为 N 次 use_figma 调用并并行发出（在一条消息中发出 N 个工具调用）。
  • 输出通道：agent 只能看到 return 的值；每个创建或修改画布节点的脚本都必须返回所有受影响的节点 ID。
  • 编辑模式：use_figma 在设计模式（editorType "figma"，默认）下工作；FigJam 和 Slides 有不同可用节点类型；可通过 URL 判断编辑器：Design = figma.com/design/...，FigJam = figma.com/board/...，Slides = figma.com/slides/...。
  • 高效 API：优先使用 node.query(selector) 进行类似 CSS 的节点搜索，以及 node.set(props) 进行批量属性更新，而不是冗长的替代方案。

适用场景

  • 需要在 Figma 文件中通过 Plugin API 执行 JavaScript 的任务。
  • 从代码构建或更新整页、整屏或多区块布局（配合 figma-generate-design）。
  • 在 Figma 中创建或构建组件（配合 figma-generate-library）。
  • 处理 Figma 设计系统、变量、文本样式与效果样式。
  • 跨页面读取与写入画布内容。
  • 在设计文件、FigJam 或 Slides 中工作（需注意各自可用的节点类型与 API 差异）。

限制

  • use_figma 仅在设计模式（editorType "figma"，默认）下工作；FigJam（"figjam"）和 Slides（"slides"）有不同的可用节点类型——多数设计节点在 FigJam 中被阻止，仅 FigJam 的节点在 Slides 中被阻止。
  • 仅设计模式可用的 API：figma.createPage() 仅在设计文件（figma.com/design/...）中可用；在 FigJam 和 Slides 中它会抛出 TypeError：figma.createPage no such property 'createPage' on the figma global object。
  • Slides 说明：目前尚没有专门读取 Slides 文件的工具，需用 use_figma 以只读脚本进行检查，并使用 get_screenshot / await node.screenshot() 获取视觉上下文；Slides 专用 API 指南需加载 figma-use-slides 技能。
  • 同步 setter figma.currentPage = page 不工作，会抛出“Setting figma.currentPage is not supported”。
  • figma.notify() 会抛出“not implemented”，不应使用。
  • console.log() 的输出不会返回给 agent。
  • 绝不要从变体组件读取 componentPropertyDefinitions；可选链并不能使该 getter 安全。
  • layoutSizingHorizontal/Vertical 中 HUG 和 FILL 受结构上下文限制，可能导致错误；应先将节点追加到自动布局父级，再设置 HUG/FILL。
  • 关于设计模式中可用的节点类型：Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Page、Section、TextPath 可用；Sticky、Connector、ShapeWithText、CodeBlock、Slide、SlideRow、SlideGrid、InteractiveSlideElement、Webpage 被阻止。
  • 关于 Slides 模式中可用的节点类型：Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Section、TextPath、Slide、SlideRow、SlideGrid、InteractiveSlideElement 可用；Sticky、Connector、ShapeWithText、CodeBlock、Webpage、Page 被阻止。

暂无提供的细节

本资料未提供该技能的收费、价格信息，也未提供其平台支持范围、具体效果或分步使用教程等事实。