figma-generate-library

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

在 Figma 中构建与代码匹配的专业级设计系统。此技能通过 20–100+ 次 use_figma 调用协调多阶段工作流，并遵循真实设计系统（Material 3、Polaris、Figma UI3、Simple DS）中的质量模式。

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

在此技能中调用 use_figma 时，始终传入 skillNames: "figma-generate-library"。 这是一个日志参数，不会影响执行。

---

1. 最重要的一条规则

这绝不是一次性任务。 构建设计系统需要在多个阶段中调用 use_figma 20–100+ 次，并在各阶段之间设置强制的用户检查点。试图一次调用完成所有工作，必然会产生损坏、不完整或无法恢复的结果。将每项操作拆分为最小的实用单元，进行验证、获取反馈，然后继续。

---

2. 强制工作流

每次设计系统构建都必须遵循以下阶段顺序。跳过或调整阶段顺序会导致难以撤销的结构性故障。

Phase 0: DISCOVERY (always first — no use_figma writes yet)
  0a. Analyze codebase → extract tokens, components, naming conventions
  0b. Inspect Figma file → pages, variables, components, styles, existing conventions
  0c. Search subscribed libraries → use search_design_system for reusable assets
  0d. Lock v1 scope → agree on exact token set + component list before any creation
  0e. Map code → Figma → resolve conflicts (code and Figma disagree = ask user)
  ✋ USER CHECKPOINT: present full plan, await explicit approval

Phase 1: FOUNDATIONS (tokens first — always before components)
  1a. Create variable collections and modes
  1b. Create primitive variables (raw values, 1 mode)
  1c. Create semantic variables (aliased to primitives, mode-aware)
  1d. Set scopes on ALL variables
  1e. Set code syntax on ALL variables
  1f. Create effect styles (shadows) and text styles (typography)
  → Exit criteria: every token from the agreed plan exists, all scopes set, all code syntax set
  ✋ USER CHECKPOINT: show variable summary, await approval

Phase 2: FILE STRUCTURE (before components)
  2a. Create page skeleton: Cover → Getting Started → Foundations → --- → Components → --- → Utilities
  2b. Create foundations documentation pages (color swatches, type specimens, spacing bars)
  → Exit criteria: all planned pages exist, foundations docs are navigable
  ✋ USER CHECKPOINT: show page list + screenshot, await approval

Phase 3: COMPONENTS (one at a time — never batch)
  For EACH component (in dependency order: atoms before molecules):
    3a. Create dedicated page
    3b. Build base component with auto-layout + full variable bindings
    3c. Create all variant combinations (combineAsVariants + grid layout)
    3d. Add component properties (TEXT, BOOLEAN, INSTANCE_SWAP)
    3e. Link properties to child nodes
    3f. Add page documentation (title, description, usage notes)
    3g. Validate: get_metadata (structure) + get_screenshot (visual)
    3h. Optional: lightweight Code Connect mapping while context is fresh
    → Exit criteria: variant count correct, all bindings verified, screenshot looks right
    ✋ USER CHECKPOINT per component: show screenshot, await approval before next component

Phase 4: INTEGRATION + QA (final pass)
  4a. Finalize all Code Connect mappings
  4b. Accessibility audit (contrast, min touch targets, focus visibility)
  4c. Naming audit (no duplicates, no unnamed nodes, consistent casing)
  4d. Unresolved bindings audit (no hardcoded fills/strokes remaining)
  4e. Final review screenshots of every page
  ✋ USER CHECKPOINT: complete sign-off

---

3. 关键规则

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

• 使用 return 返回数据（自动序列化）。不要使用 IIFE 包装，也不要调用 closePlugin。
• 每个返回值都要包含所有已创建或已修改节点的 ID。
• 每次调用都会重置页面上下文；务必在开头执行 await figma.setCurrentPageAsync(page)。
• figma.notify() 会抛出错误，切勿使用。
• 颜色范围是 0–1，而不是 0–255。
• 写入任何文本前，必须先加载字体：await figma.loadFontAsync({family, style})

设计系统规则：

1. 先创建变量，再创建组件——组件要绑定变量。没有令牌，就不创建组件。
2. 创建前先检查——运行只读的 use_figma，了解现有规范并与之保持一致。
3. 每个组件使用一个页面（默认）——例外：紧密相关的组件系列（例如输入框及其辅助组件）可以共用一个页面，但必须明确划分区块。
4. 将视觉属性绑定到变量（默认）——填充、描边、内边距、圆角、间距。例外：有意固定的几何尺寸（图标像素网格尺寸、静态分隔线）。
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——绝不要为每个图标创建一个变体。限制变体矩阵：如果 Size × Style × State 的组合数超过 30，则拆分为子组件。
10. 使用确定性命名——为节点使用一致且唯一的名称，以支持幂等清理和恢复。通过返回值和状态账本追踪已创建节点的 ID。
11. 不要执行破坏性清理——清理脚本应根据命名规范或返回的 ID 识别节点，而不是猜测。
12. 继续操作前先验证——绝不要基于未经验证的工作继续构建。每次创建后调用 get_metadata，每个组件创建后调用 get_screenshot。
13. 绝不并行调用 use_figma——Figma 状态变更必须严格按顺序执行。即使工具支持并行调用，也绝不要同时运行两个 use_figma 调用。
14. 绝不臆造节点 ID——务必从先前调用返回的状态账本中读取 ID。绝不要凭记忆重建或猜测 ID。
15. 使用辅助脚本——将 scripts/ 中的脚本嵌入 use_figma 调用。不要从头编写 200 行的内联脚本。
16. 明确批准阶段——在每个检查点明确说出下一阶段。如果你询问的是 Phase 1，那么“看起来不错”并不代表批准继续进入 Phase 3。

---

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);        // identifies this build run
node.setSharedPluginData('dsb', 'phase', 'phase3');        // which phase created it
node.setSharedPluginData('dsb', 'key', 'component/button');// unique logical key

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

/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 中先搜索，然后在创建每个组件前立即再次搜索。

search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

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

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

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

• API 不兼容（属性名称不同、变体模型不正确）
• Token 模型不兼容（硬编码值、变量架构不同）
• 所有权问题（无法修改该库）

视觉匹配但 API 不兼容时进行包装：

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

三种方式的优先级：本地已有 → 导入已订阅的库 → 新建。

---

6. 用户检查点

必须执行。设计决策需要人工判断。

之后	所需产物	提问
发现与范围锁定	Token 列表、组件列表、差距分析	“这是我的计划。在我创建任何内容之前，请批准。”
基础内容	变量摘要（N 个集合、M 个变量、K 个模式）、样式列表	“所有 Token 均已创建。请在搭建文件结构前审核。”
文件结构	页面列表 + 截图	“页面已搭建。请在创建组件前审核。”
每个组件	组件页面的 get_screenshot	“这是包含 N 个变体的 [Component]。正确吗？”
每处冲突（代码 ≠ Figma）	展示两个版本	“代码中是 X，Figma 中是 Y。以哪个为准？”
最终 QA	每页截图 + 审核报告	“已完成。请确认验收。”

如果用户拒绝：先修正，再继续。绝不要在被拒绝的工作之上继续构建。

---

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. 各阶段的反模式

阶段 0 的反模式：

• ❌ 在与用户确定范围之前就开始创建任何内容
• ❌ 忽略现有文件约定并强行采用新约定
• ❌ 在规划组件创建前跳过 search_design_system

阶段 1 的反模式：

• ❌ 对任何变量使用 ALL_SCOPES
• ❌ 在语义层重复原始值，而不是使用别名
• ❌ 未设置代码语法（会导致 Dev Mode 和往返转换失效）
• ❌ 未就令牌分类达成一致前就创建组件令牌

阶段 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. 脚本

可复用的 Plugin 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} 映射，用于重建状态