Generate Design System

使用设计系统

Claude使用Figma设计系统的技能——一个地方有两种模式： 检查 （只读审计，包括WCAG检查、组件评分、移交文件）以及 构建 （创建组件、固定基础、添加插槽、编写描述）。构建模式可选择扩展到 第6阶段（与代码同步） --生成 tokens.css，审计脚本和代码库的AI规则文件。

与Claude Code、Cursor和Codex配合使用。

v2.0中的新功能

这是一个重大的发布。这项技能以前被称为 generate-design-system 只负责建筑。现在它涵盖了整个生命周期：检查现有文件，决定构建或修复什么，可选地导出到代码。在检查和构建之间，该技能总是会暂停，等待您的决定。默认情况下，第6阶段为关闭状态，仅在明确请求时触发。

从v1.x迁移： 迁移说明请参见CHANGELOG。回购URL已更改，但旧链接会自动重定向。

亮点：

• 两种模式 --检查（只读）和构建（写入），两者之间必须暂停
• 第6阶段——与代码同步（可选，默认关闭） --生成 tokens.css 具有三层间接性、AI规则文件（克劳德代码/光标/代码）和CI就绪审计脚本。关闭设计到代码循环。
• 插槽支持 对于复合组件（卡片、模态、对话框）--替换分离模式
• 强制性结构化组件描述 --Figma MCP将它们作为上下文传递给代理
• 六个审计模块 --令牌合规性（具有严重性级别）、交互状态、WCAG可访问性、分离实例、命名质量、组件描述
• 加权战备评分 --对每个组件进行0-100的评分（错误权重为1.0，警告权重为0.3）
• 三种导出格式 --markdown、JSON、AI代码生成提示
• 图案指南 --如何在Figma中记录组合模式（并可选择将其作为规范文件导出到repo）
• 故事到变体奇偶校验 当代码库有故事书时
• 自动重命名建议 当通用图层名称超过20%时

它做什么

该技能会自动从您的请求中检测模式（或在不清楚时询问）。

检查模式 --只读。运行审核模块：

• 模块1——代币合规性。 可变绑定覆盖范围。错误：未绑定填充、笔划、填充、间隙、角半径。警告：原始不透明度、模糊半径、动画持续时间。没有单独标记文本样式的文本节点。
• 模块2——交互状态。 将变量与每个组件类型的预期状态矩阵进行比较。缺少状态（按下按钮、输入错误），并列出完整的预期设置。
• 模块3——可访问性。 计算WCAG 2.1 AA检查。颜色对比度（正常4.5:1，大3:1）。触摸目标（交互式最小44×44px）。字体大小警告\<12px，错误\<10px。焦点指示器存在。
• 模块4——分离实例。 扫描所有页面，查找与组件名称匹配但与实例不匹配的帧。带有页面、父路径和节点ID的报告。
• 模块5——命名质量。 在组件内标记通用的Figma自动名称（第47帧，矩形3）。
• 模块6——组件描述。 为每个组件生成结构化文档（目的、行为、组成、用途、代码注释）。使用推理而不是计算。

评分公式：

Score = (tokens_errors × 2 + tokens_warnings × 0.6 + states × 3 + accessibility × 1 + naming × 0.5) / 7.1 × 100

状态覆盖权重最大，因为缺失的状态会导致生成代码中最下游的破坏。

检查后，该技能总是会暂停报告，并在做出任何更改之前等待您的决定。

生成模式 --写。六阶段工作流程（第6阶段可选）：

• 第一阶段——发现。 分析代码库或从头开始收集规范。接受.md品牌指南、.json令牌（W3C DTCG、tokens Studio）、屏幕截图、URL。如果文件存在，则运行快速健康检查（不是完全审计——为此，请使用检查模式）。建议路径：就地构建、新文件、混合、仅导出代码。
• 第二阶段——基础。 变量集合（基于3层或平面域——两者都支持）。亮/暗模式（和多品牌）。文本样式、效果样式。设置代码语法。WEB每个变量。当基础存在并通过健康检查时跳过。
• 阶段3——文件结构。 标准页面：封面、入门、基础、每个组件组一个、模式（可选）、实用程序。可重用的页面标题组件。组件页面使用固定宽度（996像素）的包装。当不需要文档页面时跳过。
• 第4阶段——组件。 建议核心10，你确认。对于原子（按钮、输入、复选框）、具有所有状态的完整变量矩阵、自动布局、变量绑定、TEXT属性。对于复合（卡片、模态、对话框），运行插槽决策——命名插槽替换分离模式。为每个公共组件编写结构化描述。在每个组件之后进行验证。可选的阶段4d记录组合模式。
• 第5阶段——质量保证。 验证脚本检查缺少的集合、ALL_SCOPES违规、硬编码填充、缺少自动布局、亮/暗覆盖、缺少描述、缺少插槽决策。构建测试页面以验证可组合性。以可选的第6阶段提示关闭。
• 第6阶段——与代码同步（可选，默认关闭）。 生成 tokens.css 三层间接（上游→ 带有回退功能的项目别名→ 组件引用别名）、CI就绪的Node.js审计脚本和AI规则文件(.claude/rules/design-system.md, .cursor/rules/design-system.mdc，或 AGENTS.md 部分）。浅色/深色过孔 [data-theme], @media (prefers-color-scheme)或两者皆有。仅在明确的用户请求时触发。

技能在阶段之间暂停，以便您进行复习。

文件结构

work-with-design-systems/
├── SKILL.md                              # Core instructions
├── README.md
├── CHANGELOG.md
├── LICENSE
│
├── references/
│   ├── inspect/                          # Inspect mode reference docs
│   │   ├── overview.md
│   │   ├── token-compliance.md
│   │   ├── interactive-states.md
│   │   ├── accessibility.md
│   │   ├── detached-instances.md
│   │   ├── naming-quality.md
│   │   ├── component-descriptions.md
│   │   ├── readiness-scoring.md
│   │   └── report-templates.md
│   │
│   └── build/                            # Build mode reference docs
│       ├── token-taxonomy.md
│       ├── component-spec.md
│       ├── naming-conventions.md
│       ├── framework-mappings.md
│       ├── slots-guide.md
│       ├── component-description-template.md
│       ├── patterns-guide.md             # Composition patterns in Figma
│       └── code-export.md                # Phase 6 — tokens.css, audit, AI rules
│
├── scripts/
│   ├── inspect/                          # Inspect mode scripts (read-only)
│   │   ├── inventory.js
│   │   ├── audit-tokens.js               # With severity tiers
│   │   ├── audit-states.js
│   │   ├── audit-accessibility.js
│   │   ├── audit-detached.js
│   │   └── audit-naming.js
│   │
│   └── build/                            # Build mode scripts (write)
│       ├── validate-design-system.js     # Final QA validation
│       ├── exportTokensToCSS.js          # Phase 6a — read variables for export
│       └── fixHardcodedToTokens.js       # Fuzzy auto-fix for inspect → build flow
│
└── assets/
    └── file-structure-template.md

参考和脚本文件按需加载。检查模式负载 references/inspect/ 和 scripts/inspect/.构建模式负载 references/build/ 和 scripts/build/第6阶段具体加载 code-export.md 和 exportTokensToCSS.jsSKILL.md中的关键规则适用于所有模式。

安装

克劳德代码

# Copy into your project
cp -r work-with-design-systems/ .claude/skills/work-with-design-systems/

# Or install globally (available across all projects)
cp -r work-with-design-systems/ ~/.claude/skills/work-with-design-systems/

# Or clone directly
git clone https://github.com/natdexterra/work-with-design-systems.git .claude/skills/work-with-design-systems

然后调用 /work-with-design-systems 在Claude Code聊天中。

光标

cp -r work-with-design-systems/ .cursor/skills/work-with-design-systems/

法典

cp -r work-with-design-systems/ skills/work-with-design-systems/

兼容性

技能是一组Markdown和JavaScript文件，不依赖于任何特定的IDE。已确认与以下人员合作：

• 克劳德码（终端和VS码扩展）
• 光标
• 法典

第6阶段（同步到代码）需要文件写入权限。可在Claude Code、Cursor、Codex和类似的MCP客户端中使用文件工具。当从Claude.ai web/mobile运行时，Phase 6会内联输出文件内容以供手动保存。

先决条件

• Figma MCP服务器 已连接（建议使用远程服务器）
• 这 figma-use 已安装技能（附带Claude Code和Cursor的Figma插件）

用法

检查——全面审核

/work-with-design-systems

Audit my design system file for quality issues.

该技能清点文件，运行所有六个模块，生成完整的报告，然后停止并等待您的决定。

检查——范围狭窄

/work-with-design-systems

Check WCAG compliance on Button and Input only.

只有模块3在指定的组件上运行。

检查——移交前文件

/work-with-design-systems

Generate component documentation for developer handoff.

模块1和6运行。输出：markdown+JSON捆绑包，带有结构化组件规范。

从头开始构建

/work-with-design-systems

Create a design system for a fintech product.
Brand color: #6366F1 (indigo). Font: Inter.
Need Light and Dark modes.

构建模式，完整构建路径。要求在建造前确认颜色、间距、组件清单。

你可以喂它 .md 品牌指南或 .json 令牌（W3C DTCG，令牌工作室）而不是键入规范。

构建——基于现有代码库

/work-with-design-systems

Sync our component library to Figma.
Tokens: tailwind.config.ts
Components: src/components/ui/

读取令牌文件和组件道具，映射到Figma变量和组件变体。阅读故事书故事（如果有的话）。

构建--扩展现有文件

/work-with-design-systems

Variables and text styles are set up in [Figma file URL].
Need to build 7 components with proper bindings.

对变量进行健康检查，然后构建组件——无需重新创建基础。

构建--向现有组件添加插槽

/work-with-design-systems

Our Card component keeps getting detached because users need different inner content.
Add slots to it.

读取当前卡结构，根据分离模式建议插槽位置，并就地更新。现有实例继续工作。不提供第6阶段（改造范围）。

构建——端到端，代码导出

/work-with-design-systems

Create a design system for fintech app, indigo primary, Inter, Light+Dark —
and generate tokens.css and CLAUDE.md when done.

完整的构建路径通过第5阶段，然后直接进入第6阶段（因为用户提前选择了）。输出 tokens.css 具有三层间接性， .claude/rules/design-system.md 具有组件列表和令牌引用， scripts/token-audit.js 对于CI。

仅代码导出

/work-with-design-systems

My Figma DS is solid. Just generate tokens.css and CLAUDE.md for my repo.

1c阶段变量健康检查。如果基础有效（范围已设置，codeSyntax已存在），则跳过阶段2-5并直接运行阶段6。如果基础损坏，拒绝并建议先修复。

检查→ 构建（最常见）

/work-with-design-systems

I have a 6-month-old Figma file. Need to figure out what's broken and fix what's worth fixing.

先运行检查，提交报告，暂停以决定要修复什么。然后根据您的范围指令进入构建模式。

支持的框架

references/build/framework-mappings.md 包含以下令牌提取模式：

• React+顺风CSS（包括shadcn/ui和 cva)
• React+CSS模块/样式化组件
• 使用任何CSS方法的Vue 2/3
• 斯维尔特
• Angular
• W3C设计令牌（DTCG JSON格式）
• 代币工作室格式

对于不受支持的设置，该技能可以追溯到手动收集规格。

支持的输入

从头开始时：

第6阶段输出

当第6阶段运行时，您将获得：

审计脚本将错误（硬编码颜色、原始间距、原始半径）与警告（原始过渡持续时间、z索引值）分开标记。CI管道在出现错误时退出，但允许发出警告。

设计决策

为什么一种技能有两种模式？ 一个常见的工作流程是检查→ 决定→ 建造。分成两种技能意味着在会话之间手动切换和打破上下文。一种具有显式模式的技能可以保留流程，同时仍然在检查中强制执行只读安全。

为什么在检查和构建之间必须暂停？ 检查模式的值是生成一个可以操作的报告。自动链接构建违背了目的——你永远不会看到报告。暂停是核心保证。

为什么默认情况下关闭第6阶段？ 第6阶段在Figma之外写入文件。这与其他技能的范围不同。在每次构建时自动运行它将是侵入性的，并且会破坏改装场景（插槽改装不应重新生成 tokens.css 并覆盖用户的审计脚本）。QA结束时的默认报价为用户提供了选择加入的机会，而无需强制。

为什么在tokens.css中采用三层间接？ 第1层包含上游设计系统令牌（Atlaskit、Material、Carbon——如果使用的话）。第2层包含引用第1层的项目别名，其中原始值作为回退(var(--ds-text, #292A2E)).组件仅参考第2层。如果上游重命名令牌，则修复一个别名。如果上游无法到达，回退将保持项目运行。

为什么有范围的AI规则路径？ 顶层 CLAUDE.md, AGENTS.md，并且已满 .cursor/rules 是用户管理的文件，通常包含项目的自定义说明。覆盖它们是破坏性的。范围路径(.claude/rules/design-system.md等）与其他规则共存，不要冲突。

为什么要加权评分？ 缺少“按下”状态的按钮比通用层名称更严重地破坏了用户交互。状态差距得分×3，令牌错误×2，可访问性×1，命名×0.5。令牌警告得分×0.6（小于错误但不为零）。

为什么插槽过度分离？ 分离的框架在结构上对代理和检查模式是不可见的。插槽为可变内容提供了明确的dropzone，同时保持了组件的完整性。Figma在2026年3月专门为此添加了插槽。

为什么是强制性描述？ Figma MCP读取组件描述并将其作为上下文传递给消费代理。没有描述的组件迫使代理根据视觉结构猜测一切。描述是您可以添加到AI质量设计系统中的唯一最高杠杆。

为什么使用三层代币？ 原始值保存原始值。语义标记别名原语并承载意义(color/bg/primary 而不是 color/blue-500).组件仅绑定到语义。切换亮/暗需要零组件更改——您交换语义层。对于单一品牌或重建，基于平面域的集合（颜色、间距、半径）同样有效。技能支持两者。

为什么要显式变量作用域？ 默认的ALL_SCOPES会污染每个属性选择器。颜色选择器中显示的间距变量令人困惑。

为什么要在违约前声明？ 大多数不完整的设计系统都有一个“快乐之路”按钮，忘记了禁用、错误、加载。组件规范要求所有州提前提交。

为什么每个变量都有codeSyntax？ 没有 codeSyntax.WEB，代理人使用 get_design_context 获取原始的Figma变量名，而不是CSS标记名。将其设置为创作意味着从第一天开始对桥梁工程进行编码设计。第6阶段也依赖于codeSyntax——没有它，审计拒绝运行。

为什么选择TEXT组件属性？ 如果没有它们，将按钮标签从“标签”更改为“提交”会在组件更新时恢复。TEXT属性 componentPropertyReferences 保留覆盖。

为什么使用固定宽度的页面包装？ 如果没有固定宽度（996像素），像Toggle这样的小组件会产生窄页面（350像素），而大组件会产生宽页面。固定宽度使所有组件页面在视觉上保持一致。

为什么选择灵活的组件列表？ 真正的设计系统很少与通用的“核心10”相匹配。金融科技DS可能需要日期选择器和步进器，但不需要阿凡达。该技能建议默认值，但会根据实际库存进行调整。

为什么要将inspect/build拆分到子文件夹中？ 大型参考文件不需要一次加载。检查模式读数 references/inspect/ 只有。构建模式读取 references/build/ 只有。第6阶段具体负载 code-export.mdSKILL.md中的关键规则适用于所有模式。

为什么这很重要：闭环Figma↔ 代码

该技能端到端地完成了设计到代码的循环。Figma方面：组件、令牌、插槽、描述都结构正确 get_design_context 返回干净的CSS令牌名称。代码端（第6阶段）： tokens.css 通过三层间接方式精确地镜像Figma，AI规则告诉IDE中的代理存在哪些令牌以及在哪里查找组件规范，审计脚本会发现偏差。AI代理通过MCP读取设计并在IDE中编写代码，这两种方式都会选择相同的令牌。没有捏造，没有会话之间的漂移。

定制

分叉并适应。常见变化：

• 不同的核心组件： 编辑SKILL.md阶段4a中的列表，并将规格添加到 references/build/component-spec.md
• 不同的间距比例： 在中编辑默认值 references/build/token-taxonomy.md
• 公司特定名称： 编辑 references/build/naming-conventions.md
• 附加审计检查： 将新模块添加到 references/inspect/ 并将脚本与 scripts/inspect/.更新SKILL.md检查工作流程。
• 单一框架： 从中删除不相关的部分 references/build/framework-mappings.md
• 不同的第6阶段输出路径： 在中编辑默认值 references/build/code-export.md

相关技能

资源

• Figma：为MCP服务器创建技能
• Figma：MCP技能
• 设计系统中的Figma槽（Nathan Curtis）
• 如何在Figma中构建设计系统（2026）
• 将你的设计系统暴露给LLM（Hardik Pandya） --第六阶段建筑的灵感

许可证

麻省理工学院——见 许可证.