figma-extract-design-system

figma-extract-design-system — 生产应用 → 设计系统

组织可以让小型团队借助 AI 快速编写产品代码。产品能用，但缺少底层设计系统，因此无法保持一致、复用或版本管理。此技能负责执行提取流程：应用 → 组件清单 → DTCG 令牌 → Storybook 包 →（可选）Figma。

有两个合理的停止点：

• 代码主导型组织：在 Storybook 包阶段停止。它将成为经过版本管理的事实来源，打包后重新导入到产品中。
• 设计主导型组织：继续进入 Figma，将令牌转换为变量（figma_import_tokens），并将关键组件转换为 Figma 组件集。

工具模式

• 首选 — 已连接 figma-console-mcp（本地模式）： 使用五个 figma_ds_* 工具。这些工具执行确定、范围明确，并会在 <outDir>/.extraction/ 下保存清单，让提取工作可跨会话继续。
• 备用 — 未连接 console MCP： 使用 Read/Grep/Bash 自行完成相同阶段（速度较慢，确定性较低）。保留相同产物：自行编写的 analysis.json、DTCG tokens/tokens.json，以及相同的包目录结构。Figma 往返流程使用 figma-import-tokens 技能（官方 Figma MCP use_figma）。

阶段 0 — 探索（先沟通）

扫描之前，先与用户确认：

1. 目标应用路径 — 绝对路径。多个应用是优势：真正的设计系统是这些产品的交集。
2. 代码主导还是设计主导？ 这决定是否执行阶段 6（Figma）。
3. 品牌／命名背景 — 产品名称，以及现有品牌颜色名称（如有）。语义命名环节需要这些信息。
4. 设计系统的存放位置 — 默认是 <first app>/design-system，也可以是 monorepo 中的独立目录。

阶段 1 — 分析

figma_ds_analyze { targets: ["/abs/path/app"], outDir: "/abs/path/app/design-system" }

在继续之前，与用户一起审阅摘要——尤其是**architecture 块**，它决定了设计系统与 UI 套件的区别：

• specializations 是按用途命名的组件（FollowButton、ModerationMenu、NodeCard）——每个组件实际上都是一个通用组件（Button、Menu、Card）加上一种用途。用途让它成为“关注按钮”；组件本身只是一个按钮。
• missingPrimitives 是构建清单：应用中隐含存在、但从未创建的通用组件。
• levels 是原子设计的分类（原子/分子/有机体/模板）——这只是启发式分类；请与用户确认组织内部使用的术语。

**泛化流程（审阅之后、移植之前或期间）：**如果已连接 design-systems-assistant MCP，请以它为依据做出决策（使用 search_design_knowledge 查询命名惯例、组件 API 设计和原子层级——其中包含跨行业最佳实践）。然后：

1. 将商定的每个 missingPrimitive 构建为通用组件，并提供足够广泛的变体/属性 API，以涵盖观察到的专用组件。
2. 将每个专用组件重新表达为一个配方：可以是通用组件上的一个故事（Button → Recipes/Follow），也可以是 recipes/ 层中的轻量包装器——绝不能作为同级基础组件。产品保留自己的关注按钮；系统提供 Button。
3. 按选定的层级组织 Storybook（例如 Primitives/、Components/、Patterns/），而不是使用一个扁平的 Components/ 列表。
4. 并非所有专用组件都应合并——方位限定组件（LeftNav）或真正的一次性有机体（ThreadCanvas）可以保留；报告负责提出建议，由用户决定取舍。

另外也请审阅以下经典项目：

• 分类很重要。 vendored（shadcn 风格的复制源码）和 bespoke 按原样移植；wrapped 移植时保留供应商包作为同级依赖；pure-vendor（直接使用 MUI/Chakra）不予移植——通过主题/令牌和使用文档来体现。
• duplicateGroups 是氛围编码的典型迹象（三个 Button.tsx 文件）。与用户一起确定每组中应采用的规范版本；将其余版本标记为 skipped，并在 figma_ds_status 中添加备注。
• 移植顺序 = 工具的使用排名（topByUsage）。未经询问，不要移植无人使用的长尾组件。

阶段 2 — 提取令牌

figma_ds_extract_tokens { outDir, formats: [...match the app's styling method...] }

• declared 令牌（CSS 变量、@theme、SCSS 变量、tailwind 主题、shadcn HSL 三元组）保留其名称并携带 sources 溯源信息。.dark / [data-theme=dark] 的值会转换为真正的浅色/深色多模式结构。
• inferred 令牌是根据出现频率提升的原始值——请与用户一起审阅；belowThreshold 列表值得快速浏览，以查找接近阈值但未达标的项目。

**语义命名流程（这是你的工作，不是工具的）：**结构化名称（color/blue/500、color/extracted/hex-22c55e）虽然正确，但还不能直接交付。根据用户提供的品牌背景，通过编辑 tokens/tokens.json 添加语义别名令牌（color/primary → {color.blue.500}）——将其添加到 Semantic 组，使用 {dot.path} 别名引用基础令牌，绝不要删除基础令牌。仅当代码库发生变化时才重新运行 figma_ds_extract_tokens（它会重新生成内容；对生成投影文件的手动编辑会丢失，而对 tokens.json 的编辑是脚手架构建的输入）。

阶段 3 — 搭建脚手架 + Storybook

figma_ds_scaffold { outDir, packageName: "@org/design-system" }
cd <outDir> && npm install && npm create storybook@latest -- --yes --no-dev
figma_ds_setup_storybook { outDir }    # AFTER init — wires the workshop to the extraction

figma_ds_setup_storybook 会生成 .storybook/preview.css（提取的令牌以及源应用的 @theme 映射、@utility 定义、@layer base 和 @font-face 规则，以便忠实呈现生产环境中的类名和字体），复制可自托管的字体，并修补 main.js（tailwind vite 插件 + 自动 JSX 运行时）和 preview.jsx（根据提取出的模式名称设置主题工具栏/装饰器）。执行它返回的任何 manualSteps，然后重启开发服务器。请确认 .storybook/main 中的故事文件 glob 包含 src/**/*.mdx——生成的 src/docs/*.mdx 页面用于展示令牌/排版/图标设计。

阶段 4 — 移植组件（循环）

按使用频次排序，对每个组件执行：

1. figma_ds_extract_component { outDir, component: "Button" } — 提供源码、本地导入闭包、属性约定、观察到的调用点变体、样式关联点以及 CSF3 故事脚手架。
2. 移植到 <outDir>/src/components/<Name>/ — 每个组件都有自己的目录、组件文件、故事文件和 index（绝不使用单体文件）。解耦特定于应用的导入（路由、数据获取、全局状态）；将硬编码值替换为设计令牌（对照 tokens.json 检查 styleTouchpoints.customProperties）。
3. 调整故事脚手架 — 每个实际变体（observedProps）对应一个故事，设置 tags: ['autodocs']。
4. 在 Storybook 中进行视觉验证（浏览器），确认无误后再完成。
5. figma_ds_status { outDir, update: { component, status: "ported", storyFile } }。

长期协作：在会话开始时运行 figma_ds_status { outDir }，即可准确了解上次进度。

阶段 5 — 以代码为主的停靠点

构建可构建、带版本的包：组件 + 设计令牌 + Storybook。根据组织使用的方式设置发布和版本管理（changesets、私有注册表）。之后，各个产品便可使用 @org/design-system，而非各自的本地副本 — 这项迁移属于单独的协作任务。

阶段 6 — 以设计为主：导入 Figma

1. 设计令牌 → 变量： 使用 tokens/tokens.json 运行 figma_import_tokens（顶层分组会变成集合；Light/Dark 模式也会一并导入）。先使用 strategy: "dry-run" 预览。
2. 组件 → Figma： 使用现有工具（figma_create_component_set、figma_execute）或 figma-generate-library / prototype-to-figma 工作流，将关键组件重建为组件集 — 将填充、描边和圆角绑定到已导入的变量，让 Figma 和代码共用同一设计令牌来源。
3. 此后，同步循环为 figma_export_tokens / figma_import_tokens，并采用感知差异的合并方式。

边界与注意事项

• figma_ds_* 工具仅支持 Local Mode（它们会读写本地文件系统）。
• 提取过程不会修改目标应用 — 所有内容都会放在 outDir 下。
• 始终使用绝对路径：MCP 服务的工作目录不是项目目录。
• 不要手动编辑生成的投影文件（tokens.css、theme.css 等）；请编辑 tokens.json（或源应用），然后重新生成。
• 每个设计令牌的来源信息都保存在 $extensions["figma-console-mcp.extraction"] 中 — 可用它向用户说明决策依据（“这是主要设计令牌，因为它出现了 214 次”）。