figma-generate-library

Name: figma-generate-library
Author: figma

设计系统构建器 — Figma MCP 技能

在 Figma 中构建与代码匹配的专业级设计系统。本技能编排跨 20–100+ 次 use_figma 调用的多阶段工作流，强制执行来自真实设计系统（Material 3、Polaris、Figma UI3、Simple DS）的质量模式。

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

在调用 use_figma 作为本技能的一部分时，始终在逗号分隔的 skillNames 参数中包含 figma-generate-library。如果本技能是通过 MCP 资源加载的，则必须在名称前加上 resource:（例如 resource:figma-generate-library）。这是一个日志参数——不影响执行。

1. 最重要的规则

对于每个阶段，遵循此沟通契约。

在开始一个阶段之前：

发布一个面向用户的检查清单，标题为 Phase N Checklist。
包括该阶段将尝试的每个任务/子任务。
包括阶段退出标准。
在发布此检查清单之前，不要开始该阶段的变更工作。
如果该阶段需要明确批准，则在检查清单后请求批准并等待。

执行期间：

在每个主要子部分之前，发布一个简短更新，命名正在处理的确切部分，使用以下格式：
Working on Phase N.X: <section name>
保持更新简洁，但使当前工作可见。
当子部分完成时，如果界面支持检查清单/状态更新，则在运行中的检查清单中标记为已完成；否则在下一个进度更新中提及完成。

每个阶段结束时：

发布一个 Phase N Summary，包括：
- 已完成的任务
- 创建或更改的 Figma 对象
- 执行的验证
- 解决的决策或冲突
- 剩余风险或后续步骤
然后显示该阶段所需的阶段产物，并自动继续。
仅在阶段 0 之后或出现真正的决策分支时请求明确批准（参见第 6 节）。对于阶段 1–4，默认在总结后自动继续。

稳定的任务 ID

在所有地方使用一种任务 ID 格式：P{phase}.{step}。

规则：

仅使用带字母的步骤 ID：P0.a、P0.b、P1.a、P3.d。
不要使用纯项目符号作为任务列表。
每个阶段检查清单、进度更新、验证说明和阶段总结必须引用相同的任务 ID。

没有设置例外： 创建新的 Figma 文件、导入库、创建页面、变量、集合、样式或组件都算作创建/变更。不要将其中任何一项视为无害的设置。

这绝不是一次性任务。 构建设计系统需要跨多个阶段的 20–100+ 次 use_figma 调用，并且它们之间必须有强制性的进度。任何试图在一次调用中创建所有内容的尝试都会产生损坏、不完整或不可恢复的结果。将每个操作分解为最小的有用单元，验证，获取反馈，然后继续。

2. 强制工作流

按顺序完成阶段。在当前阶段的必要操作和验收检查完成之前，不要进入下一阶段。如果某个阶段无法通过，则停止并报告阻塞因素。除非用户明确批准限制，否则不要近似、跳过或推迟失败的阶段。没有尽力而为的替代。没有静默的近似。没有在缺少源真相、缺少视觉真相、虚假资产、近似排版、损坏的交互或未验证状态的情况下移交。

阶段 0：发现（始终优先——尚无 `use_figma` 写入）

[ ] 0a. 分析代码库 → 提取令牌、组件、命名约定
[ ] 0b. 检查 Figma 文件 → 页面、变量、组件、样式、现有约定
[ ] 0c. 搜索已订阅的库 → 使用 search_design_system 查找可重用资产
[ ] 0d. 锁定 v1 范围 → 在任何创建之前记录确切的令牌集 + 组件列表
[ ] 0e. 映射代码 → Figma → 每个冲突（代码与 Figma 不一致）都已解决并记录
[ ] 0f. 在聊天中打印差距分析：代码中存在但 Figma 中没有的内容、Figma 中存在但代码中没有的内容，以及来自 0e 的每个冲突及其解决方案

阶段 1：基础（令牌优先——始终在组件之前）

[ ] 1a. 创建变量集合和模式
[ ] 1b. 创建原始变量（原始值，1 种模式）
[ ] 1c. 创建语义变量（别名到原始变量，支持模式）
[ ] 1d. 在所有变量上设置作用域（永远不要使用 ALL_SCOPES）
[ ] 1e. 在所有变量上设置代码语法
[ ] 1f. 创建效果样式（阴影）和文本样式（排版）
[ ] 1g. 在聊天中打印变量摘要：N 个集合、M 个变量、K 种模式，按集合细分
[ ] 1h. 在聊天中打印样式列表：创建的每个效果样式和文本样式及其名称
[ ] 退出标准满足：已商定计划中的每个令牌都存在，所有作用域已设置，所有代码语法已设置

阶段 2：文件结构（在组件之前）

[ ] 2a. 创建页面骨架：封面 → 入门 → 基础 → --- → 组件 → --- → 实用工具
[ ] 2b. 创建基础文档页面（色板、字体样本、间距条）
[ ] 2c. 捕获每个基础页面的 get_screenshot，并在聊天中打印页面列表以及截图
[ ] 退出标准满足：所有计划页面存在，基础文档可导航

阶段 3：组件（一次一个——绝不批量）

对于每个组件（按依赖顺序：原子组件在前，分子组件在后），运行以下检查清单。完成当前组件后再开始下一个。

[ ] 3a. 创建专用页面
[ ] 3b. 使用自动布局 + 完整变量绑定构建基础组件
[ ] 3c. 创建所有变体组合（combineAsVariants + 网格布局）
[ ] 3d. 添加组件属性（TEXT、BOOLEAN、INSTANCE_SWAP）
[ ] 3e. 将属性链接到子节点
[ ] 3f. 添加页面文档（标题、描述、使用说明）
[ ] 3g. 验证：get_metadata（结构）+ get_screenshot（视觉）
[ ] 3h. 可选：在上下文清晰时进行轻量级 Code Connect 映射
[ ] 退出标准满足：变体数量正确，所有绑定已验证，截图看起来正确

阶段 4：集成 + 质量保证（最终检查）

[ ] 4a. 完成所有 Code Connect 映射
[ ] 4b. 可访问性审计（对比度、最小触摸目标、焦点可见性）
[ ] 4c. 命名审计（无重复、无未命名节点、大小写一致）
[ ] 4d. 未解析绑定审计（无硬编码填充/描边残留）
[ ] 4e. 每个页面的最终审查截图

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() 发现可用字体并验证确切的样式字符串——如果加载失败，查询可用字体以找到正确的名称或备用字体。

设计系统规则：

变量在组件之前——组件绑定到变量。没有令牌 = 没有组件。
创建前检查——运行只读的 use_figma 以发现现有约定。匹配它们。
每个组件一个页面 （默认）——例外：紧密相关的系列（例如，输入 + 辅助元素）可以共享一个页面，但要有清晰的部分分隔。
将视觉属性绑定到变量 （默认）——填充、描边、内边距、半径、间距。例外：故意固定的几何形状（图标像素网格尺寸、静态分隔线）。
每个变量都有作用域——切勿保留为 ALL_SCOPES。背景：FRAME_FILL, SHAPE_FILL。文本：TEXT_FILL。边框：STROKE_COLOR。间距：GAP。圆角：CORNER_RADIUS。原始变量：[]（隐藏）。
每个变量都有代码语法——WEB 语法必须使用 var() 包装器：var(--color-bg-primary)，而不是 --color-bg-primary。使用代码库中实际的 CSS 变量名称。ANDROID/iOS 不使用包装器。
将语义别名到原始变量——{ type: 'VARIABLE_ALIAS', id: primitiveVar.id }。切勿在语义层中重复原始值。
在 combineAsVariants 之后定位变体——它们堆叠在 (0,0)。手动网格布局 + 调整大小。
图标使用 INSTANCE_SWAP——切勿为每个图标创建变体。限制变体矩阵：如果尺寸 × 样式 × 状态 > 30 种组合，则拆分为子组件。
确定性命名——使用一致、唯一的节点名称，以实现幂等清理和可恢复性。通过返回值和国家账本跟踪创建的节点 ID。
无破坏性清理——清理脚本通过命名约定或返回的 ID 识别节点，而不是通过猜测。
在继续之前验证——切勿在未验证的工作上构建。每次创建后使用 get_metadata，每个组件后使用 get_screenshot。
切勿并行化 use_figma 调用——Figma 状态变更必须严格顺序执行。即使您的工具支持并行调用，也切勿同时运行两个 use_figma 调用。
切勿幻觉节点 ID——始终从先前调用返回的国家账本中读取 ID。切勿从内存中重建或猜测 ID。
使用辅助脚本——将 scripts/ 中的脚本嵌入到您的 use_figma 调用中。不要从头编写 200 行的内联脚本。

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

getPluginData() / setPluginData() 在 use_figma 中不受支持。 请改用 getSharedPluginData() / setSharedPluginData()（这些受支持），或使用基于名称的查找和国家账本（返回的 ID）。

实体类型	幂等键	如何检查存在性
场景节点（页面、框架、组件）	`setSharedPluginData('dsb', 'key', value)` 或唯一名称	`node.getSharedPluginData('dsb', 'key')` 或 `page.findOne(n => n.name === 'Button')`
变量	集合内的名称	`(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)`
样式	名称	`getLocalTextStyles().find(s => s.name === name)`

在创建后立即标记每个创建的场景节点：

node.setSharedPluginData('dsb', 'run_id', RUN_ID);        // 标识此构建运行
node.setSharedPluginData('dsb', 'phase', 'phase3');        // 哪个阶段创建的
node.setSharedPluginData('dsb', 'key', 'component/button');// 唯一逻辑键

状态持久化：不要仅依赖对话上下文来维护国家账本。将其写入磁盘：

/tmp/dsb-state-{RUN_ID}.json

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

维护一个跟踪以下内容的国家账本：

{
  "runId": "ds-build-2024-001",
  "phase": "phase3",
  "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": ["phase0", "phase1", "phase2", "component-avatar"]
}

每次创建前的幂等性检查：通过名称 + 国家账本 ID 查询。如果存在，则跳过或更新——绝不重复。

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

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

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

5. 库发现和 search_design_system——重用决策矩阵

首先在阶段 0 中搜索，然后在每个组件创建之前立即再次搜索。

从 get_libraries 开始，了解哪些库可用，然后再盲目搜索：

// 发现文件可访问的所有库
get_libraries({ fileKey })
// 返回：
//   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 非空，则还有更多组织库可用——使用 offset 设置为该值再次调用 get_libraries。组织库每批 20 个分页；社区 UI 套件仅出现在第一页。

// 在所有库中搜索（默认）
search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

// 仅在特定库中搜索
search_design_system({ query, fileKey, includeLibraryKeys: ["lk-abc123..."], includeComponents: true })

如果满足以下所有条件，则重用：

组件属性 API 满足您的需求（相同的变体轴、兼容的类型）
令牌绑定模型兼容（使用相同或可别名的变量）
命名约定与目标文件匹配
组件可编辑（未锁定在您不拥有的远程库中）

如果满足以下任一条件，则重建：

API 不兼容（不同的属性名称、错误的变体模型）
令牌模型不兼容（硬编码值、不同的变量模式）
所有权问题（无法修改库）

如果视觉匹配但 API 不兼容，则包装：

将库组件作为嵌套实例导入到新的包装器组件中
在包装器上公开干净的 API

优先级顺序：本地现有 → 已订阅库导入 → 来自 libraries_available_to_add 的未订阅 UI 套件库（尤其是图标）→ 新建。

6. 决策分支

当路径分叉时询问用户——当存在两个或更多合理答案，且代码库、Figma 文件或锁定计划中没有明确胜出者时。不要静默默认。呈现每个选项及其权衡和您的建议；仅在用户引导后选择。

何时不问： 如果从真相来源（代码、Figma 文件、已商定计划）中明确有一条路径是正确的，则采用它。本节适用于真正的歧义，而不是将每个决策都推卸出去。

分支情况	要呈现的内容	示例询问
代码与 Figma 在令牌、组件或值上不一致	两个版本并排显示，带有来源（文件/行 vs 节点）	"代码说 `--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 模式

标准模式（推荐起点）：

集合："Primitives"    模式：["Value"]
  blue/500 = #3B82F6, gray/900 = #111827, ...

集合："Color"         模式：["Light", "Dark"]
  color/bg/primary → Light: 别名 Primitives/white, Dark: 别名 Primitives/gray-900
  color/text/primary → Light: 别名 Primitives/gray-900, Dark: 别名 Primitives/white

集合："Spacing"       模式：["Value"]
  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...

9. 各阶段反模式

阶段 0 反模式：

❌ 在范围与用户锁定之前开始创建任何内容
❌ 忽略现有文件约定并强加新约定
❌ 在计划组件创建之前跳过 search_design_system

阶段 1 反模式：

❌ 在任何变量上使用 ALL_SCOPES
❌ 在语义层中重复原始值而不是使用别名
❌ 未设置代码语法（破坏开发者模式和往返）
❌ 在未商定令牌分类法之前创建组件令牌

阶段 2 反模式：

❌ 跳过封面页或基础文档
❌ 将多个不相关的组件放在一个页面上

阶段 3 反模式：

❌ 在基础存在之前创建组件
❌ 在组件中硬编码任何填充/描边/间距/半径值
❌ 为每个图标创建变体（改用 INSTANCE_SWAP）
❌ 在 combineAsVariants 之后未定位变体（它们都堆叠在 0,0）
❌ 构建变体矩阵 > 30 而不拆分（变体爆炸）
❌ 导入远程组件然后立即分离它们

通用反模式：

❌ 在未先理解错误的情况下重试失败的脚本
❌ 使用名称前缀匹配进行清理（删除用户拥有的节点）
❌ 在上一步未验证的工作上构建
❌ 并行化 use_figma 调用（始终顺序执行）
❌ 从内存中猜测/幻觉节点 ID（始终从国家账本读取）
❌ 编写大型内联脚本而不是使用提供的辅助脚本
❌ 因为用户说“构建按钮”而开始阶段 3，但未完成阶段 0-2

10. 参考文档

按需加载——每个参考对其阶段具有权威性：

使用您的文件读取工具在需要时阅读这些文档。不要根据文件名假设其内容。

文档	阶段	必需/可选	何时加载
discovery-phase.md	0	必需	开始任何构建——代码库分析 + Figma 检查
token-creation.md	1	必需	创建变量、集合、模式、样式
documentation-creation.md	2	必需	创建封面页、基础文档、色板
component-creation.md	3	必需	创建任何组件或变体
code-connect-setup.md	3–4	必需	设置 Code Connect 或变量代码语法
naming-conventions.md	任意	可选	命名任何内容——变量、页面、变体、样式
error-recovery.md	任意	出错时必需	脚本失败、多步骤工作流恢复、清理废弃工作流状态

11. 脚本

可重用的插件 API 辅助函数。嵌入到 use_figma 调用中：

脚本	用途
inspectFileStructure.js	发现所有页面、组件、变量、样式；返回完整清单
createVariableCollection.js	创建具有模式的命名集合；返回 `{collectionId, modeIds}`
createSemanticTokens.js	从令牌映射创建别名的语义变量
createComponentWithVariants.js	从变体矩阵构建组件集；处理网格布局
bindVariablesToComponent.js	将设计令牌绑定到所有组件视觉属性
createDocumentationPage.js	创建带有标题 + 描述 + 部分结构的页面
validateCreation.js	验证创建的节点是否匹配预期数量、名称、结构
cleanupOrphans.js	通过命名约定或国家账本 ID 删除孤立节点
rehydrateState.js	按名称扫描文件中的所有页面、组件、变量；返回完整的 `{key → nodeId}` 映射用于状态重建

你可能还喜欢

songsee

385Kdesign-ui

Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.

steipete

获取

ui-to-vue

237Kdesign-ui

Use when the user has UI screenshots or design exports that need batch conversion into Vue 3 components, especially with Vant, Element Plus, or Ant Design Vue.