Figma 设计系统发现阶段（Phase 0）实战指南：从代码库 Token 到 Figma 变量的迁移蓝图

Figma 设计系统发现阶段（Phase 0）实战指南：从代码库 Token 到 Figma 变量的迁移蓝图

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本文基于 figma-generate-library 技能仓库中 discovery-phase.md 参考文档展开。该文档是设计系统构建工作流 Phase 0（发现阶段）的权威指南，定义了在任何写入操作开始之前必须完成的五项任务：分析代码库中的 Token、检视 Figma 文件中的既有约定、搜索已订阅的组件库、构建映射计划、解决代码与 Figma 之间的冲突。

导读

本文是 figma-generate-library 技能中 Phase 0（发现阶段）的完整实战手册：它教会你如何在动手创建任何变量、组件或样式之前，从代码库中定位设计 Token 的真实来源，用只读的use_figma调用摸清 Figma 文件的既有结构，并通过search_design_system建立复用基线。读完本文，你将掌握一套"先发现、后规划、再写入"的规范流程，能够输出 Token→变量映射表、组件→组件集映射表与用户确认检查点消息，并在代码与 Figma 出现分歧时按既定框架做出不破坏任一方的决策。

该技能在 SKILL.md 中把整套设计系统构建编排为 Phase 0～4 的多阶段工作流，跨 20～100+ 次use_figma调用，其中 Phase 0 是永远最先执行、且不包含任何写操作的阶段：

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 0 的产出（Token 清单、组件清单、差距分析）将直接输入 Phase 1 Token 创建 与 Phase 3 组件创建。任何跳过或重排该阶段的行为，都会导致后期难以挽回的结构性失败。

1. 代码库分析——定位 Token 的真实来源

搜索优先级顺序

按下列顺序查找 Token 来源，找到权威来源后立即停止；多种格式可以共存：

1. 设计 Token 文件：*.tokens.json、tokens/*.json、src/tokens/**
2. CSS 变量文件：variables.css、tokens.css、theme.css、global.css
3. Tailwind 配置：tailwind.config.js、tailwind.config.ts
4. CSS-in-JS 主题对象：theme.ts、createTheme、ThemeProvider
5. 平台特定来源：iOS Asset 目录（.xcassets）、Androidthemes.xml、colors.xml

为什么顺序如此重要：Token 会以不同形态散落在代码库各处，先找到"源头文件"（如 DTCG 格式的*.tokens.json），就能避免从 Style Dictionary 或 Tokens Studio 的生成产物中反向推断，也避免从 Tailwind 的bg-blue-500这类工具类名中错误地"发明" Token（工具类名不是 Token，必须从 config 对象中取值）。

CSS 自定义属性（Web 端最常见）

需要搜索的内容：

:root { ... } @theme { ... } ← Tailwind v4 --color-*, --spacing-*, --radius-*, --shadow-*, --font-*

匹配模式：/--[\w-]+:\s*[^;]+/g

常见文件位置：src/styles/tokens.css、src/styles/variables.css、src/theme/*.css

提取与命名转换：

命名规则：在分类边界处把连字符替换为斜杠，路径最后一段内部保留连字符：--color-bg-primary→color/bg/primary，而--color-bg-primary-hover→color/bg/primary-hover。

必须始终把原始 CSS 变量名作为代码语法值存储——绝不从 Figma 变量名推导。如果代码库使用--sds-color-background-brand-default，就在setVariableCodeSyntax('WEB', '--sds-color-background-brand-default')中使用这个精确字符串。这一点与本仓库 naming-conventions.md 中"Figma 变量名与代码名并行存在"的规则完全一致：Figma 名称是给设计师看的，代码语法才是给开发者和 Dev Mode 看的真实标识。

Tailwind 配置

在tailwind.config.js或tailwind.config.ts中寻找：

// theme.extend.colors → Figma color 变量 { primary: { DEFAULT: '#3366FF', light: '#6699FF', dark: '#0033CC' } } // → color/primary/default, color/primary/light, color/primary/dark // theme.extend.spacing → Figma FLOAT 变量 { 'xs': '4px', 'sm': '8px', 'md': '16px' } // → spacing/xs = 4, spacing/sm = 8, spacing/md = 16 // theme.extend.borderRadius → Figma FLOAT 变量 { 'sm': '4px', 'md': '8px', 'lg': '16px' } // → radius/sm = 4, radius/md = 8, radius/lg = 16

Tailwind 工具类名（bg-blue-500、p-4）不是 Token——必须从 config 对象中提取值，而不是从类名中提取。同时注意 Tailwind v4 的@theme块（CSS 文件内联定义）同样属于此类来源，应一并纳入搜索范围。

DTCG 格式（Design Token Community Group）

匹配模式：*.tokens.json或tokens/*.json。务必定位源文件，而非 Style Dictionary 或 Tokens Studio 生成的输出产物。

{ "color": { "bg": { "primary": { "$type": "color", "$value": "#ffffff" }, "secondary": { "$type": "color", "$value": "#f5f5f5" } } }, "spacing": { "sm": { "$type": "dimension", "$value": "8px" } } }

嵌套键直接映射为斜杠分隔的 Figma 名称：color.bg.primary→color/bg/primary。$type字段对应 Figma 变量类型（color→COLOR、dimension→FLOAT 等），$value即该模式的原始值，两者都是建库时的直接输入。

CSS-in-JS / 主题对象

需要搜索：createTheme、ThemeProvider、theme = {}、styled-components、Emotion、Stitches、vanilla-extract

// theme.colors.bg.primary → Figma 变量: color/bg/primary // theme.spacing.sm → Figma 变量: spacing/sm // 多个主题对象 (lightTheme, darkTheme) → 同一 collection 中的 modes

对于 Chakra、Ant Design、MUI 这类不使用 CSS 自定义属性的 JS-first 系统，代码语法应设置为 JS 属性路径（如colors.gray.500、colorPrimary、theme.palette.primary.main），而不是 CSS 变量——详见 naming-conventions.md 第 9 节。

iOS Token 来源

// Asset catalog colors in .xcassets/Colors.xcassets // extension Color { static let bgPrimary = Color("bg-primary") } // Look for traitCollection.userInterfaceStyle for dark mode detection

Android Token 来源

// res/values/colors.xml <color name="primary">#3366FF</color> // res/values-night/colors.xml (dark mode overrides) // MaterialTheme.colorScheme.primary in Compose // val Primary = Color(0xFF3366FF)

检测暗色模式

Figma 映射规则：如果存在暗色模式 → 语义色 collection 至少需要 2 个 modes（Light/Dark）；原始（Primitive）collection 保持单模式。这与 token-creation.md 中"Primitives（1 mode）+ Color semantic（Light/Dark）"的标准架构完全吻合。

阴影 / 抬升提取

阴影无法成为 Figma 变量——它们将变成Effect Styles。

/* 寻找: box-shadow, --shadow-* */ --shadow-sm: 0 1px 2px rgba(0,0,0,0.05); --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.10); --shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.10);

CSS0 4px 6px -1px rgba(0,0,0,0.1)→ Figma 效果：

{ type: "DROP_SHADOW", offset: {x:0, y:4}, radius: 6, spread: -1, color: {r:0, g:0, b:0, a:0.1} }

注意颜色分量在此处已是 0–1 范围（Plugin API 要求，非 0–255），半透明 alpha 直接落在a字段。实际创建 Effect Style 的可执行脚本见 token-creation.md 第 7 节。

排版提取

复合文本样式（所有属性打包在一起）→ Figma Text Styles；单个属性 → 带相应 scope 的 Figma 变量。

组件提取

对每个组件提取：

1. 名称→ Figma 组件集（component set）名称
2. 联合类型 props→ VARIANT 属性
3. 字符串内容 props→ TEXT 属性
4. 布尔 props→ BOOLEAN 属性（与交互状态组合时 → VARIANT State）
5. 子节点/插槽 props→ INSTANCE_SWAP 属性

// React 示例: interface ButtonProps { size: 'sm' | 'md' | 'lg'; // → VARIANT: Size = sm|md|lg variant: 'primary' | 'secondary'; // → VARIANT: Style = primary|secondary disabled?: boolean; // → VARIANT: State (combine: default|hover|pressed|disabled) label: string; // → TEXT: Label icon?: ReactNode; // → INSTANCE_SWAP: Icon + BOOLEAN: Show Icon } // → Component Set "Button"，变体数量: 3 sizes × 2 styles × 4 states = 24

变体矩阵爆炸预警：本仓库 SKILL.md 与 component-creation.md 都强调，若 Size × Style × State 超过 30 种组合，应拆分出子组件（Building Blocks 模式），而不是无节制地扩张变体矩阵。

2. Figma 文件检视——只读探查既有约定

每次构建开始时都要运行以下use_figma片段。它们全部是只读操作，在用户任何检查点之前都可以安全运行。仓库提供的 inspectFileStructure.js 脚本把这些只读探查聚合为一次完整清单返回（pages、variableCollections、componentSets、textStyles、effectStyles），可以视为本节所有片段的生产级合并版本。

列出所有页面

(async () => { try { const pages = figma.root.children.map((p, i) => ({ index: i, name: p.name, id: p.id, childCount: p.children.length })); figma.closePlugin(JSON.stringify({ pages })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })();

如何解读：留意页面命名约定（是 PascalCase 还是 sentence case？），统计分隔页（---）的数量，区分既有的组件页与基础（foundations）页。

列出带 Modes 的变量集合

(async () => { try { const collections = await figma.variables.getLocalVariableCollectionsAsync(); const result = collections.map(c => ({ id: c.id, name: c.name, modes: c.modes, // [{modeId, name}, ...] variableCount: c.variableIds.length, defaultModeId: c.defaultModeId })); figma.closePlugin(JSON.stringify({ collections: result })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })();

如何解读：确认是否已存在 primitive/semantic 分层，记录 mode 命名（是 "Light/Dark" 还是 "SDS Light/SDS Dark"？），通过变量数量判断系统规模——这直接决定采用 token-creation.md 中的简单模式（<50 tokens）、标准模式（50–200）还是 M3 高级模式（200+）。

列出某集合中的变量（名称、类型、scope、示例值）

(async () => { try { const collections = await figma.variables.getLocalVariableCollectionsAsync(); const targetName = "Color"; // change to the collection you want to inspect const coll = collections.find(c => c.name === targetName); if (!coll) { figma.closePlugin(JSON.stringify({ error: `Collection "${targetName}" not found` })); return; } const allVars = await figma.variables.getLocalVariablesAsync(); const vars = allVars.filter(v => v.variableCollectionId === coll.id); const result = vars.map(v => ({ id: v.id, name: v.name, resolvedType: v.resolvedType, scopes: v.scopes, codeSyntax: v.codeSyntax, // First mode value only, for a sample sampleValue: v.valuesByMode[coll.defaultModeId] })); figma.closePlugin(JSON.stringify({ collection: coll.name, variableCount: result.length, variables: result })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })();

如何解读：检查变量是否使用了ALL_SCOPES（违反最佳实践，应立即标记），检查命名约定（是否斜杠分层？），检查 code syntax 是否已设置，识别别名链（alias chains）。

列出带属性的组件集

(async () => { try { await figma.setCurrentPageAsync(figma.currentPage); // ensures page context const componentSets = figma.currentPage.findAll(n => n.type === 'COMPONENT_SET'); const result = componentSets.map(cs => ({ id: cs.id, name: cs.name, variantCount: cs.children.length, properties: Object.entries(cs.componentPropertyDefinitions).map(([key, def]) => ({ name: key, type: def.type, variantOptions: def.variantOptions || null, defaultValue: def.defaultValue })) })); figma.closePlugin(JSON.stringify({ componentSets: result, count: result.length })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })();

注意：要搜索所有页面，请遍历figma.root.children并对每个页面调用setCurrentPageAsync——这正是 inspectFileStructure.js 内部实现的做法，它还会额外捕获不在组件集内的独立组件（COMPONENT且父节点不是COMPONENT_SET）。

列出所有样式

(async () => { try { const [textStyles, effectStyles, paintStyles] = await Promise.all([ figma.getLocalTextStylesAsync(), figma.getLocalEffectStylesAsync(), figma.getLocalPaintStylesAsync() ]); figma.closePlugin(JSON.stringify({ textStyles: textStyles.map(s => ({ id: s.id, name: s.name, fontSize: s.fontSize, fontName: s.fontName })), effectStyles: effectStyles.map(s => ({ id: s.id, name: s.name, effectCount: s.effects.length })), paintStyles: paintStyles.map(s => ({ id: s.id, name: s.name })), counts: { text: textStyles.length, effect: effectStyles.length, paint: paintStyles.length } })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })();

检查既有组件上的命名约定

(async () => { try { // Replace with the node ID of an existing component to analyze const node = await figma.getNodeByIdAsync("YOUR_NODE_ID"); if (!node) { figma.closePlugin(JSON.stringify({ error: "Node not found" })); return; } // Check fills for variable bindings const fillInfo = []; if ('fills' in node && Array.isArray(node.fills)) { for (const fill of node.fills) { if (fill.type === 'SOLID' && fill.boundVariables?.color) { fillInfo.push({ type: 'variable_alias', id: fill.boundVariables.color.id }); } else if (fill.type === 'SOLID') { fillInfo.push({ type: 'hardcoded', r: fill.color.r, g: fill.color.g, b: fill.color.b }); } } } figma.closePlugin(JSON.stringify({ name: node.name, type: node.type, fills: fillInfo, pluginData: node.getPluginData('dsb_key') || null })); } catch(e) { figma.closePluginWithFailure(e.toString()); } })();

如何解读：该片段区分variable_alias（已绑定变量的填充，记录其变量 ID）与hardcoded（硬编码颜色值）——这是判断既有组件是否符合"视觉属性全部绑定变量"标准的直接证据。注意其中读取的dsb_key是 figma-generate-library 自身的 idempotency 标记键（详见 error-recovery.md），在发现阶段可用于识别本技能此前构建的节点。

3. 使用 search_design_system 建立复用基线

它搜索什么

search_design_system针对给定文件执行三路并行搜索，范围是已订阅的设计库：

1. Components—— 已发布的库组件，通过推荐引擎按名称/描述搜索（相关性排序，非精确匹配）
2. Variables—— 跨已订阅库的设计 Token（颜色、间距等）
3. Styles—— paint styles、text styles、effect styles

只有文件已订阅的库会被搜索。如果结果为空，说明该文件可能未订阅任何设计系统库。

输入参数

search_design_system({ query: "button", // required — text query fileKey: "abc123", // required — your file key includeComponents: true, // default true includeVariables: true, // default true includeStyles: true // default true })

返回值

{ "components": [ { "name": "Button", "libraryName": "Design System", "assetType": "component_set", "componentKey": "abc123def", "description": "Primary action button" } ], "variables": [ { "name": "colors/primary/500", "variableType": "COLOR", "variableSetKey": "set1key", "key": "var1key", "scopes": ["FILL_COLOR"], "variableCollectionName": "Colors" } ], "styles": [ { "name": "Heading/H1", "styleType": "TEXT", "key": "style1key" } ] }

如何解读结果

Components：componentKey可在use_figma中用于导入组件：

const component = await figma.importComponentByKeyAsync("abc123def"); // or for component sets: const componentSet = await figma.importComponentSetByKeyAsync("abc123def");

Variables：variableSetKey是 collection 的 key，key是变量的 key。用它们理解既有命名约定，以及有哪些 Token 可供别名（alias）引用。

Styles：key可直接配合figma.importStyleByKeyAsync(key)导入当前文件。

何时搜索

• Phase 0 步骤 0c：在规划任何内容之前进行宽泛搜索（query: "button"、query: "color"、query: "spacing"）。这确立了复用基线。
• 每个组件创建前一刻：在写任何use_figma创建代码之前，搜索具体的组件名。

复用决策：

本仓库 SKILL.md 第 5 节给出了同款决策矩阵的完整判定条件（API 匹配、Token 绑定模型兼容、命名约定一致、组件可编辑且不属于不归自己所有的远程库），并定义了总优先级：本地既有 → 已订阅库导入 → 新建。

4. 构建计划——在写入前锁定范围

完成代码库分析与 Figma 检视后，产出映射表并提交给用户。

Token → 变量映射表

为代码中找到的每个 Token 记录：

组件 → 组件集映射表

差距识别

对比代码中发现的内容与 Figma 中已存在的内容：

• 新建（New）：代码中存在但 Figma 中没有的 Token 或组件 → 创建
• 已存在（Existing）：Figma 中已有同名 Token 或组件 → 验证 scope / code syntax，跳过或更新
• 冲突（Conflict）：同名但值不同 → 升级给用户决策（见第 5 节）
• Figma 独有（Figma-only）：Figma 中存在但代码中没有 → 标记给用户，通常跳过

用户检查点消息模板

继续执行前必须呈现此消息。未获用户明确批准，绝不进入 Phase 1。

Here's what I found and what I plan to build: CODEBASE ANALYSIS Colors: {N} primitives ({families}), {M} semantic tokens ({light/dark if applicable}) Spacing: {N} tokens ({range}) Typography: {N} text styles, {M} individual scale tokens Shadows: {N} levels → will become Effect Styles Components: {list of component names} EXISTING FIGMA FILE Collections: {N} existing collections Variables: {M} existing variables Styles: {K} text, {L} effect, {J} paint styles Components: {list} PLAN New collections: {list with mode counts} New variables: ~{N} ({breakdown by collection}) New styles: {N} text, {M} effect New components: {list} Libraries to search before each component: {list} GAPS / CONFLICTS NEEDING DECISIONS ⚠ {conflict description} — Code says X, Figma already has Y. Which wins? WHAT I WON'T BUILD (and why) - {item}: already exists in Figma with matching conventions - {item}: not supported as a Figma variable (e.g. z-index, animation timing) Shall I proceed?

检查点机制是整个工作流的硬性要求。SKILL.md 明确列出 7 个强制检查点（发现+范围锁定、基础层、文件结构、每个组件、每个冲突、最终 QA），并特别强调："looks good" 不构成对下一阶段的批准——在检查点处必须明确说出下一阶段名称。

5. 冲突解决——当代码与 Figma 意见不一致时

当同一 Token/组件在代码和 Figma 中同时存在但值、名称或结构不同时，务必询问用户。绝不静默选择一方。

决策框架

代码胜出（Code Wins）

默认以代码为真值来源的情况：

• Hex 值（代码是线上生产值）
• Token 命名（CSS 变量名会成为 code syntax）
• Mode 值（light/dark 划分来自代码）

Figma 胜出（Figma Wins）

默认以 Figma 为真值来源的情况：

• Collection 架构（如果已存在结构良好的系统，扩展它而非替换它）
• 变量命名层级（如果设计师已经在用特定名称使用该系统）
• 页面结构（匹配既有页面组织模式）

两者都不占优：协商

当任何一方都不明显正确时，提出解决方案并询问：

"我建议 [方案]。这样代码 Token 名称和 Figma 命名约定都能保留。可以吗？"

冲突解决后的落地要点

从仓库实现角度看，冲突解决结论应同步反映在 naming-conventions.md 的并行标识系统规则中：Figma 名称与代码标识（code syntax、Code Connect source path）是两个平行体系，冲突的常见化解方式就是"Figma 保留人类可读名称 + code syntax 携带精确 CSS 名称"。此外，整个冲突决策过程应记录进状态账本（state ledger），配合 rehydrateState.js 与 error-recovery.md 中基于dsb_run_id/dsb_key的标记体系，保证长工作流中断后可按{key → nodeId}映射重建现场、幂等续跑。

结语：为什么发现阶段值得认真对待

discovery-phase.md 反复强调一个核心主张：设计系统构建绝非一次性任务，而发现阶段是唯一保证后续 20–100+ 次写入调用不跑偏的前置投资。代码库分析回答"有什么"，Figma 检视回答"已有什么"，search_design_system回答"能复用什么"，映射表回答"要建什么"，冲突解决回答"谁说了算"。只有这五步全部完成并经过用户检查点批准，才轮到 token-creation.md（Phase 1）和 component-creation.md（Phase 3）登场。把 Phase 0 做扎实，后续的变量绑定、变体矩阵与文档页创建才能建立在可验证、可恢复的确定性之上。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills