figma-generate-library

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design System Builder — Figma MCP Skill

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

Build professional-grade design systems in Figma that match code. This skill orchestrates multi-phase workflows across 20–100+

use_figma

calls, enforcing quality patterns from real-world design systems (Material 3, Polaris, Figma UI3, Simple DS).

Prerequisites: The

figma-use

skill MUST also be loaded for every

use_figma

call. It provides Plugin API syntax rules (return pattern, page reset, ID return, font loading, color range). This skill provides design system domain knowledge and workflow orchestration.

Always pass
skillNames: "figma-generate-library"
when calling
use_figma
as part of this skill. This is a logging parameter — it does not affect execution.

在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. The One Rule That Matters Most

1. 最重要的一条规则

This is NEVER a one-shot task. Building a design system requires 20–100+

use_figma

calls across multiple phases, with mandatory user checkpoints between them. Any attempt to create everything in one call WILL produce broken, incomplete, or unrecoverable results. Break every operation to the smallest useful unit, validate, get feedback, proceed.

这绝对不是一次性任务。构建设计系统需要在多个阶段中执行20–100+次

use_figma

调用，且阶段之间必须设置用户检查点。任何试图一次性创建所有内容的操作，都会导致结果损坏、不完整或无法恢复。将每个操作拆分为最小的可用单元，验证、获取反馈后再继续。

2. Mandatory Workflow

2. 强制工作流

Every design system build follows this phase order. Skipping or reordering phases causes structural failures that are expensive to undo.

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

所有设计系统构建都必须遵循以下阶段顺序。跳过或重新排序阶段会导致结构故障，且修复成本极高。

Phase 0: 发现阶段（必须最先执行 — 暂不进行use_figma写入操作）
  0a. 分析代码库 → 提取令牌、组件、命名规范
  0b. 检查Figma文件 → 页面、变量、组件、样式、现有规范
  0c. 搜索已订阅库 → 使用search_design_system查找可复用资源
  0d. 锁定v1范围 → 在开始创建前，就确切的令牌集和组件列表达成一致
  0e. 映射代码→Figma → 解决冲突（代码与Figma不一致时，询问用户）
  ✋ 用户检查点：提交完整计划，等待明确批准

Phase 1: 基础规范阶段（先创建令牌 — 必须在组件之前）
  1a. 创建变量集合和模式
  1b. 创建原始变量（原始值，单模式）
  1c. 创建语义变量（关联到原始变量，支持多模式）
  1d. 为所有变量设置作用域
  1e. 为所有变量设置代码语法
  1f. 创建效果样式（阴影）和文本样式（排版）
  → 完成标准：计划中的每个令牌都已创建，所有作用域和代码语法已设置
  ✋ 用户检查点：展示变量摘要，等待批准

Phase 2: 文件结构阶段（在组件之前）
  2a. 创建页面框架：封面 → 快速开始 → 基础规范 → --- → 组件 → --- → 实用工具
  2b. 创建基础规范文档页面（颜色样本、字体示例、间距标尺）
  → 完成标准：所有计划页面已创建，基础规范文档可导航
  ✋ 用户检查点：展示页面列表+截图，等待批准

Phase 3: 组件阶段（逐个创建 — 绝不批量处理）
  对于每个组件（按依赖顺序：原子组件优先于分子组件）：
    3a. 创建专属页面
    3b. 构建带有自动布局+完整变量绑定的基础组件
    3c. 创建所有变体组合（使用combineAsVariants+网格布局）
    3d. 添加组件属性（TEXT、BOOLEAN、INSTANCE_SWAP）
    3e. 将属性关联到子节点
    3f. 添加页面文档（标题、描述、使用说明）
    3g. 验证：调用get_metadata（结构）+ get_screenshot（视觉）
    3h. 可选：趁上下文清晰时，完成轻量级Code Connect映射
    → 完成标准：变体数量正确，所有绑定已验证，截图符合预期
    ✋ 每个组件的用户检查点：展示截图，等待批准后再进行下一个组件

Phase 4: 集成+QA阶段（最终检查）
  4a. 完成所有Code Connect映射
  4b. 可访问性审计（对比度、最小触摸目标、焦点可见性）
  4c. 命名审计（无重复、无未命名节点、大小写一致）
  4d. 未绑定项审计（无硬编码填充/描边残留）
  4e. 所有页面的最终审核截图
  ✋ 用户检查点：完成最终签署

3. Critical Rules

3. 关键规则

Plugin API basics (from use_figma skill — enforced here too):

Use
```
return
```
to send data back (auto-serialized). Do NOT wrap in IIFE or call closePlugin.
Return ALL created/mutated node IDs in every return value
Page context resets each call — always
```
await figma.setCurrentPageAsync(page)
```
at start
```
figma.notify()
```
throws — never use it
Colors are 0–1 range, not 0–255

Font MUST be loaded before any text write:

await figma.loadFontAsync({family, style})

Design system rules:

Variables BEFORE components — components bind to variables. No token = no component.
Inspect before creating — run read-only
```
use_figma
```
to discover existing conventions. Match them.
One page per component (default) — exception: tightly related families (e.g., Input + helpers) may share a page with clear section separation.
Bind visual properties to variables (default) — fills, strokes, padding, radius, gap. Exceptions: intentionally fixed geometry (icon pixel-grid sizes, static dividers).
Scopes on every variable — NEVER leave as
```
ALL_SCOPES
```
. Background:
```
FRAME_FILL, SHAPE_FILL
```
. Text:
```
TEXT_FILL
```
. Border:
```
STROKE_COLOR
```
. Spacing:
```
GAP
```
. Radii:
```
CORNER_RADIUS
```
. Primitives:
```
[]
```
(hidden).
Code syntax on every variable — WEB syntax MUST use the
```
var()
```
wrapper:
```
var(--color-bg-primary)
```
, not
```
--color-bg-primary
```
. Use the actual CSS variable name from the codebase. ANDROID/iOS do NOT use a wrapper.
Alias semantics to primitives —
```
{ type: 'VARIABLE_ALIAS', id: primitiveVar.id }
```
. Never duplicate raw values in semantic layer.
Position variants after combineAsVariants — they stack at (0,0). Manually grid-layout + resize.
INSTANCE_SWAP for icons — never create a variant per icon. Cap variant matrices: if Size × Style × State > 30 combinations, split into sub-component.
Deterministic naming — use consistent, unique node names for idempotent cleanup and resumability. Track created node IDs via return values and the state ledger.
No destructive cleanup — cleanup scripts identify nodes by name convention or returned IDs, not by guessing.
Validate before proceeding — never build on unvalidated work.
```
get_metadata
```
after every create,
```
get_screenshot
```
after each component.
NEVER parallelize
use_figma
calls — Figma state mutations must be strictly sequential. Even if your tool supports parallel calls, never run two use_figma calls simultaneously.
Never hallucinate Node IDs — always read IDs from the state ledger returned by previous calls. Never reconstruct or guess an ID from memory.
Use the helper scripts — embed scripts from
```
scripts/
```
into your use_figma calls. Don't write 200-line inline scripts from scratch.
Explicit phase approval — at each checkpoint, name the next phase explicitly. "looks good" is not approval to proceed to Phase 3 if you asked about Phase 1.

Plugin API基础（来自use_figma技能 — 本技能同样强制执行）：

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

设计系统规则:

先变量后组件 — 组件绑定到变量。没有令牌就不能创建组件。
先检查再创建 — 先执行只读的
```
use_figma
```
调用，发现现有规范并与之匹配。
每个组件对应一个页面（默认规则）— 例外：紧密关联的组件族（如Input+辅助组件）可共享页面，但需明确划分区域。
将视觉属性绑定到变量（默认规则）— 填充、描边、内边距、圆角、间距。例外：刻意固定的几何形状（图标像素网格尺寸、静态分隔线）。
为每个变量设置作用域 — 绝不要保留为
```
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行的内联脚本。
明确的阶段批准 — 在每个检查点，明确说明下一个阶段。如果用户针对Phase 1回复“看起来不错”，这不代表批准进入Phase 3。

4. State Management (Required for Long Workflows)

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

getPluginData()
/
setPluginData()
are NOT supported in
use_figma
. Use
getSharedPluginData()
/
setSharedPluginData()
instead (these ARE supported), or use name-based lookups and the state ledger (returned IDs).

Entity type Idempotency key How to check existence

Scene nodes (pages, frames, components)

Entity type	Idempotency key	How to check existence
Scene nodes (pages, frames, components)	`setSharedPluginData('dsb', 'key', value)` or unique name	`node.getSharedPluginData('dsb', 'key')` or `page.findOne(n => n.name === 'Button')`
Variables	Name within collection	`(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)`
Styles	Name	`getLocalTextStyles().find(s => s.name === name)`

setSharedPluginData('dsb', 'key', value)

or unique name

node.getSharedPluginData('dsb', 'key')

page.findOne(n => n.name === 'Button')

Variables

Name within collection

(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)

Styles

Name

getLocalTextStyles().find(s => s.name === name)

Tag every created scene node immediately after creation:

javascript

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

State persistence: Do NOT rely solely on conversation context for the state ledger. Write it to disk:

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

Re-read this file at the start of every turn. In long workflows, conversation context will be truncated — the file is the source of truth.

Maintain a state ledger tracking:

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"]
}

Idempotency check before every create: query by name + state ledger ID. If exists, skip or update — never duplicate.

Resume protocol: at session start or after context truncation, run a read-only

use_figma

to scan all pages, components, variables, and styles by name to reconstruct the

{key → id}

map. Then re-read the state file from disk if available.

Continuation prompt (give this to the user when resuming in a new chat):

"I'm continuing a design system build. Run ID: {RUN_ID}. Load the figma-generate-library skill and resume from the last completed step."

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)`

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)

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

javascript

node.setSharedPluginData('dsb', 'run_id', RUN_ID);        // 标识本次构建运行
node.setSharedPluginData('dsb', 'phase', 'phase3');        // 标记创建该节点的阶段
node.setSharedPluginData('dsb', 'key', 'component/button');// 唯一逻辑键

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

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

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

维护状态台账，跟踪以下内容：

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 — Reuse Decision Matrix

5. search_design_system — 复用决策矩阵

Search FIRST in Phase 0, then again immediately before each component creation.

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

Reuse if all of these are true:

Component property API matches your needs (same variant axes, compatible types)
Token binding model is compatible (uses same or aliasable variables)
Naming conventions match the target file
Component is editable (not locked in a remote library you don't own)

Rebuild if any of these:

API incompatibility (different property names, wrong variant model)
Token model incompatible (hardcoded values, different variable schema)
Ownership issue (can't modify the library)

Wrap if visual match but API incompatible:

Import the library component as a nested instance inside a new wrapper component
Expose a clean API on the wrapper

Three-way priority: local existing → subscribed library import → create new.

在Phase 0先执行搜索，然后在每个组件创建前再次执行。

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

复用条件：需同时满足以下所有要求：

组件属性API符合需求（相同的变体轴、兼容的类型）
令牌绑定模型兼容（使用相同或可关联的变量）
命名规范与目标文件匹配
组件可编辑（并非在你无权拥有的远程库中锁定）

重建条件：满足以下任意一项：

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

包装条件：视觉匹配但API不兼容：

将库组件作为嵌套实例导入到新的包装组件中
在包装组件上暴露清晰的API

优先级顺序：本地现有资源 → 订阅库导入 → 新建组件

6. User Checkpoints

6. 用户检查点

Mandatory. Design decisions require human judgment.

After	Required artifacts	Ask
Discovery + scope lock	Token list, component list, gap analysis	"Here's my plan. Approve before I create anything?"
Foundations	Variable summary (N collections, M vars, K modes), style list	"All tokens created. Review before file structure?"
File structure	Page list + screenshot	"Pages set up. Review before components?"
Each component	get_screenshot of component page	"Here's [Component] with N variants. Correct?"
Each conflict (code ≠ Figma)	Show both versions	"Code says X, Figma has Y. Which wins?"
Final QA	Per-page screenshots + audit report	"Complete. Sign off?"

If user rejects: fix before moving on. Never build on rejected work.

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

检查时机	必需交付物	询问内容
发现阶段+范围锁定后	令牌列表、组件列表、差异分析	"这是我的计划。在开始创建前，请批准？"
基础规范阶段后	变量摘要（N个集合、M个变量、K个模式）、样式列表	"所有令牌已创建。在开始文件结构设置前，请审核？"
文件结构阶段后	页面列表+截图	"页面已设置完成。在开始组件创建前，请审核？"
每个组件创建后	组件页面的get_screenshot截图	"这是[组件名称]，包含N个变体。是否符合要求？"
每次冲突（代码≠Figma）时	展示两个版本	"代码中是X，Figma中是Y。以哪个为准？"
最终QA后	所有页面的截图+审计报告	"全部完成。请签署确认？"

如果用户拒绝：修复后再继续。绝不要基于被拒绝的工作继续构建。

7. Naming Conventions

7. 命名规范

Match existing file conventions. If starting fresh:

Variables (slash-separated):

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

Primitives:

blue/50

→

blue/900

gray/50

→

gray/900

Component names:

Button

Input

Card

Avatar

Badge

Checkbox

Toggle

Variant names:

Property=Value, Property=Value

— e.g.,

Size=Medium, Style=Primary, State=Default

Page separators:

---

(most common) or

——— COMPONENTS ———

Full naming reference: naming-conventions.md

与现有文件规范匹配。如果是新建项目：

变量（斜杠分隔）：

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

页面分隔符：

---

（最常用）或

——— 组件 ———

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

8. Token Architecture

8. 令牌架构

Complexity	Pattern
< 50 tokens	Single collection, 2 modes (Light/Dark)
50–200 tokens	Standard: Primitives (1 mode) + Color semantic (Light/Dark) + Spacing (1 mode) + Typography (1 mode)
200+ tokens	Advanced: Multiple semantic collections, 4–8 modes (Light/Dark × Contrast × Brand). See M3 pattern in token-creation.md

Standard pattern (recommended starting point):

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, ...

复杂度	模式
< 50个令牌	单一集合，2种模式（亮/暗）
50–200个令牌	标准模式：原始变量（单模式）+ 颜色语义变量（亮/暗）+ 间距（单模式）+ 排版（单模式）
200+个令牌	高级模式：多个语义集合，4–8种模式（亮/暗 × 对比度 × 品牌）。详见token-creation.md中的M3模式

标准模式（推荐起始方案）：

集合: "原始变量"    模式: ["值"]
  blue/500 = #3B82F6, gray/900 = #111827, ...

集合: "颜色"         模式: ["亮", "暗"]
  color/bg/primary → 亮模式：关联原始变量/white，暗模式：关联原始变量/gray-900
  color/text/primary → 亮模式：关联原始变量/gray-900，暗模式：关联原始变量/white

集合: "间距"       模式: ["值"]
  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...

9. Per-Phase Anti-Patterns

9. 各阶段反模式

Phase 0 anti-patterns:

❌ Starting to create anything before scope is locked with user
❌ Ignoring existing file conventions and imposing new ones
❌ Skipping
```
search_design_system
```
before planning component creation

Phase 1 anti-patterns:

❌ Using
```
ALL_SCOPES
```
on any variable
❌ Duplicating raw values in semantic layer instead of aliasing
❌ Not setting code syntax (breaks Dev Mode and round-tripping)
❌ Creating component tokens before agreeing on token taxonomy

Phase 2 anti-patterns:

❌ Skipping the cover page or foundations docs
❌ Putting multiple unrelated components on one page

Phase 3 anti-patterns:

❌ Creating components before foundations exist
❌ Hardcoding any fill/stroke/spacing/radius value in a component
❌ Creating a variant per icon (use INSTANCE_SWAP instead)
❌ Not positioning variants after combineAsVariants (they all stack at 0,0)
❌ Building variant matrix > 30 without splitting (variant explosion)
❌ Importing remote components then immediately detaching them

General anti-patterns:

❌ Retrying a failed script without understanding the error first
❌ Using name-prefix matching for cleanup (deletes user-owned nodes)
❌ Building on unvalidated work from the previous step
❌ Skipping user checkpoints to "save time"
❌ Parallelizing use_figma calls (always sequential)
❌ Guessing/hallucinating node IDs from memory (always read from state ledger)
❌ Writing massive inline scripts instead of using the provided helper scripts
❌ Starting Phase 3 because the user said "build the button" without completing Phases 0-2

Phase 0反模式:

❌ 在与用户锁定范围前就开始创建内容
❌ 忽略现有文件规范，强行推行新规范
❌ 在规划组件创建前跳过
```
search_design_system
```

Phase 1反模式:

❌ 为任何变量设置
```
ALL_SCOPES
```
❌ 在语义层重复原始值，而非关联到原始变量
❌ 未设置代码语法（会破坏Dev Mode和双向同步）
❌ 在达成令牌分类共识前就创建组件令牌

Phase 2反模式:

❌ 跳过封面页或基础规范文档
❌ 在一个页面中放置多个不相关的组件

Phase 3反模式:

❌ 在基础规范完成前就创建组件
❌ 在组件中硬编码任何填充/描边/间距/圆角值
❌ 为每个图标创建一个变体（改用INSTANCE_SWAP）
❌ 在combineAsVariants后不调整变体位置（它们会堆叠在0,0）
❌ 构建超过30种组合的变体矩阵而不拆分（变体爆炸）
❌ 导入远程组件后立即分离

通用反模式:

❌ 在未理解错误原因的情况下重试失败的脚本
❌ 使用名称前缀匹配进行清理（会删除用户自有节点）
❌ 基于上一步未验证的工作继续构建
❌ 跳过用户检查点以“节省时间”
❌ 并行调用use_figma（必须始终按顺序执行）
❌ 凭记忆猜测/凭空生成节点ID（始终从状态台账读取）
❌ 编写大量内联脚本，而非使用提供的辅助脚本
❌ 因为用户说“构建按钮”就直接开始Phase 3，而未完成Phases 0-2

10. Reference Docs

10. 参考文档

Load on demand — each reference is authoritative for its phase:

Use your file reading tool to read these docs when needed. Do not assume their contents from the filename.

Doc	Phase	Required / Optional	Load when
discovery-phase.md	0	Required	Starting any build — codebase analysis + Figma inspection
token-creation.md	1	Required	Creating variables, collections, modes, styles
documentation-creation.md	2	Required	Creating cover page, foundations docs, swatches
component-creation.md	3	Required	Creating any component or variant
code-connect-setup.md	3–4	Required	Setting up Code Connect or variable code syntax
naming-conventions.md	Any	Optional	Naming anything — variables, pages, variants, styles
error-recovery.md	Any	Required on error	Script fails, multi-step workflow recovery, cleanup of abandoned workflow state

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

在需要时，使用文件读取工具读取这些文档。不要仅凭文件名假设其内容。

文档	阶段	必填/可选	加载时机
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. Scripts

11. 脚本

Reusable Plugin API helper functions. Embed in

use_figma

calls:

Script	Purpose
inspectFileStructure.js	Discover all pages, components, variables, styles; returns full inventory
createVariableCollection.js	Create a named collection with modes; returns `{collectionId, modeIds}`
createSemanticTokens.js	Create aliased semantic variables from a token map
createComponentWithVariants.js	Build a component set from a variant matrix; handles grid layout
bindVariablesToComponent.js	Bind design tokens to all component visual properties
createDocumentationPage.js	Create a page with title + description + section structure
validateCreation.js	Verify created nodes match expected counts, names, structure
cleanupOrphans.js	Remove orphaned nodes by name convention or state ledger IDs
rehydrateState.js	Scan file for all pages, components, variables by name; returns full `{key → nodeId}` map for state reconstruction

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