figma-generate-library

Design System Builder — Figma MCP Skill

在 Figma 中构建与代码匹配的专业级设计系统资源。根据所需交付物调整工作流规模：一组令牌、一个组件、完整的组件库，或有针对性的对齐。将选定路径划分为连贯且可安全重试的构建阶段，并通过基于证据的验证进行检查。

前提条件：每次调用 use_figma 时，都必须同时加载 figma-use skill。它提供 Plugin API 语法规则（返回模式、页面重置、ID 返回、字体加载、颜色范围）。本 skill 提供设计系统领域知识和工作流编排。

将本 skill 用于 use_figma 调用时，skillNames 参数中始终要包含 figma-generate-library，并以逗号分隔。如果通过 MCP 资源加载本 skill，则必须为名称添加 resource: 前缀（例如：resource:figma-generate-library）。 这是一个日志参数，不会影响执行。

---

1. 范围与完成约定

首次进行更改前，根据用户的请求选择一个主要范围，并记录其中包含的交付物和验收检查项。不要擅自将较窄的请求升级为完整组件库项目。

请求范围	必需工作	除非有要求或必要，否则不包含
仅令牌／基础样式	所需变量、模式、作用域、代码语法、样式，以及所需的示例页面	组件、组件页面、Code Connect、完整组件库导航
单个组件或组件系列	检查并复用兼容的基础样式；仅创建组件所需的缺失令牌；构建所需的变体／属性／绑定；验证组件	无关的基础样式、其他组件、完整文件骨架、广泛的文档或审计
完整组件库／设计系统	调研、基础样式、文件结构、所需组件清单、文档、集成和最终 QA	超出已商定的 v1 清单的工作
对齐／更新	对比代码和 Figma，然后仅更新受影响的令牌、样式、组件、文档及依赖项	重建有效资源或扩展组件库

沟通应与工作规模相称：更改前发布一份简洁的范围与验收检查清单，在关键阶段提供进度更新，最后用一份总结说明已创建或更改的对象、验证证据和未解决的限制。不要重复未更改的检查清单，也不要逐条叙述每次 API 调用。

如果批量执行相关操作后的脚本仍可安全重试，就应将这些操作批量处理。在页面上下文边界、难以恢复的更改处，或实际故障后的定向重试中拆分操作；切勿仅为创建验证检查点而拆分正常运行的操作。更改必须按顺序进行。利用写入操作返回的结构化证据（ID 及相关数量、名称和边界）；仅在证据缺失或后续更改导致证据过时时，才单独执行审计。每个连贯的组合构建阶段进行一次视觉检查；只有在进行有针对性的视觉修复后，才额外截取一次修复后的截图。最近一张通过检查的截图即为最终截图。

完成标准

选定范围内的所有条件均满足后即停止：

• 最终交付物涵盖已锁定的清单，并与适用的事实来源实质一致，包括请求的变体／状态覆盖、所需资源，以及范围内的审查示例。
• 对于组件任务，将主组件和构建资源置于最终审查画面之外，并在一个紧凑画面中以实例展示请求的状态。停止前，以正常比例检查该画面，并修复被裁切、截断、对比度低、为空、位置不当或脱离主体的内容。
• 已验证所需的变量作用域、别名、代码语法、组件属性、变体和绑定。
• 请求的产物通过适用的结构和视觉验证。确认请求的内容均完整可见，除非裁切或截断是有意为之；修复缺陷，并仅重新检查受影响的输出。
• 如果来源提供了所需资源，则替换占位内容；移除临时实例、测试画面、捕获内容、废弃产物及无关的游离节点。
• 没有已知缺陷或未解决的决定会妨碍约定的验收检查通过。报告范围之外的限制，不要因此开始额外工作。

除非选定范围要求，否则补充文档、组件、Code Connect 映射、无障碍审查或推测性审计均属于后续工作。完成标准通过后，即停止。

范围变更

如果用户更改交付物，请更新范围和验收清单。保留已验证的工作，仅执行新适用的步骤，不要追溯添加未选路径中的工作。

---

2. 范围化工作流

每个范围都从有针对性的发现开始：分析相关代码，检查目标 Figma 资源和惯例，在调用 search_design_system 之前调用 get_libraries，并在修改前解决代码与 Figma 之间的冲突。批量执行相互独立的搜索，并复用搜索结果。锁定请求的清单，然后仅执行下方对应的路径。

令牌／基础

1. 创建或更新请求的集合、模式、原始变量、语义别名、作用域和代码语法。
2. 创建请求的文本样式和效果样式。
3. 仅在用户请求时创建示例或文档页面。
4. 验证数量、模式值、别名、作用域、语法、样式及任何请求的视觉产物；然后停止。

单个组件或组件系列

1. 检查并复用兼容的本地或库变量、文本样式和效果样式。仅创建组件所需的缺失基础项。对于源代码定义、库标准或重复出现的组件角色，创建或复用共享文本样式或效果样式，并将其应用于所有匹配的组件节点；一次性文档内容保留为内联样式。
2. 构建请求的基础组件、变体、属性、绑定和依赖组件。
3. 如果文件惯例适合使用专用页面，或请求需要有文档说明的展示页，则使用专用页面；否则将其放在现有组件区域。
4. 验证变体数量、属性、变量绑定、代表性节点上应用的文本／效果样式 ID、结构和外观；然后停止。

完整库／设计系统

1. **发现：**锁定令牌和组件清单，并输出差距分析。
2. **基础：**创建集合、变量、别名、作用域、代码语法和样式。
3. **文件结构：**创建约定的封面、入门、基础、组件和工具页面，以及请求的文档。
4. **组件：**按依赖顺序构建约定的清单，并包含属性、绑定、文档和验证。
5. **集成与 QA：**为约定的组件清单完成 Code Connect 映射；审查无障碍、命名和绑定；并对每个约定页面进行视觉验证。

对齐／更新

1. 清点现有资源，并找出与当前代码源的确切差异。
2. 原地更新受影响的资源；尽可能保留有效名称、ID、绑定和库结构。
3. 验证已更改的资源及其已知依赖项，然后停止。

如果必需的验收检查未通过，请先修复范围内的缺陷再继续。不要用伪造资源、近似字体、失效交互或未经验证的状态来替代。

本技能选定的工作流、搜索节奏、验证规则和完成定义优先于参考资料中的更广泛指引、清单和示例。仅加载选定路径所需的参考资料。

---

3. 关键规则

插件 API 基础知识（来自 use_figma 技能——此处同样适用）：

• 使用 return 返回数据（会自动序列化）。不要使用 IIFE 包装，也不要调用 closePlugin。
• 每次返回时，都要包含所有已创建／已修改节点的 ID
• 每次调用都会重置页面上下文——始终在开头调用 await figma.setCurrentPageAsync(page)。每个脚本最多调用一次：每个组件或文档页面都应作为单独的 use_figma 调用。切勿在修改脚本中遍历 figma.root.children 并在页面间切换——应针对每个目标页面，将工作拆分为一次聚焦调用（参见 figma-use → gotchas.md → 每次 use_figma 调用只设置一次当前页面）
• figma.notify() 会抛出异常——切勿使用
• 颜色取值范围为 0–1，而非 0–255
• 写入任何文本前，必须先加载字体：await figma.loadFontAsync({family, style})。使用 await figma.listAvailableFontsAsync() 查找可用字体并确认精确的样式字符串——如果加载失败，请查询可用字体，找到正确名称或备用字体。 设计系统规则：

1. 先构建基础，再构建依赖组件 — 复用兼容的现有变量和样式。构建依赖这些基础的组件前，先补齐缺失的基础；不要重新创建有效的基础。
2. 创建前先检查 — 运行只读的 use_figma，了解现有规范，并与之保持一致。
3. 遵循文件的组件组织方式 — 完整的组件库通常每个组件使用一个页面；紧密相关的组件系列可以共用一个页面。单组件任务可以使用现有组件区域，而不必创建组件库骨架。
4. 将视觉属性绑定到变量 （默认） — 填充、描边、内边距、圆角、间距。例外：有意固定的几何尺寸（图标像素网格尺寸、静态分隔线）。使用较早一次 use_figma 调用中的变量时，绑定前请使用该调用返回的真实 Figma 变量 ID 重新解析句柄；JavaScript 引用不会跨调用保留。
   使用 Plugin API 时，绑定前请通过 await figma.variables.getVariableByIdAsync(id) 解析变量。
5. 为每个变量设置作用域 — 绝不保留为 ALL_SCOPES。背景：FRAME_FILL, SHAPE_FILL。文本：TEXT_FILL。边框：STROKE_COLOR。间距：GAP。圆角：CORNER_RADIUS。原始变量：[]（隐藏）。
6. 为每个变量设置代码语法 — WEB 语法必须使用 var() 封装：var(--color-bg-primary)，不能写成 --color-bg-primary。使用代码库中的实际 CSS 变量名。ANDROID/iOS 不使用封装。
7. 将语义变量别名指向原始变量 — { type: 'VARIABLE_ALIAS', id: primitiveVar.id }。绝不在语义层重复原始值。
8. 在 combineAsVariants 后排列变体 — 它们会堆叠在 (0,0) 处。手动按网格排列并调整大小。
9. 图标使用 INSTANCE_SWAP — 绝不为每个图标创建一个变体。限制变体矩阵规模：如果尺寸 × 样式 × 状态的组合数 > 30，请拆分为子组件。
10. 使用确定性的命名方式 — 为节点使用一致且唯一的名称，以便实现幂等清理和断点续做。通过返回值和状态账本记录创建的节点 ID。
11. 不进行破坏性清理 — 清理脚本应根据命名约定或返回的 ID 识别节点，而不是猜测。
12. 根据证据验证后再继续 — 绝不基于未经验证的工作继续构建。依据写入操作返回的结构证据（ID 及相关数量、名称和边界）；只有在需要确认验收检查，或相关变更使之前的证据失效时，才针对每个连贯阶段运行一次批量结构审计。每个连贯的组合阶段进行一次视觉检查；只有在针对性视觉修复后，才额外截取一次修复后的屏幕截图。
13. 绝不并行调用 use_figma — Figma 状态变更必须严格按顺序执行。即使工具支持并行调用，也绝不同时运行两个 use_figma 调用。
14. 绝不臆造 Node ID — 始终从先前调用返回的状态账本中读取 ID。绝不凭记忆重建或猜测 ID。
15. 使用辅助脚本 — 将 scripts/ 中的脚本嵌入 use_figma 调用。不要从头编写 200 行的内联脚本。

4. 状态管理（长工作流必需）

不要将工作流状态存储在 Figma 对象上。使用确定性名称进行查找，并在状态台账中记录精确返回的 ID。将组件用途和使用指南以易读的形式写入组件或组件集的 description。

实体类型	稳定标识	如何检查是否存在
页面和画框	确定性名称 + 状态台账 ID	figma.root.children.find(p => p.name === pageName) 或 await figma.getNodeByIdAsync(id)
组件和组件集	变体/集合名称 + 状态台账 ID	page.findOne(n => n.name === name) 或 await figma.getNodeByIdAsync(id)
变量	集合内的名称	(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)
样式	名称	getLocalTextStyles().find(s => s.name === name)

创建后立即在状态台账中记录每个返回的 ID。绝不要使用模糊查找来授权删除。

状态持久化：不要仅依赖对话上下文保存状态台账。将其写入磁盘：

/tmp/design-system-state-{RUN_ID}.json

在每轮开始时重新读取此文件。在长工作流中，对话上下文会被截断——此文件才是事实来源。

维护状态台账，跟踪：

{
  "runId": "ds-build-2024-001",
  "scope": "single-component",
  "step": "component-button",
  "entities": {
    "collections": { "primitives": "id:...", "color": "id:..." },
    "variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },
    "pages": { "Cover": "id:...", "Button": "id:..." },
    "components": { "Button": "id:..." }
  },
  "pendingValidations": ["Button:screenshot"],
  "completedSteps": ["discovery", "foundations/verified", "component-button/base"]
}

幂等性检查：每次创建前，按名称 + 状态台账 ID 查询。如果已存在，则跳过或更新——绝不重复创建。

恢复协议：在会话开始时或上下文被截断后，运行只读的 use_figma，按名称扫描所有页面、组件、变量和样式，以重建 {key → id} 映射。然后从磁盘重新读取状态文件（如果可用）。

续接提示词（在新聊天中恢复时提供给用户）：

“我正在继续构建设计系统。运行 ID：{RUN_ID}。加载 figma-generate-library 技能，并从上次完成的步骤继续。”

---

5. 库发现与 search_design_system — 复用决策矩阵

在限定范围的发现阶段进行搜索，并复用搜索结果。只有当组件不在原始清单中、可用库发生变化，或先前的结果无法解决问题时，才在组件开发前再次搜索。

针对目标文件调用 search_design_system 前，必须先为该文件调用 get_libraries。不得假定已有库已添加或可用。

get_libraries 返回空结果并不能成为跳过搜索的理由——这只意味着没有可用于限定搜索范围的库键。get_libraries 会分页（社区 UI 套件仅显示在第一页，组织库每页显示 20 个），因此列表为空并不能证明没有库。根据结果采取以下操作：

• 返回了库 — 使用 includeLibraryKeys 限定范围，运行 search_design_system。libraries_available_to_add 中的库默认不会被搜索；传入它们的 libraryKey 才能搜索这些库。
• 未返回库 — 仍须运行 search_design_system，但省略 includeLibraryKeys。省略该参数会将搜索范围限定为文件本身；当发现阶段没有返回可供限定范围的库时，这正是所需做法。

只有当搜索本身返回空结果后，才能在差距分析中记录“没有可用的设计系统资源”，并使用代码令牌进行构建。不得根据失败或未尝试的 get_libraries 调用推断“没有库”。

// Discover all libraries accessible to the file
get_libraries({ fileKey })
// Returns:
//   libraries_added_to_file: [{ name, libraryKey, description, source }, ...]
//   libraries_available_to_add: [{ name, libraryKey, description, source }, ...]
//   libraries_available_to_add_next_offset: number | null

使用返回的 libraryKey 值，通过 includeLibraryKeys 将搜索范围限定为特定库。可用库较多时，这样能减少无关结果。

如果 libraries_available_to_add_next_offset 不为 null，则表示还有更多组织库可用——使用该值作为 offset，再次调用 get_libraries。组织库每页显示 20 个；社区 UI 套件仅显示在第一页。

// Search across all libraries (default)
search_design_system({
  queries: [
    { entity: "component", query },
    { entity: "variable", query },
    { entity: "style", query }
  ],
  fileKey
})

// Search within a specific library only
search_design_system({ queries: [{ entity: "component", query }], fileKey, includeLibraryKeys: ["lk-abc123..."] })

满足以下所有条件时复用：

• 组件属性 API 符合需求（变体维度相同，类型兼容）
• 令牌绑定模型兼容（使用相同或可设别名的变量）
• 命名约定与目标文件一致
• 组件可编辑（未锁定在你无权访问的远程库中）

出现以下任一情况时重建：

• API 不兼容（属性名称不同，变体模型不符）
• 令牌模型不兼容（硬编码值，变量架构不同）
• 归属权问题（无法修改该库）

视觉效果匹配但 API 不兼容时包装：

• 将库组件作为嵌套实例导入新的包装组件
• 在包装组件上公开简洁的 API

优先顺序：本地已有组件 → 导入已订阅的库 → 使用 libraries_available_to_add 中未订阅的 UI Kit 库（尤其是图标）→ 新建。

---

6. 决策分歧

出现决策分歧时询问用户——即有两个或多个合理选项，且无法从代码库、Figma 文件或已锁定的计划中明确判断哪个更合适。不要默默选择默认选项。说明每个选项的利弊并给出建议；只有在用户明确选择后再执行。

**何时不要询问：**如果根据事实来源（代码、Figma 文件、已达成一致的计划）可以明确判断只有一种正确做法，就直接采用。本节适用于确实存在歧义的情况，不是让你把所有决定都推给用户。

分歧情况	需要说明的内容	示例提问
代码与 Figma 在令牌、组件或值上不一致	并列展示两个版本及其出处（文件/行号与节点）	“代码中是 --color-bg-primary = #FFFFFF，Figma 中是 color/bg/primary = #FAFAFA。应以哪个为准？”
已订阅的库中有相似但不完全匹配的组件	库组件摘要及差距列表	“库中有 Button，但没有 loading 状态。是在本地复用并包装，还是从头重建？”
计划锁定时（0d）范围不明确	明确属于范围内、明确不属于范围内以及存在歧义的内容	“规范列出了 Button 和 Input；有提及 Field，但没有定义。它属于 v1 范围吗？”

**如果用户拒绝了你已经据此构建的选项：**继续之前先修正。绝不要基于已被否决的工作继续构建。

---

7. 命名规范

遵循现有文件约定。如果从头开始：

变量（斜杠分隔）：

color/bg/primary     color/text/secondary    color/border/default
spacing/xs  spacing/sm  spacing/md  spacing/lg  spacing/xl  spacing/2xl
radius/none  radius/sm  radius/md  radius/lg  radius/full
typography/body/font-size    typography/heading/line-height

基元：blue/50 → blue/900，gray/50 → gray/900

组件名称：Button、Input、Card、Avatar、Badge、Checkbox、Toggle

变体名称：Property=Value, Property=Value — 例如：Size=Medium, Style=Primary, State=Default

页面分隔符：---（最常见）或 ——— COMPONENTS ———

完整的命名参考：naming-conventions.md

---

8. 令牌架构

复杂度	模式
< 50 个令牌	单个集合，2 种模式（浅色/深色）
50–200 个令牌	标准：基元（1 种模式）+ 颜色语义（浅色/深色）+ 间距（1 种模式）+ 字体排版（1 种模式）
200+ 个令牌	高级：多个语义集合，4–8 种模式（浅色/深色 × 对比度 × 品牌）。参见 token-creation.md 中的 M3 模式

标准模式（推荐的起点）：

Collection: "Primitives"    modes: ["Value"]
  blue/500 = #3B82F6, gray/900 = #111827, ...

Collection: "Color"         modes: ["Light", "Dark"]
  color/bg/primary → Light: alias Primitives/white, Dark: alias Primitives/gray-900
  color/text/primary → Light: alias Primitives/gray-900, Dark: alias Primitives/white

Collection: "Spacing"       modes: ["Value"]
  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...

---

9. 反模式

探索与范围：

• ❌ 忽略现有约定，或跳过相关代码、文件和库的探索
• ❌ 将狭窄的请求扩展为不相关的基础内容、文档或完整的库

基础：

• ❌ 使用 ALL_SCOPES、在语义层重复基元值，或省略代码语法
• ❌ 在基础尚未建立时创建依赖这些基础的组件

组件：

• ❌ 存在兼容变量时，仍将组件填充、描边、间距或圆角硬编码
• ❌ 为每个图标创建一个变体，而不是使用 INSTANCE_SWAP
• ❌ 执行 combineAsVariants 后，仍将变体堆叠在 (0,0)
• ❌ 创建超过 30 个项目的变体矩阵，而不拆分
• ❌ 导入远程组件后立即分离它们

执行与恢复：

• ❌ safeToRetryWithoutCanvasRead 为 false 时，尚未读取画布就重试
• ❌ 使用名称前缀匹配进行清理（会删除用户拥有的节点）
• ❌ 基于上一步未经验证的工作继续构建
• ❌ 并行调用 use_figma（始终按顺序调用）
• ❌ 凭记忆猜测或臆造节点 ID（始终从状态台账中读取）
• ❌ 编写庞大的内联脚本，而不使用提供的辅助脚本

---

10. 参考文档

按需阅读参考文档；不要根据文件名推断其内容。

文档	何时加载
discovery-phase.md	在修改前分析相关代码和 Figma 资源
token-creation.md	创建变量、集合、模式或样式
documentation-creation.md	所选范围包含封面或基础文档
component-creation.md	创建组件或变体
code-connect-setup.md	所选范围包含 Code Connect 或变量代码语法
naming-conventions.md	为变量、页面、变体或样式命名
error-recovery.md	脚本失败，或需要清理已放弃的工作流状态

---

11. 脚本

可复用的 Plugin API 辅助函数。在 use_figma 调用中嵌入：

脚本	用途
inspectFileStructure.js	查找所有页面、组件、变量和样式；返回完整清单
createVariableCollection.js	创建带有模式的命名集合；返回 {collectionId, modeIds}
createSemanticTokens.js	根据令牌映射创建别名语义变量
createComponentWithVariants.js	根据变体矩阵构建组件集；处理网格布局
bindVariablesToComponent.js	将设计令牌绑定到组件的所有视觉属性
createDocumentationPage.js	创建包含标题、描述和分区结构的页面
validateCreation.js	验证创建的节点是否符合预期数量、名称和结构
cleanupOrphans.js	仅删除状态台账中提供的确切节点、变量和集合 ID