AI设计系统技能：一键生成可执行设计规范，统一多助手编码风格-编程实验室

1. 项目概述：一个为AI编码助手打造的“设计系统”技能

如果你和我一样，每天都要和Claude Code、Cursor、GitHub Copilot这些AI编码助手打交道，那你肯定也遇到过这个痛点：每次新建一个项目，或者让AI帮你写UI组件时，你都得花大量时间反复描述你的设计规范——“按钮用这个蓝色”、“标题用这个字体大小”、“间距要8的倍数”。更头疼的是，不同的AI助手之间、甚至同一个助手的不同会话之间，这些规则都无法继承，导致生成的代码风格割裂，后期维护成本极高。

今天要聊的这个项目，Jaywalker-not-a-whitewalker/DesignSystem，就是专门为解决这个问题而生的。它本质上是一个“技能”（Skill），可以安装到主流的AI编码助手中。一旦安装，你只需要在项目里说一句new project、create design system或者/design，它就会启动一个引导式的6步流程，帮你为当前项目生成一套完整、可执行的设计系统文档Design.md。最关键的是，它会自动在所有支持的AI助手（如Claude Code、Cursor、Antigravity等）中植入“钩子”，确保此后任何AI在编写UI代码前，都会先加载并遵循你这套设计规则。

这解决了几个核心问题：第一，设计一致性，所有组件都基于同一套Token（设计变量）生成；第二，开发效率，无需重复沟通设计约束；第三，团队协作，把设计规范变成机器可读、可执行的“单一事实来源”（Single Source of Truth），所有开发者的AI助手都同步遵守。无论你是独立开发者，还是前端团队负责人，这个工具都能显著提升从设计到代码的转化效率和一致性。

2. 核心设计理念与工作流程拆解

这个设计系统技能的核心思想，是将主观、模糊的“设计感觉”转化为客观、可审计的“设计规则”，并让AI成为这些规则的强制执行者。它不仅仅是一套静态的样式指南，而是一个动态的、与开发流程深度集成的治理体系。

2.1 “应用类型驱动设计”的核心理念

与许多从视觉风格入手的工具不同，这个技能采用了“应用类型驱动设计”（App-Type-Driven Design）的方法。在它的6步引导流程中，“应用类型”的优先级高于“技术框架”。这意味着，设计决策的首要依据是你的应用是做什么的（例如，是一个SaaS仪表盘、一个社交应用，还是一个营销落地页），而不是用什么技术栈构建的。

为什么这个顺序如此重要？因为不同应用类型有其固有的设计模式和用户心智模型。一个金融仪表盘需要清晰的数据层级和严肃的信任感，其设计规则（如色彩克制、高信息密度）与一个创意作品集网站（可能强调视觉冲击和个性表达）截然不同。技能内部预设了针对不同应用类型的设计启发式规则（Heuristics），比如：

SaaS仪表盘：会强制推行严格的8pt间距网格、高对比度的表面（Surface）隔离、限制装饰性色彩的使用，以确保复杂信息下的可读性和操作效率。
社交应用：可能会允许更活泼的色彩组合、更灵活的卡片圆角，并强调动态反馈（Motion）规则，以营造互动感和社区氛围。
营销落地页：则会侧重于建立清晰的视觉层次（一个主行动号召）、大尺寸的展示性字体，并可能禁止大段的居中对齐正文，以优化阅读动线和转化率。

通过先确定“应用类型”，技能就能调用最合适的基础设计规则模板，后续的色彩、字体选择都是在这个约束框架内进行的优化，从而保证了设计决策始终服务于产品目标，而非个人审美偏好。

2.2 六步引导式流程深度解析

整个系统的生成始于一次性的、交互式的6步引导流程。每一步都旨在捕获最关键的设计决策输入：

形态因素（Form Factor）：选择网站、移动应用、可穿戴设备或桌面应用。这决定了基础的字号范围、触摸目标大小（如移动端最小44px）、以及响应式断点的预设策略。
应用类型（App Type）：如上所述，这是设计的“宪法”。选择后，一系列默认规则（如间距网格严格度、色彩饱和度范围、组件原子层级）就被锁定了。
框架/平台（Framework / Platform）：选择React/Next.js、Flutter、SwiftUI等。这一步仅影响最终的代码输出格式（如生成tailwind.config.js还是Flutter的ThemeData），而不会影响设计规则本身。这体现了“设计规则与实现分离”的思想。
应用身份（App Identity）：填写应用名称、目标用户、核心操作和三个“氛围词”（如“专业、高效、可信赖”）。氛围词会被转化为具体的设计属性，例如“温暖”可能对应较低的色彩对比度和圆润的字体，“现代”则对应高对比度和几何感强的无衬线字体。
视觉参考（Visual Reference）：这是可选但价值极高的一步。你可以提供一个Logo的URL、一张截图，或者说“感觉像[某个知名应用]”。技能会使用视觉算法分析参考图像，提取主色、辅助色、字体风格（如有）等，作为生成调色板和字体建议的强信号输入，极大地加速了设计方向的对齐。
色彩方向（Color Direction）：基于上一步的输入，技能会提供几套AI生成的调色板选项供你选择，也支持手动输入。这里的一个关键技术点是，它使用OKLCH色彩空间来生成颜色。相比传统的RGB或HSL，OKLCH在感知上更均匀，能生成在视觉上亮度、饱和度更协调的颜色系列，并且能更好地处理广色域（P3）。

完成这六步后，技能并不是简单地把你的回答拼凑成一个文档。它的核心引擎开始工作：首先，基于所有输入，生成唯一的“事实来源”——design-tokens.json。这个JSON文件包含了所有颜色、字体、间距、圆角、动效时长等原始Token。然后，以这个JSON文件为数据源，渲染生成人类可读的Design.md文档，以及针对你所选技术栈的配置文件（如Tailwind配置）。

3. 设计系统的核心构成与规则详解

生成的Design.md是一个结构严谨、内容丰富的设计宪法。我们来逐一拆解它的核心模块，以及背后强制执行的设计规则。

3.1 设计令牌：单一事实来源

design-tokens.json是这个系统的基石。它采用了一种层级化的结构来定义Token，例如：

{ "color": { "primary": { "50": "oklch(0.97 0.02 250)", "500": "oklch(0.55 0.22 250)", "900": "oklch(0.15 0.18 250)" }, "surface": { "DEFAULT": "oklch(0.99 0 0)", "subtle": "oklch(0.96 0.01 0)" } }, "spacing": { "1": "0.5rem", // 4px "2": "1rem", // 8px "3": "1.5rem", // 12px "4": "2rem" // 16px } }

所有UI代码中引用的都必须是这些Token名（如var(--color-primary-500)或spacing.4），绝对禁止硬编码任何具体的色值、尺寸或字体。这条规则通过后续的审计功能来强制执行。

3.2 视觉层次与隔离规则

这是保证界面清晰、易读的关键约束，也是新手设计师最容易犯错的地方。

区域隔离规则：规定任何两个相邻的内容区块（Section）之间，必须使用且仅能使用以下五种方式之一进行视觉隔离：1）表面色阶变化（如从白色背景切换到浅灰色背景）；2）留白（通常是较大的间距）；3）分割线；4）边框；5）色块填充。严禁将两个相同表面、没有任何隔离的元素直接堆叠在一起。这条规则强制开发者思考区块之间的关系，避免了界面变成一堵“信息墙”。
视觉层次规则：
- 一个主要行动：在任何给定的视图（View）中，只允许存在一个最高优先级的行动号召按钮（通常使用主色），避免用户决策瘫痪。
- 三级文本流：文本颜色必须严格遵循三个层级：--color-text-primary（正文）、--color-text-muted（次要信息）、--color-text-faint（禁用状态、标签）。这确保了信息的轻重缓急一目了然。
- 强调色克制：强调色（Accent Color，通常来自主色系）只能用于可交互元素的激活状态、链接和最重要的按钮，绝不能用于装饰性元素，如无关紧要的图标颜色或背景点缀。

3.3 原子化组件架构与8pt间距网格

原子化设计层级：强制推行从“原子”（Atoms，如按钮、输入框）到“分子”（Molecules，如搜索框=输入框+按钮）再到“有机体”（Organisms，如导航栏、卡片列表）的构建方式。规则禁止在“分子”或“有机体”内部直接硬编码样式，所有样式必须通过组合更基础的原子或引用设计Token来实现。这保证了组件的可复用性和一致性。
严格的8pt间距网格：这是最具约束力也最有效的规则之一。它规定所有margin、padding、gap的值必须是8像素的整数倍（8, 16, 24, 32...）。像padding: 12px或margin-top: 37px这样的值会被审计标记为违规。为什么是8？因为8是大多数屏幕的物理像素与CSS逻辑像素换算后的一个公约数，遵循它能使元素在各种设备上对齐得更清晰，减少亚像素渲染带来的模糊问题。这条规则通过强制使用有限的、成比例的间距值，极大地提升了界面的节奏感和专业度。

3.4 无障碍访问与反模式拦截

WCAG AA对比度强制合规：所有文本与其背景的对比度必须达到WCAG AA标准（普通文本4.5:1，大号文本3:1）。技能在生成颜色Token时就会进行计算和校验，确保基础配色方案是可达的。审计功能也会扫描现有代码，找出对比度不足的组合。
反模式拦截清单：技能内置了一个“黑名单”，会阻止AI生成某些被普遍认为不佳的设计模式，例如：
- 渐变背景（容易分散注意力且难以保证文字可读性）。
- 带颜色的卡片边框（通常用表面色差隔离是更优雅的方式）。
- 完全相同的三栏功能网格（缺乏视觉焦点）。
- 大段正文的居中对齐（不利于长文阅读）。
- 由AI生成的、空洞无物的“英雄区域”文案。

4. 多AI助手集成与自动化工作流实现

这个技能最强大的地方在于它的“一次配置，处处生效”的自动化集成能力。它通过向项目目录写入特定的配置文件（“钩子”），来“劫持”不同AI助手的工作流程。

4.1 钩子文件的生成与作用机制

在运行/design命令并生成Design.md后，技能会根据检测到的环境，在项目根目录创建以下一个或多个文件：

AGENTS.md: 这是一个通用钩子文件，内容类似于“本项目使用以下设计系统：[Design.md的内容摘要]”。Claude Code、Codex、OpenCode、Aider、Trae、Hermes等助手在分析项目上下文时，会读取这个文件，从而获知设计约束。
.cursor/rules/design-system.mdc: 这是Cursor编辑器特有的规则文件。通过设置alwaysApply: true，Cursor的AI在编写或修改本项目下的任何文件时，都会自动加载并遵循这些设计规则，无需手动触发。
.agent/rules/design-system.md与.agent/workflows/design-system.md: 这是为Google Antigravity定制的。前者是“始终应用”的规则，后者定义了一个/design斜杠命令，用于重新触发设计流程。

实操心得：务必将这些钩子文件（连同Design.md和design-tokens.json）提交到版本控制系统（如Git）。这样，当任何团队成员克隆项目后，他们的AI助手（只要安装了本技能）会自动识别并加载统一的设计规范，从根本上解决了团队内的设计一致性难题。

4.2 安装与配置的注意事项

安装过程通过一个install.sh脚本完成，它本质上是在你的本地AI助手技能目录（如~/.cursor/rules/）和本技能仓库之间创建符号链接。这意味着，当你从GitHub拉取技能的最新版本后，所有链接的AI助手会立即使用更新后的规则。

常见问题与排查：

技能命令不触发：首先检查是否在正确的项目目录下运行。然后，检查对应AI助手的技能目录中是否存在symlink。对于Cursor，可以查看~/.cursor/rules/下是否有design-system.mdc这个链接文件。如果链接丢失，可以重新运行安装脚本。
设计规则未被应用：确保项目根目录下存在Design.md和相应的钩子文件。对于Antigravity，有时需要重启编辑器或重新加载工作区才能使.agent/目录下的规则生效。
审计功能报错或不准确：审计功能依赖于对代码的静态分析。如果它无法识别某些CSS-in-JS或非常规的样式写法，可能会出现误报。此时，可以手动检查design-tokens.json，确保所有使用的值都来源于Token。你也可以在Design.md的“审计日志”部分查看所有被记录的违规，这是一个持续更新的清单。

4.3 日常开发中的使用模式

一旦设置完成，你的开发流程会变得非常流畅：

新建组件：你只需要对AI说“创建一个用户个人资料卡片组件”，AI会自动使用设计Token中的颜色、间距和字体，并遵循原子化层级和隔离规则来生成代码。
修改界面：你可以说“把主页的英雄区域背景改成表面次要色，并增加32像素的上边距”，AI会精确地使用--color-surface-subtle和spacing.8这样的Token来执行。
代码审计：你可以随时对单个文件或整个目录运行audit my UI命令。技能会生成一份详细的报告，指出哪些地方违反了8pt网格、对比度不足或硬编码了值。最棒的是，它通常会提供一个“自动修复”的选项，一键将违规代码替换为正确的Token引用。

5. 实战案例：为一个SaaS仪表盘项目构建设计系统

让我们通过一个虚构的“数据看板SaaS项目——AnalyticsPro”来走一遍完整的实操流程，看看这套系统如何从零开始塑造一个项目的视觉语言和代码规范。

5.1 初始化与六步引导

在项目根目录，我们打开Cursor（已安装技能），在聊天框输入/design。

形态因素：我们选择Website。
应用类型：选择SaaS Dashboard。这一步至关重要，它立刻激活了针对仪表盘的一系列预设：严格网格、高信息密度、克制用色。
框架/平台：选择React/Next.js + Tailwind CSS。这决定了后续会生成tailwind.config.js。
应用身份：
- 名称：AnalyticsPro
- 目标用户：数据分析师、团队负责人
- 核心操作：快速洞察业务关键指标
- 氛围词：专业、清晰、高效
视觉参考：我们提供了公司Logo的URL。技能分析后，提取出Logo中的深蓝色（#1a56db）作为主色候选。
色彩方向：技能基于深蓝色和“专业、清晰”的氛围词，生成了三套OKLCH调色板。一套偏冷蓝（专业感），一套带有少许青色调（清晰、科技感），一套是单色系。我们选择了第一套。

5.2 生成物解析与关键文件调整

技能运行后，生成了以下核心文件：

design-tokens.json：打开这个文件，你会发现颜色不再是简单的十六进制码，而是OKLCH值。例如，主色primary-500可能是oklch(0.55 0.18 250)。间距Token以0.5rem（4px）为基数，定义了1到64的尺度。字体Token定义了一个流畅的clamp()缩放尺度，确保在不同屏幕尺寸下的可读性。

Design.md：这个文件结构清晰，包含了所有规则的详细解释和示例。在“视觉层次规则”部分，它特别强调：“鉴于这是一个SaaS仪表盘，应避免使用过于鲜艳的强调色进行装饰。图表颜色应使用专门定义的、区分度高的数据调色板，而非主色系。”

tailwind.config.js：这个文件不是手写的，而是由Token文件自动映射生成的。它确保了我们在写Tailwind类名时，如bg-primary-500或p-4，使用的值完全来自设计系统。

个人调整：系统生成的设计是优秀的起点，但并非不可更改。例如，我觉得默认的圆角radius.2（对应8px）对于仪表盘卡片有点大，希望更方正一些。我不能直接去组件里写border-radius: 4px。正确的做法是：直接修改design-tokens.json中的"radius": {"2": "0.25rem"}（4px）。然后重新运行一次简单的生成命令（或手动同步），Design.md和tailwind.config.js都会自动更新。所有未来引用了radius.2的组件都会继承这个新值。这就是“单一事实来源”的力量。

5.3 开发、审计与团队协作实战

现在开始开发。我需要一个数据概览卡片。我对Cursor AI说：“Create a React component for a metric card. It should show a title, a large current value, a comparison indicator vs. last period, and an optional trend chart. Use the design system tokens.”

AI生成的MetricCard.tsx大致如下（已简化）：

import { TrendingUp, TrendingDown } from 'lucide-react'; interface MetricCardProps { title: string; value: string | number; change?: number; // positive or negative percentage chartData?: number[]; } export function MetricCard({ title, value, change, chartData }: MetricCardProps) { return ( <div className="bg-surface rounded-radius-2 p-6 border border-border-subtle"> {/* 标题区域 */} <div className="flex items-center justify-between mb-4"> <h3 className="text-text-muted text-sm font-medium">{title}</h3> {/* 变化指示器 */} {change !== undefined && ( <div className={`inline-flex items-center px-2 py-1 rounded-radius-1 text-xs font-medium ${ change >= 0 ? 'bg-success-50 text-success-700' : 'bg-error-50 text-error-700' }`}> {change >= 0 ? <TrendingUp className="w-3 h-3 mr-1" /> : <TrendingDown className="w-3 h-3 mr-1" />} {Math.abs(change)}% </div> )} </div> {/* 主数值 */} <div className="text-3xl font-semibold text-text-primary mb-2">{value}</div> {/* 图表或其他内容区域 - 通过padding-top隔离 */} {chartData && ( <div className="pt-4 mt-4 border-t border-border-subtle"> {/* 简易图表占位 */} <div className="h-16 bg-surface-subtle rounded-radius-1"></div> </div> )} </div> ); }

注意代码中的所有样式都引用了设计Token对应的CSS变量或Tailwind类（如bg-surface,p-6,text-text-muted），没有出现任何一个硬编码的样式值。

代码审计：组件写完后，我运行audit src/components/MetricCard.tsx。技能报告：“PASSES: 所有间距值符合8pt网格，颜色使用Token，对比度合规。” 一切良好。

团队协作：我的同事小王克隆了这个项目。他使用VS Code + GitHub Copilot。当他打开项目，Copilot在分析项目上下文时读到了根目录的AGENTS.md文件，里面包含了设计系统的摘要。因此，当小王让Copilot“添加一个过滤器下拉组件”时，Copilot生成的代码会自动遵循AnalyticsPro的设计规范，使用相同的颜色和间距Token。我们之间不需要开一次会来对齐按钮的蓝色应该用#1a56db还是#2563eb，因为机器已经帮我们强制执行了。

6. 高级技巧、局限性与未来演进

经过一段时间的深度使用，我总结出一些能让你更好地驾驭这个工具的技巧，同时也客观分析它的当前局限。

6.1 高级使用技巧与心得

氛围词的精准使用：三个“氛围词”是影响最终视觉风格的关键杠杆。不要用“好看、酷”这种模糊的词。尝试更具体、更具冲突感的组合，如“坚固且友好”、“复古但数字”、“静谧而有力”。技能会尝试平衡这些特质，产出更有张力的设计方向。
利用“感觉像[App X]”：如果你很难描述想要的风格，直接说“感觉像Linear的仪表盘”或“感觉像Vercel的官网”。技能内置了对这些知名产品设计语言的分析模型，能快速克隆其核心设计模式（如间距节奏、色彩运用），这是一个快速启动项目的捷径。
渐进式严格化：对于已有大量遗留代码的项目，一次性全面应用所有规则（尤其是8pt网格）可能不现实。你可以分步走：首先运行/design生成系统，然后在Design.md中暂时注释掉或调整最严格的规则，先让AI在新代码中遵守。随后，利用“审计”功能，分批、分模块地重构旧代码。
自定义反模式规则：你可以在项目的.cursor/rules/design-system.mdc文件末尾添加你自己的规则。例如，如果你团队约定禁止使用!important，可以添加一条：“禁止在CSS中使用!important声明，如有特殊需求需团队评审。”

6.2 当前局限性

对高度定制化或复杂品牌系统的支持有限：该系统擅长基于规则生成一致、合理的设计，但对于需要突破常规、极具艺术性或复杂品牌叙事的项目，其生成的结果可能显得“安全”但缺乏独特性。它更像一个严谨的工程师，而非天马行空的设计师。
动态主题与深色模式切换：虽然它生成了亮色/深色两套颜色Token，但实现完整的、用户可实时切换的主题，还需要开发者自己编写上下文（Context）和状态管理逻辑来动态切换CSS变量。技能提供了“颜料”，但“调色板切换机制”需要自己搭建。
与复杂设计工具的深度集成：目前它主要从Logo或截图提取颜色，与Figma等设计软件没有直接的、双向的同步管道。设计稿的更新无法自动同步到design-tokens.json，反之亦然。这仍然是设计和开发之间的一道手动桥梁。
学习曲线：对于不熟悉原子化设计、设计Token或WCAG标准的开发者，理解并信任这套系统强加的约束需要时间。初期可能会觉得“不自由”，需要适应期。

6.3 可能的演进方向

从我作为使用者的角度看，这个技能的进化可以朝着几个方向：

Figma插件双向同步：一个理想的未来是，设计师在Figma中维护“主设计文件”，通过插件一键发布到某个URL或生成令牌文件。开发项目的技能可以订阅这个URL，自动同步变更，并生成变更日志。
更智能的上下文感知：目前的规则是全局的。未来可以支持“上下文规则”，例如：“在模态框（Modal）内，使用更紧凑的间距Token子集”；“在移动端视图下，将三级标题降级为四级标题”。
可视化规则编辑器：高级用户可能希望通过一个UI界面来调整、禁用或新增设计规则，而不是直接编辑Markdown或配置文件。

这个项目代表了一种前沿的思潮：将设计系统从一份静态的、需要人力维护和宣讲的文档，转变为一个动态的、可执行的、深度嵌入开发工具的“活系统”。它可能不是所有项目的银弹，但对于追求产品一致性、团队协作效率和开发速度的团队来说，它无疑是一个强大的加速器和质量守门员。我开始使用它之后，最直观的感受是，和AI讨论UI时，我们从争论“这个蓝色好不好看”变成了讨论“这个交互流程合不合理”，把创造力聚焦在了更值得投入的地方。