当前位置：首页 > news >正文

构建AI-Ready设计系统：三层架构实现人机协同开发

news 2026/5/3 14:14:55

1. 项目概述：一个为AI与人类共读而生的设计系统

如果你和我一样，在过去一年里频繁地与Claude Code、Cursor、GitHub Copilot这样的AI编码助手打交道，那你一定遇到过这个令人头疼的场景：你满怀期待地输入“创建一个用户管理页面，包含搜索框、数据表格和分页”，AI助手也确实生成了代码，但结果却是一团糟——样式混乱、组件风格不统一、甚至违背了你自己项目里辛苦建立的设计规范。问题出在哪？传统的设计系统，无论是Figma设计稿、Storybook文档，还是冗长的Markdown指南，本质上都是为人类设计的。它们依赖设计师和工程师去阅读、理解、并在具体情境中做出判断。但AI不是人类，它无法“理解”设计哲学，它只能“读取”和“匹配”信息。

这正是melta UI诞生的背景。它不是一个普通的UI组件库，而是一个AI-Ready Design System，一个专门为解决“如何让AI也能准确理解并遵循设计规范”这一核心问题而构建的体系。它的目标直白而深刻：在完全不牺牲人类开发者可读性和使用体验的前提下，为AI助手提供一套机器可读、无歧义、可验证的“设计宪法”。简单来说，它让AI从“凭感觉猜”变成了“按规矩办”。

这个项目来自日本的开发者tsubotax，其名称“melta”或许就蕴含着“融合”之意。它基于当前前端生态中普及度极高的Tailwind CSS构建，但它的价值远不止于提供另一套按钮和卡片组件。它的核心创新在于其三层架构和机器可读的单一事实来源，这确保了无论是人类通过文档查看，还是AI通过API调用，获取到的设计规则都是绝对一致且无歧义的。接下来，我将深入拆解这套系统的设计哲学、实现细节，并分享如何将其理念融入到你自己的项目中。

2. 架构深度解析：三层结构如何实现“AI-Ready”

melta UI的整个系统围绕一个核心目标构建：让AI“不迷路、少犯错、错了能发现”。为此，它采用了清晰的三层架构，每一层都扮演着不可替代的角色。

2.1 第一层：宪法层——AI的“入职培训手册”

这是AI接触项目时的第一个，也是最重要的入口。想象一下，一位新加入团队的工程师，第一件事就是阅读项目README和核心设计文档。对于AI来说，DESIGN.md和CLAUDE.md就扮演了这个角色。

DESIGN.md- 设计宪法与速查表：这份文档是给所有AI代理看的。它开宗明义地阐述了品牌的视觉身份和七大设计原则，比如“内容优先”、“严格遵守WCAG 2.1 AA无障碍标准”、“使用语义化颜色（bg-primary-500而非bg-blue-600）”等。更重要的是，它包含了一个Quick Reference部分，用最精炼的方式告诉AI：“要创建一个主要按钮，就用这些Tailwind类；要创建一个卡片，就遵循这个结构。”这使得AI在无需深入细节的情况下，就能生成基本合规的UI。
CLAUDE.md- Claude Code专属工作手册：这是针对特定AI工具（Claude Code）的优化指南。它详细说明了Claude Code应该如何加载这个设计系统、使用哪些npm脚本、以及处理不同任务时的最佳实践路径。这相当于为这位特定的“新员工”提供了一份岗位说明书，极大提升了协作效率。

实操心得：在你自己的项目中，即使不构建完整的melta UI，也强烈建议创建一个AI_GUIDE.md文件。用清晰的结构列出你的品牌色Token（如--color-brand-primary）、间距基数（如4px）、核心组件的类名范式。这能显著提升AI生成代码的可用性。

2.2 第二层：规范层——机器可读的单一事实来源

如果说第一层是指导方针，那么第二层就是具有法律效力的成文法典。所有设计细节都被转化为结构化的JSON文件，存放在design/contracts/目录下。这是整个系统的“单一事实来源”，确保了信息的一致性和无歧义性。

tokens.json- 设计Token库：这里定义了99个设计Token，包括颜色、间距、圆角、字体大小等。每个Token都有清晰的路径，如color.primary.500、spacing.4。AI不需要理解“主色”是什么，它只需要知道当规范要求color.primary.500时，去这个文件里查找对应的十六进制值或CSS变量名即可。
rules.json- 禁止规则注册表：这是melta UI最具特色的部分之一，包含了89条具体的禁止规则。每条规则都有唯一ID、严重等级（error/warning）和检测模式。例如，规则AI_NO_CARD_COLOR_BAR_TOP会检测是否使用了border-t-4这种“顶部彩色边框”的常见AI装饰风格，并提示应使用border border-slate-200来构建卡片。这相当于给AI设置了一个“代码审查员”，在生成时就能规避已知的坏味道。
components/目录 - 组件契约：28个UI组件（如Button、Card、Modal）每个都有一个对应的.contract.json文件。这个文件以机器最友好的方式，定义了组件的所有变体、尺寸、对应的设计Token引用、以及必须遵守的Tailwind类字符串。

// 以按钮契约的片段为例 { "id": "button", "variants": { "contained": { "tokenRefs": { "bg": "color.primary.500", "text": "color.white", "radius": "radius.md" }, "tailwind": "inline-flex items-center justify-center gap-2 h-10 px-4 rounded-md bg-primary-500 text-white font-medium ..." } }, "rules": ["BTN_ICON_ONLY_ARIA_REQUIRED"] // 该组件需要额外注意的规则 }

这种结构化的定义，使得AI可以通过简单的数据查询来获取组件的准确构建方式，完全避免了自然语言文档可能存在的模糊性。

2.3 第三层：验证层——自动化的质量守门员

有了宪法和法典，还需要执法机构。第三层就是一系列自动化工具，确保上述规范被严格遵守。

脚本 (scripts/design/): 包含校验合约完整性、检查文档与合约是否发生偏离、构建向后兼容数据等脚本。
**测试 (tests/)**: 使用Playwright进行组件渲染测试，并集成axe-core`进行自动化的无障碍合规测试（共9项核心测试）。
CI/CD (`github/workflows/): 通过GitHub Actions，在每次提交或拉取请求时自动运行设计规范校验和测试，确保不符合规范的代码无法进入主分支。
MCP服务器: 这是连接AI与设计系统的“桥梁”。它是一个标准的Model Context Protocol服务器，将设计系统的查询能力（如获取Token、获取组件规范、检查规则）暴露为AI可以直接调用的工具函数。

这个三层架构形成了一个完美的闭环：引导（宪法） -> 定义（规范） -> 执行（验证），从而真正实现了“AI-Ready”。

3. 核心工作流程：AI如何与melta UI协同工作

理解了架构，我们来看看AI在实际编码时，是如何与melta UI交互的。melta UI提供了多种集成方式，适应不同的工作流。

3.1 模式一：轻量级启动（Claude Code原生集成）

这是最无缝的体验。你只需要将melta UI的仓库作为子模块放在项目根目录，或者直接复制其DESIGN.md和CLAUDE.md文件。当你在Claude Code中打开项目时，它会自动读取这些文件。

工作流程示例：

人类指令：“创建一个用户资料卡片，包含头像、姓名、职位和一个‘关注’按钮。”
AI内部处理：
- AI首先阅读DESIGN.md，理解卡片和按钮的基本设计原则。
- 根据CLAUDE.md的指引，它知道可以去查询design/contracts/。
- AI查询card.contract.json和button.contract.json，获取到准确的HTML结构和Tailwind类。
- 同时，它可能会调用check_rule工具，验证自己生成的代码片段（如shadow-lg）是否违反了禁止规则。
输出：生成一段完全符合设计规范的、结构清晰的HTML代码，使用了正确的语义化类名如bg-card、text-primary，并且避免了任何被禁止的装饰模式。

3.2 模式二：深度集成（通过MCP服务器）

对于更复杂、需要动态查询的项目，可以启动内置的MCP服务器。这为AI提供了强大的实时查询能力。

配置与使用：

# 1. 构建MCP服务器 npm install npm run build # 2. 将其添加到你的AI助手（如Claude Desktop）中 # 具体命令取决于你的AI客户端，例如： claude mcp add melta-ui node ./dist/index.js

可用工具一览：

工具名	功能描述	典型使用场景
`get_token`	按路径查找设计Token	AI需要知道`color.error.500`对应的具体HEX值。
`get_component`	获取组件的完整契约	AI需要构建一个分页组件，查询`pagination`的所有变体和必需类。
`check_rule`	检查一段CSS类字符串是否违反规则	AI生成代码后，自我审查是否包含了`border-t-4`这类禁止模式。
`search`	在全系统文档中搜索关键词	AI不确定“模态框”该如何处理，搜索`modal`获取相关文档和契约。

这种方式让AI像调用API一样使用设计系统，实现了真正的动态、精准的代码生成。

3.3 模式三：编辑器增强（Cursor规则）

对于使用Cursor编辑器的开发者，melta UI直接提供了预配置的规则文件，放置在.cursor/rules/目录下。这些规则文件会在你编码时提供实时的提示、自动补全和规则检查，将设计系统的约束直接融入开发环境。

注意事项：MCP服务器和Cursor规则的配置，本质上都是将设计系统的“知识”注入到AI的上下文中。关键在于确保这些知识来源（JSON合约）是唯一且最新的。melta UI通过构建脚本npm run design:build，从contracts/生成metadata/components.json，保证了MCP和规则文件的数据同源。

4. 设计原则与实现细节：为何这样设计？

melta UI的七大设计原则并非空谈，它们直接影响了Token和组件的具体实现。理解这些，你才能更好地复用或借鉴其思想。

4.1 语义化颜色与3色原则

传统项目中，我们可能直接使用bg-blue-600。这带来了两个问题：1) 品牌色变更时需要全局搜索替换；2) AI无法理解blue-600代表“主操作”。melta UI的做法是建立语义化Token映射。

实现方式：在tokens.json中，定义：

{ "color": { "primary": { "500": "#3b82f6", "600": "#2563eb" }, "neutral": { "100": "#f3f4f6", "800": "#1f2937" } } }

在theme.md或CSS变量中，将Tailwind类映射到这些Token：

/* 通过Tailwind配置或CSS变量实现 */ :root { --color-primary-500: #3b82f6; }

在Tailwind配置中：

// tailwind.config.js module.exports = { theme: { extend: { colors: { primary: { 500: 'var(--color-primary-500)', 600: 'var(--color-primary-600)', } } } } }

AI使用效果：AI在生成按钮时，会使用bg-primary-500而不是bg-blue-600。当品牌色从蓝色改为绿色时，只需修改Token值，所有组件自动更新。3色原则（一个界面主要使用不超过3种语义色）则通过规则来约束，避免AI在一个页面中滥用过多颜色。

4.2 严格的间距网格与无障碍默认

4px基准网格：所有间距（padding, margin, gap）、尺寸（height, width）都建议使用4px的倍数（如4, 8, 12, 16, 20, 24...）。这在tokens.json中体现为spacing系列Token。AI在布局时，会被引导使用这些标准值，确保视觉节奏的一致。

WCAG 2.1 AA默认合规：这是通过两个机制保障的：

Token设计：在定义颜色Token时，就确保其对比度组合（如primary.500与white）满足4.5:1的最低要求。
组件契约：在组件的契约中，直接绑定好了符合对比度的前景色和背景色Token。例如，一个contained按钮的契约里，bg指向color.primary.500，text指向color.white，这个组合在定义时就是无障碍的。
自动化测试：通过Playwright + axe-core的测试套件，自动检测生成的页面是否存在对比度不足等无障碍问题。

4.3 反对“AI式装饰”与规则检测

AI在生成UI时，常会添加一些刻板的“装饰”，如顶部彩色边框(border-t-4)、过重的阴影(shadow-2xl)、无意义的渐变。melta UI的rules.json将这些模式明确定义为错误。

规则引擎示例：

{ "id": "AI_NO_EXCESSIVE_SHADOW", "severity": "error", "detector": "tailwind-class", "pattern": "shadow-(xl|2xl)", "alternative": "使用 shadow-sm, shadow-md 或 shadow-lg（仅用于叠加层）", "reason": "保持界面轻盈，避免视觉噪音" }

当AI生成的代码包含shadow-2xl时，check_rule工具或CI流程会立即标记出错误，并给出修改建议。这相当于将资深设计师的评审意见自动化了。

5. 实战：将melta UI理念引入现有项目

你可能不需要完全照搬melta UI，但它的核心思想极具借鉴价值。以下是如何在你的团队或项目中逐步实施。

5.1 第一步：建立机器可读的设计Token

这是投入产出比最高的一步。不要只把设计Token放在Figma或口头上。

创建一个design-tokens.json文件。
使用类似melta UI的结构化格式定义你的颜色、间距、字体等。
使用工具（如style-dictionary）或编写简单脚本，将这个JSON文件转换为你需要的格式：CSS变量、Tailwind配置、SCSS变量、甚至iOS/Android的资源文件。
确保这个JSON文件是你的SSOT。所有平台的样式都从这里生成。

5.2 第二步：编写AI友好的核心文档

创建或更新你的DESIGN.md或STYLE_GUIDE.md。

开头部分：用最简洁的语言阐述你的1-3条核心设计原则（例如：“我们的产品追求信息密度与可读性的平衡”）。
速查表：制作一个表格，列出最常用的10个组件及其对应的CSS类或组件名。例如：
组件用途类名/组件
主按钮主要操作 <Button variant="primary">
卡片容器信息分组 class="bg-white rounded-lg border p-6"
危险操作删除等 <Button variant="danger">
给AI的提示：在文档末尾，可以加一段“给AI助手的提示”，明确说明：“请优先使用上表中的类名/组件。颜色请使用语义化Token，如text-brand-primary。”

组件	用途	类名/组件
主按钮	主要操作	`<Button variant="primary">`
卡片容器	信息分组	`class="bg-white rounded-lg border p-6"`
危险操作	删除等	`<Button variant="danger">`

5.3 第三步：定义关键禁止规则

与团队的设计师和资深前端工程师开个会，列出你们最不能忍受的5-10种“坏样式”。

例如：“禁止使用!important”、“禁止行内样式”、“禁止使用固定像素字体大小（应使用text-sm、text-base等）”、“表单标签必须与输入框关联（for和id）”。
将这些规则写入一个ai-rules.json文件，或者简单地写在团队Wiki里。在代码审查时，将这些规则作为检查项。

5.4 第四步：探索自动化集成

如果你的团队大量使用AI编码：

研究MCP：了解Model Context Protocol，它正在成为AI助手与工具集成的事实标准。尝试为你项目的关键API或规范编写简单的MCP工具。
配置编辑器：在Cursor或VSCode（配合Copilot）中，通过设置代码片段、模板或规则文件，引导AI生成更符合你们约定的代码。
设置CI检查：可以编写一个简单的脚本，在CI中扫描新代码，检查是否违反了核心禁止规则（例如，用正则表达式检查是否有!important）。

5.5 常见问题与排查

Q1：这套系统会不会增加前端开发的复杂度？A：对于小型项目或个人项目，初期会有学习成本。但对于中大型团队，它通过减少AI生成代码的返工率、统一视觉输出、自动化代码审查，从长期看显著提升了开发效率和代码质量。你可以从“建立设计Token”这一小步开始。

Q2：我们用的不是Tailwind CSS，怎么办？A：melta UI的核心思想是分层架构和机器可读的规范，这与CSS解决方案无关。你可以用相同的结构，将tailwind字段替换为css（包含CSS规则字符串）或className（你的CSS Modules类名）。关键在于将组件契约定义为数据。

Q3：如何维护contracts.json和实际组件代码的同步？A：这是最大的挑战。melta UI的策略是契约驱动：contracts/目录是SSOT，组件的实现（无论是React、Vue还是纯HTML示例）都应被视为根据契约“生成”的产物。可以通过脚本（如npm run design:drift）来检测两者是否发生偏离，并在CI中阻断不同步的提交。理想情况下，组件的实现应该能部分或全部从契约中自动生成。

Q4：AI真的能严格遵守这些复杂规则吗？A：以目前的Claude 3.5 Sonnet或GPT-4o水平，在提供了清晰、结构化、上下文充足的规范后，其遵守率非常高。规则不是为了100%杜绝错误，而是将错误率从“不可控”降低到“可管理、可检测”的水平。结合MCP工具的实时查询和CI的最终检查，可以形成一个可靠的质量防线。