1. 项目缘起当设计系统遇上AI智能体最近在做一个内部工具的后台界面和很多开发者一样我遇到了一个经典困境前端UI开发太耗时了。从零开始搭组件、调样式、处理响应式一套流程下来核心业务逻辑还没怎么写几天时间就过去了。更头疼的是当我想尝试用一些新兴的AI编码助手比如Cursor、Claude Code、甚至是GitHub Copilot的聊天模式来加速开发时发现它们生成的组件代码风格各异难以统一后期整合的成本甚至比手写还高。这让我开始思考一个问题我们能否创建一套设计资源它不仅是给人用的更是为“AI程序员”量身定制的一套组件库如果其代码结构、命名约定、文档注释都能被主流AI编码智能体“理解”并“熟练调用”那开发效率会不会有质的飞跃基于这个想法我花了几个月时间整理、重构并开源了一套包含502个独立组件的HTML设计工具包。它的核心目标很明确原生适配AI编码助手的工作流让“用自然语言描述界面AI输出可直接使用的、风格一致的代码”成为标准操作。这套工具包不是另一个Bootstrap或Tailwind UI的简单复制。它的独特之处在于每一个组件从简单的按钮、卡片到复杂的仪表盘、数据表格、导航菜单都被精心设计为“AI友好型”。这意味着当你对AI智能体说“创建一个带有头像、用户名、操作按钮和下拉菜单的用户资料卡片”时它有很大概率会输出与我这套设计语言完全匹配的、可直接粘贴运行的HTML和CSS代码而不是需要你花大量时间调整的“近似”方案。2. 设计哲学构建AI与开发者之间的“通用语”要让AI智能体高效地使用一套设计系统关键在于建立一套清晰、一致、可预测的“通信协议”。这超越了传统设计系统只关注视觉一致性的范畴进入了“语义一致性”和“结构可解析性”的层面。2.1 原子化与组合性让AI学会“搭积木”我采用了严格的原子设计方法论但这套方法论是为AI理解而优化的。组件被清晰地划分为五个层级原子Atoms 最基础的构建块如颜色变量、字体样式、间距单位、基础HTML标签样式button,input。这些都以CSS自定义属性CSS Custom Properties和实用类Utility Classes的形式明确定义。分子Molecules 由原子组合而成的简单UI控件例如一个带图标和标签的按钮、一个带标签的输入框组合。每个分子组件都有单一的、明确的功能。有机体Organisms 相对复杂的、由分子和原子组合而成的界面区块如网站页头包含Logo、主导航、搜索框、用户菜单、产品卡片、评论表单。模板Templates 将多个有机体放置在页面布局中定义页面的基础骨架和内容区域但尚未填入真实内容。例如一个后台仪表盘模板定义了侧边栏、顶部导航和主内容区的布局。页面Pages 在模板中填入特定的内容文本、图片、数据形成最终的用户界面。为什么这对AI重要当AI智能体被要求“创建一个登录表单”时如果它“知道”这套设计系统它的推理链条会非常高效首先它会调用“表单Organism”模板然后在其中组合“输入框组Molecule”和“按钮Molecule”最后为这些元素应用预定义的“主色Atom”和“圆角Atom”。这种清晰的层级关系极大地降低了AI生成代码的随机性和错误率。注意 在组件的注释和文档中我明确标注了每个组件所属的层级。例如在按钮组件的文件开头会写!-- Component Level: Molecule --。许多AI智能体在训练时学习了大量代码注释这种明确的元信息能有效引导它们。2.2 语义化的命名与类名体系混乱的类名是AI的噩梦。像.btn-primary、.card-lg、.mt-4这种基于功能的类名是好的但还不够。我在此基础上建立了一套扩展的、语义化的BEMBlock Element Modifier改良体系。区块Block 代表一个独立的、有意义的UI单元如.user-profile。元素Element 属于区块的一部分没有独立意义如.user-profile__avatar、.user-profile__name。修饰符Modifier 表示区块或元素的状态或变体如.user-profile--compact、.button--loading。关键改进在于为修饰符增加了状态语义例如不仅用.button--disabled还配套有[aria-disabledtrue]属性不仅用.menu--expanded还配套有[aria-expandedtrue]。这样AI在生成交互组件时不仅能输出正确的样式类还能生成符合无障碍A11y标准的HTML属性这是很多AI原生生成代码时容易忽略的要点。2.3 内联文档与“提示词”注释这是让组件“AI原生”的核心技巧。我在每个组件的HTML文件内部和CSS选择器旁边都添加了结构化的、自然语言写成的注释。这些注释不是给人看的开发文档而是给AI看的“使用说明书”或“提示词模板”。!-- COMPONENT: Stat Card (统计卡片) DESCRIPTION: 用于展示单个统计数字、其标签和变化趋势。通常用于仪表盘概览。 USE CASE: 展示用户数、销售额、增长率等关键指标。 AI PROMPT EXAMPLE: “创建一个展示‘月度营收’的统计卡片主数值是$125K同比增长12%使用上升趋势图标和绿色强调色。” ACCESSIBILITY: 确保 div rolestatus 包裹动态更新的数值以便屏幕阅读器通知变化。 -- div classstat-card rolestatus div classstat-card__labelMonthly Revenue/div div classstat-card__value aria-livepolite$125K/div div classstat-card__trend trend--up span classtrend__icon↑/span span classtrend__value12%/span /div /div/* 组件统计卡片 - 基础样式 */ .stat-card { padding: var(--spacing-6); /* 使用设计令牌中的间距变量 */ background: var(--color-surface); border-radius: var(--radius-lg); border: 1px solid var(--color-border); } /* 修饰符紧凑模式 - 用于空间有限的侧边栏或列表 */ .stat-card--compact { padding: var(--spacing-4); } /* AI提示当需要节省空间时为组件添加 .stat-card--compact 类 */当AI智能体分析我的代码库时这些高度结构化的注释就像一个个“微调训练样本”教会它这个组件是什么、怎么用、以及如何向人类开发者描述它。实测下来像Cursor这类深度集成AI的编辑器在项目内调用这些组件时准确率和代码质量显著高于使用没有此类注释的普通组件库。3. 技术实现打造机器可读的设计令牌与组件API一套设计系统要能被AI流畅使用其底层设计令牌Design Tokens和组件“API”必须是机器高度可读和可推理的。3.1 单一事实来源CSS自定义属性与JSON双定义我采用了一种混合策略来管理设计令牌颜色、字体、间距、阴影等。CSS自定义属性主来源 所有令牌都在:root中定义为CSS变量这是样式生效的实际来源。:root { /* 颜色系统 */ --color-primary-500: oklch(62% 0.22 255); --color-primary-600: oklch(54% 0.22 255); --color-surface: #ffffff; --color-border: #e5e7eb; /* 间距系统 */ --spacing-unit: 0.25rem; --spacing-1: calc(1 * var(--spacing-unit)); /* 0.25rem */ --spacing-4: calc(4 * var(--spacing-unit)); /* 1rem */ /* 圆角 */ --radius-sm: 0.25rem; --radius-lg: 0.75rem; }配套的JSON文件机器可读来源 同时我维护一个design-tokens.json文件它以结构化的方式描述了整个令牌系统。{ color: { primary: { 500: { value: oklch(62% 0.22 255), type: color, description: 主品牌色 }, 600: { value: oklch(54% 0.22 255), type: color, description: 主品牌色 - 悬停/激活状态 } }, surface: { value: #ffffff, type: color, description: 表面背景色 } }, spacing: { unit: { value: 0.25rem, type: spacing }, 1: { value: {spacing.unit} * 1, type: spacing }, 4: { value: {spacing.unit} * 4, type: spacing } } }这样做的好处是AI智能体可以直接读取design-tokens.json文件理解整个设计系统的“词汇表”。当它需要生成一个“使用主色和标准内边距的按钮”时它可以精确地引用--color-primary-500和--spacing-4而不是随意编造一个颜色值或像素单位。许多先进的AI编码助手已经具备解析项目配置文件的能力这个JSON文件就是为它们准备的“设计系统说明书”。3.2 组件变体与属性的显式声明一个按钮可能有多种变体主要按钮、次要按钮、危险按钮、不同尺寸、禁用状态等。在传统组件库中这些通常通过不同的CSS类来区分。在我的AI原生工具包中我通过一个component-api.md文件来显式声明每个组件的“API”。以按钮为例# Button 组件 API **选择器基类**: .btn **可用修饰符Modifiers**: - 类型: .btn--primary, .btn--secondary, .btn--danger, .btn--ghost - 尺寸: .btn--sm, .btn--md (默认), .btn--lg - 状态: .btn--disabled (需配合 disabled 属性或 aria-disabled) **期望的HTML属性**: - typebutton|submit|reset - disabled (布尔属性) - aria-label (如果按钮内无文本) **组合示例**: html !-- 一个大型的主要提交按钮 -- button classbtn btn--primary btn--lg typesubmit提交订单/button !-- 一个小的、危险的、禁用状态的按钮 -- button classbtn btn--danger btn--sm disabled删除/button这个文件本质上是一个机器可读的组件契约。AI在生成代码时可以参考这个契约确保组合出的类名是有效且符合预期的避免了生成.btn--large-primary这种不存在的混合类名。3.3 无框架依赖与纯CSS实现为了最大化兼容性和AI的理解难度我刻意选择了纯HTML CSS的实现方式没有使用任何JavaScript框架React, Vue等或CSS-in-JS方案。原因有三降低AI复杂度 AI模型对标准的、语义化的HTML和CSS的理解和生成能力远高于对特定框架语法如JSX、Vue SFC的理解。纯静态文件减少了上下文依赖。零构建步骤 组件可以直接通过link标签引入或在任何服务器端模板中使用AI无需理解构建工具链Webpack, Vite就能推荐正确的使用方式。作为坚实基础 开发者或AI可以基于这些纯HTML/CSS组件轻松地将其封装成任何前端框架的组件。这提供了最大的灵活性。当然纯CSS意味着交互状态如下拉菜单、模态框的开关需要依靠:focus,:target或隐藏复选框技巧来实现。我在相关组件的注释中详细说明了这种实现原理并提供了标准的、可访问的HTML结构帮助AI理解如何生成和操作这些交互组件。4. 实战如何与AI编码智能体协同工作有了这套设计工具包你与AI协作的流程会发生根本性的改变。以下是我在实际项目中的几种高效使用模式。4.1 模式一精准组件生成这是最直接的用法。在AI聊天界面如Cursor的Chat、Claude Code的编辑器集成你可以给出非常具体的指令。低效指令传统方式 “给我一个用户卡片UI有头像、名字、简介和一个关注按钮。”高效指令AI原生工具包方式 “使用我们项目中的user-profile有机体组件生成一个用户卡片。用户名为‘Alex Johnson’头像是avatar.jpg简介是‘全栈开发者’并包含一个‘关注’按钮。按钮使用次要变体secondary variant。”AI在理解了你的项目上下文尤其是如果它已经索引了你的组件库文件后会生成如下高度可用的代码!-- 它知道引用具体的组件类和结构 -- div classuser-profile img classuser-profile__avatar srcavatar.jpg altAlex Johnson的头像 div classuser-profile__body h3 classuser-profile__nameAlex Johnson/h3 p classuser-profile__bio全栈开发者/p /div button classbtn btn--secondary typebutton关注/button /div生成的代码不仅样式立即可用而且类名和结构都与整个系统的其他部分保持一致。4.2 模式二布局与页面快速原型当你需要构建一个完整的页面时你可以直接描述页面布局和内容区域让AI调用工具包中的模板和有机体进行组装。指令示例 “创建一个后台仪表盘页面使用我们的layout-dashboard模板。左侧边栏放置主导航顶部栏包含用户菜单和搜索框。主内容区分为两列左列放置一个‘数据概览’标题和三个并排的stat-card统计卡片右列放置一个># .cursorrules 本项目使用了一套内部的、AI原生的HTML设计工具包。 - 所有UI组件都应优先使用该工具包中的组件。 - 组件代码和样式令牌的定义位于 /design-system/ 目录下。 - 在生成HTML时请参考 /design-system/component-api.md 了解可用组件及其用法。 - 样式应使用 /design-system/tokens.css 中定义的设计令牌CSS变量。 - 保持生成的代码与现有代码的样式和结构一致性。当你在Chat中提问时Cursor的AI会主动参考这个规则文件和被索引的组件代码生成高度匹配的代码。5.2 在Claude Code或GitHub Copilot Chat中提供参考对于这些工具你可以在提问时手动将关键组件或令牌的定义作为参考信息粘贴到对话中。示例 “请创建一个登录表单。参考我们项目的设计令牌主色是--color-primary-500标准内边距是--spacing-6。参考我们的输入框组件结构div class“input-group”label.../labelinput class“input”.../div。”虽然不如Cursor自动上下文方便但通过提供精确的“代码片段”作为提示你依然可以极大地引导AI输出符合规范的代码。5.3 在VS Code Copilot中利用代码片段Snippets你可以将工具包中最常用的组件如按钮、卡片、模态框的完整HTML结构配置为VS Code的用户代码片段User Snippets。这样当你输入btn-primary并按下Tab时就能直接插入一个完整的主要按钮代码块。Copilot在学习你的编码习惯后也会在建议中优先推荐这些片段。6. 常见问题与效能边界在实际使用和社区反馈中我总结了一些常见问题和这套方法的局限性。6.1 AI生成不准确或使用了错误类名问题 AI有时会“发明”一个不存在的类名如.card-header-large。排查与解决检查上下文 确保AI如Cursor已经正确索引了你的component-api.md和组件目录。有时需要手动在Chat中“”引用一下相关文件。提示词更精确 在指令中明确指定修饰符的组合方式。例如不说“一个大卡片”而说“一个应用了.card--lg修饰符的卡片组件”。提供示例 直接告诉AI“请按照以下已有示例的结构生成……”并附上一段正确的代码。6.2 生成的HTML结构过于复杂或嵌套过深问题 AI可能为了满足描述生成多层嵌套的div影响可读性和性能。解决 在.cursorrules或你的提示词中明确加入要求“生成的HTML结构应保持简洁和语义化避免不必要的嵌套div包装。优先使用原生HTML5语义化标签。”6.3 如何处理动态交互逻辑现状 纯HTML/CSS组件库不包含JavaScript。AI可以生成静态结构但交互逻辑如模态框打开关闭、标签页切换需要额外开发。策略生成静态框架 让AI生成包含所有状态如隐藏的模态框内容、所有标签面板的完整HTML结构并正确设置初始的CSS状态类如.modal--hidden。分离逻辑提示 然后再开启一个新的对话或提示专门要求AI“为上面生成的模态框编写一个简单的JavaScript函数当点击.modal-trigger按钮时切换.modal--hidden类”。这样关注点分离效果更好。6.4 这套方法适用于所有AI编码助手吗效能差异 不同AI智能体的代码理解、上下文长度和项目感知能力不同。目前深度集成在IDE中、能主动索引项目文件的工具如Cursor效果最好。纯聊天的Copilot Chat或Claude Code需要更多手动引导。模型差异 基于最新代码数据训练的模型如Claude 3.5 Sonnet, GPT-4 Code对这类任务的理解明显优于早期模型。选择能力更强的底层模型是关键。7. 开源的价值与社区的迭代我将这个包含502个组件的工具包完全开源是相信“AI原生设计系统”这个想法需要社区的共同验证和进化。开源带来的好处是显而易见的真实场景的测试 不同行业、不同项目的开发者会以我未曾想到的方式使用这些组件从而暴露出更多AI交互的边角情况。提示词库的共建 社区可以贡献针对特定组件的、更高效的AI提示词示例形成最佳实践合集。组件需求的扩展 社区需要的组件比如一个电商的SKU选择器、一个日历预约控件可以反馈回来让我或其他人以“AI友好”的方式实现并贡献从而不断丰富这个生态。降低尝试门槛 任何开发者都可以直接克隆仓库在自己的项目中体验这种与AI协作的新范式而无需从头开始构建这五百多个基础组件。开源几个月来我已经收到了几十个Pull Request有修复微小样式兼容性的有增加新组件的更有趣的是有人提交了专门为其他AI助手如通义灵码优化的使用文档。这种协同进化正是开源项目最迷人的地方。回过头看开发这套工具包最大的投入不是在写CSS上而是在于思维的转变从“如何让人类开发者用好”转变为“如何让人类和AI协同用好”。你需要像设计API一样设计组件的接口像编写技术文档一样编写机器可读的注释。这个过程本身就是对未来人机协作模式的一次深刻预演。当AI成为团队中的“初级工程师”时我们这些资深开发者或许就应该致力于为它打造更趁手的“工具”和更清晰的“规范”。这套502组件的设计工具包就是这样一个尝试。