figma-generate-design

基于设计系统构建/更新页面与视图

使用本 Skill 可通过复用已发布的设计系统（包括组件、变量和样式）在 Figma 中创建或更新页面、视图和多板块 UI 容器，而不是手绘写死数值的基础图形。适用场景涵盖完整页面、弹窗（modal）、对话框（dialog）、抽屉（drawer）、侧边栏（sidebar）、面板（panel）以及任何包含多个板块的组合视图。核心要点在于：Figma 文件中通常已存在发布好的设计系统，其中的组件、颜色/间距变量以及文本/效果样式与代码库中的 UI 组件和 Token 互相对应。你应该找到并使用它们，而不是用十六进制颜色画框框。

强制要求：在调用任何 use_figma 之前，你必须先加载 figma-use。该 Skill 包含适用于你编写的所有脚本的关键规则（如颜色范围、字体加载等）。

作为本 Skill 的一部分调用 use_figma 时，务必在以逗号分隔的 skillNames 参数中包含 figma-generate-design。如果本 Skill 是通过 MCP 资源加载的，必须为名称添加 resource: 前缀（例如 resource:figma-generate-design）。 这是一个仅用于日志记录的参数，不会影响脚本执行。

Skill 适用边界

• 如果交付物是由设计系统组件实例构成的** Figma 组合视图**（新建或更新）——如全屏页面、弹窗、对话框、抽屉、侧边栏、面板或任何多板块容器——请使用本 Skill。
• 如果用户想要创建新的可复用组件或变体，请直接使用 figma-use。
• 如果用户想要编写 Code Connect 映射，请切换至 figma-code-connect。

前置条件

• Figma MCP 服务器必须处于连接状态
• 目标 Figma 文件中必须包含已发布的设计系统组件（或拥有团队组件库的访问权限）
• 用户必须提供目标 Figma 文件（URL 或 fileKey）。如果用户还没有文件，请先调用 /figma-create-new-file（或调用 create_new_file），并复用返回的 file_key。use_figma 和 generate_figma_design 都要求传入已存在的 fileKey。
• 待构建/更新的页面/视图源代码或需求描述

与 generate_figma_design 的并行工作流（仅限 Web 应用）

当根据可在浏览器中渲染的 Web 应用构建页面时，同时并行运行两种方法效果最佳：

1. 并行执行：
   • 针对目标 Figma 文件（fileKey），基于本 Skill 的工作流（use_figma + 设计系统组件）开始构建页面。
   • 针对同一个 fileKey 运行 generate_figma_design，将运行中的 Web 应用截图像素级精准地捕获到该文件中。generate_figma_design 始终需要 fileKey——如果用户还没有 Figma 文件，先调用 /figma-create-new-file（或调用 create_new_file MCP 工具）新建一个，并在本 Skill 和截图捕获中复用该 file_key。
2. 两者均完成后： 微调 use_figma 的输出，使其匹配 generate_figma_design 捕获到的像素级排版。捕获结果给出了精准的间距、尺寸和视觉效果作为参考标准，而你的 use_figma 输出则拥有链接到设计系统的正规组件实例。如果捕获结果中包含图片，可以通过从捕获图的图片填充中复制 imageHash 值，将其转移到你的 use_figma 输出中（详情参见步骤 5）。
3. 确认视觉效果良好后： 删除 generate_figma_design 的输出内容——它仅用作视觉参考。

这种结合兼具两者优势：generate_figma_design 带来了像素级的布局精准度，而 use_figma 则提供了保持链接且可随时更新的设计系统正规组件实例。

当源码包含图片时，此并行工作流是强制要求的。 use_figma Plugin API 无法直接拉取外部图片 URL——它只能通过复制文件中已有节点的 imageHash 值来设置图片填充。generate_figma_design 会将所有可见图片栅格化并导入 Figma，从而提供你所需的 hash 值。如果包含图片却跳过截图捕获，图片框架将会留白。

对于非 Web 应用（iOS、Android 等）或更新已有页面时，请使用下方的标准工作流。

必备工作流

请严格按顺序执行以下步骤，切勿跳步。

硬性卡点——严禁走捷径：

• 严禁： 在完成步骤 2a-i 且尝试过步骤 2a-ii 或记录为不适用（例如“空文件，无现有页面”）之前，直接调用 search_design_system 搜索组件 key。
• 严禁： 在下表步骤 2 中的所有行均填妥之前，调用任何修改画布的 use_figma（步骤 3 及以后）。

步骤 1：理解交付目标

在动手操作 Figma 之前，先理清你要构建的内容：

1. 如果是根据代码构建，请阅读相关的源码文件，了解页面结构、板块划分以及使用了哪些组件。
2. 识别视图的主要板块（例如页面包括：Header、Hero 区域、内容面板、Footer；弹窗包括：标题栏、表单区域、操作按钮栏；侧边栏包括：导航栏、内容区、底部操作区）。
3. 罗列各个板块用到的 UI 组件（按钮、输入框、卡片、导航标签、手风琴折叠面板等）。
4. 从源码中确认产品使用的字体系列，切勿默认使用 Inter。 在编写任何脚本前，先搞清楚产品具体使用了哪种字体。有关查找位置（CSS 变量、组件文件）以及如何处理 Figma 中杂乱字体名称的说明，详见 references/discover-product-font.md。
5. 检查视图中是否包含任何图片（如 <img>、<Image>、背景图、商品图、头像、通过 URL 加载的图标等）。如果包含且这是一个 Web 应用，你必须运行并行 generate_figma_design 截图捕获工作流——在进行步骤 2 的同时立即启动截图，以便在探查组件的同时同步运行捕获。参见前文“与 generate_figma_design 的并行工作流”。

步骤 2：收集组件 Key、变量与样式

你需要从设计系统中提取三样东西：组件（按钮、卡片等）、变量（颜色、间距、圆角等）以及样式（文本样式、阴影等效果样式）。在存在设计系统 Token 时，不要硬编码十六进制颜色或像素值。

2a：探查组件

2a-i — 强制步骤：检查所需组件的 Code Connect 映射。 从步骤 1 中梳理出的组件清单入手，检查代码库中每个组件是否关联了 Code Connect 文件。Code Connect 文件与组件源码位于同一目录下，命名因平台而异：

• TypeScript/JS: *.figma.ts, *.figma.js
• React (parser-based): *.figma.tsx
• Kotlin/Compose：包含 @FigmaConnect 的 .kt 文件
• Swift：包含 FigmaConnect 的 .swift 文件

对于所需的每个组件（如 Button、Card、Input），搜索其对应的 Code Connect 文件——通过组件名进行 glob 通配或 grep 搜索（例如 **/Button.figma.tsx、**/Card.figma.ts）。仅读取与实际所需组件匹配的文件。

从匹配到的各个 Code Connect 文件中提取 Figma 组件 URL。解析 URL 中的 fileKey 和 nodeId（将连字符转为冒号：123-456 → 123:456）。然后通过 use_figma 解析出组件的 key：

示例： Code Connect 文件包含 // url=https://figma.com/design/ABC123/File?node-id=609-35535。解析得出 fileKey = ABC123，nodeId = 609:35535。针对组件库文件（fileKey 为 ABC123，而非目标文件）运行 use_figma 来解析 key：

const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };

可在单次调用中批量查询多个。在步骤 4 中结合 importComponentSetByKeyAsync() 使用返回的 key。

标记已解析的组件。如果所有组件均已解析完成，可跳过 2a-ii 和 2a-iii。如果所需组件均无 Code Connect 文件，请继续执行 2a-ii。

2a-ii — 存在未解析组件时的强制步骤：检查现有页面。 检查目标文件中是否已包含使用同一设计系统的页面。调用一次 use_figma 遍历现有 Frame 内的实例，即可获取精准且权威的组件映射表：

const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
  const mc = inst.mainComponent;
  const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
  const key = cs ? cs.key : mc?.key;
  const name = cs ? cs.name : mc?.name;
  if (key && !uniqueSets.has(key)) {
    uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
  }
});
return [...uniqueSets.values()];

将结果与待解析的组件进行匹配，标记新解析出的组件。如果所有组件均已解析完成，可跳过 2a-iii。

2a-iii — 终极兜底方案：search_design_system。 仅当完成 2a-i 和 2a-ii 后仍有未解析组件时才可使用。

在搜索前，先调用 get_libraries 探索当前文件可用的组件库。该接口会返回两个列表：已添加到文件的组件库，以及可添加的组件库（社区 UI Kit 和组织组件库）。每条记录包含一个 libraryKey，你可以将其通过 includeLibraryKeys 参数传给 search_design_system，从而将搜索范围精确限定在特定的组件库中，避免漫无目的地全局搜索。

// Step 1: Discover available libraries
get_libraries({ fileKey })
// Returns: {
//   libraries_added_to_file: [...],
//   libraries_available_to_add: [...],
//   libraries_available_to_add_next_offset: number | null
// }

// Step 2: Search within a specific library using its libraryKey
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })

libraries_available_to_add 中的组织组件库支持分页（每页 20 个）。当 libraries_available_to_add_next_offset 不为空时，说明还有更多组织组件库——再次调用 get_libraries 并将 offset 设置为该值以拉取下一页。社区 UI Kit 仅在第一页显示。如果用户指定了某个在当前页未看到的组件库，请继续翻页查找，不要轻易放弃。

当文件中关联了大量组件库且你希望获取精准结果时（例如仅在 "iOS 26" 或 "Material 3" 中搜索，而不是匹配所有组件库），此方法尤其管用。

扩大搜索范围——尝试使用多种关键词和同义词（例如 "button"、"input"、"nav"、"card"、"accordion"、"header"、"footer"、"tag"、"avatar"、"toggle"、"icon" 等）。使用 includeComponents: true 来聚焦搜索组件。

在你的映射表中包含组件属性信息——你需要了解各个组件暴露了哪些文本（TEXT）属性以进行文本覆盖。可以先创建一个临时实例，读取其 componentProperties（以及嵌套实例的属性），然后再将该临时实例移除。

带属性信息的组件映射表示例：

Component Map:
- Button → key: "abc123", type: COMPONENT_SET
  Properties: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
  Properties: { "Device": VARIANT, "Variant": VARIA

<!-- truncated for translation batch; full body continues in source -->