DesignKit：基于CSS变量与AI协议的开源设计系统，加速原型到代码工作流

1. 项目概述：一个为AI编码而生的原生设计系统

如果你也经常在原型设计和前端开发之间反复横跳，每次想快速搭个界面，要么得花半小时在Figma里摆弄组件，要么得跟AI描述半天“我想要一个带卡片、列表和导航的金融仪表盘”，结果生成的代码风格混乱、毫无设计体系可言——那你应该能理解我为什么要做DesignKit。

简单说，DesignKit是一个包含502个独立HTML组件和33套完整页面设计（涵盖移动端和网页）的开源库。它的核心不是又一个UI框架，而是一个为AI编码智能体（Agent）量身定制的设计语料库。每个组件都是自带内联样式的纯HTML片段，没有构建步骤，没有npm install，开箱即用。但真正让它与众不同的是其底层基于CSS自定义属性（CSS Custom Properties，也就是CSS变量）构建的“令牌系统”，以及一份专门写给AI看的“设计系统说明书”（AI-AGENT.md）。这意味着，你可以直接告诉AI：“参考DesignKit的设计规范，给我生成一个深色模式、高端感的金融应用首页，移动端390px宽度。”AI能理解并输出一套像素级精准、风格统一的HTML代码，而不是一堆需要你二次调整的“毛坯房”。

这解决了原型到代码工作流中的一个核心痛点：设计意图的精确传递。我们不再需要依赖模糊的语言描述或额外的设计文件作为中间媒介，HTML本身既是最终的可视化结果，也是AI进行跨框架转换（如转成React、Vue、SwiftUI）时最坚实、无歧义的“设计稿”。

2. 核心设计哲学：为什么是纯HTML + CSS变量？

在启动这个项目前，我评估过多种方案：Figma社区组件库、设计令牌（Design Tokens）JSON文件、甚至是一些专为AI定义的DSL（领域特定语言）。最终选择纯HTML+CSS变量这套看似“复古”的技术栈，是基于以下几个深思熟虑的考量，这些考量直接决定了它能否被AI高效理解和使用。

2.1 选择HTML作为“通用设计语言”的四大理由

第一，HTML是AI的“母语”之一。大型语言模型（LLM）的训练数据中包含了海量的HTML和CSS代码。这意味着AI对HTML的语义结构、属性用法有着深刻的内在理解。我们不需要教AI学习一门新的、小众的DSL，它天生就懂<div>、<section>、class和style。使用HTML，相当于在和AI用它的“方言”高效沟通。

第二，可视化即所得，零成本验证。一个HTML文件，用任何浏览器都能直接打开并渲染出完整的UI。这一点至关重要。无论是开发者、设计师，还是AI Agent，三方看到的是完全一致的东西。这消除了基于JSON或YAML的设计描述中常见的“想象差距”——你描述了一个borderRadius: ‘lg’，但每个人对‘lg’的具体像素值可能有不同理解。在DesignKit中，--kit-radius: 10px;是唯一真理，打开浏览器，效果立即可见。

第三，极致的简单性与零依赖。项目结构就是一个文件夹，里面是.html和.css文件。没有构建工具，没有包管理器，没有复杂的模块系统。这种 simplicity（简单性）带来了巨大的灵活性。你可以把它直接拖进任何支持文件读取的AI工具（如Cursor、Claude Code、甚至是ChatGPT with Code Interpreter），AI能立刻解析并开始工作。对于想快速上手的用户，学习成本几乎为零。

第四，框架无关的“设计源头”。HTML是Web的基石，也是所有现代UI框架（React、Vue、Svelte等）和移动端框架（通过WebView或转换工具）共同的基础。一份设计良好的HTML，可以作为向任何技术栈转换的完美“设计稿”。当你对AI说“把这个HTML组件转换成React Tailwind组件”时，AI拥有一个结构清晰、样式明确的源代码进行转换，成功率远高于从模糊需求描述直接生成框架代码。

2.2 CSS自定义属性：构建动态设计系统的基石

DesignKit的灵魂在于其全面采用CSS自定义属性（CSS Variables）来定义所有视觉属性。在项目的:root中，你定义了一套完整的“设计令牌”。

:root { --kit-primary: #6366F1; --kit-bg: #FFFFFF; --kit-surface: #F8FAFC; --kit-text: #0F172A; --kit-text-2: #475569; --kit-border: #E2E8F0; --kit-radius: 10px; --kit-shadow: 0 4px 12px rgba(0, 0, 0, 0.10); --kit-font: 'Inter', system-ui, sans-serif; /* ... 还有约30个其他变量，控制间距、动画、特殊状态色等 */ }

这套机制带来了几个革命性的优势：

1. 全局主题切换只需一行代码：想要从浅色模式切换到深色模式？不需要修改502个组件中的任何一个。你只需要在一个地方（比如一个新的<style>块或CSS文件）重新定义这些变量。例如，覆盖--kit-bg: #0F172A;和--kit-text: #F1F5F9;，整个组件库的颜色会瞬间随之改变。这使得创建多主题（如企业品牌色、节日主题）变得异常简单。

2. 保持视觉一致性，杜绝硬编码：所有组件都引用这些变量，而不是具体的色值或尺寸。这强制了整个系统在设计上保持高度一致。一个按钮的圆角、一个卡片的阴影、一段正文的颜色，全部同源。AI在生成或修改组件时，也被引导去使用这些变量，从而保证了输出结果在视觉上是和谐统一的。

3. 为AI提供明确的“设计约束”：在AI-AGENT.md文件中，我们会详细列出所有可用的--kit-*变量及其用途。这相当于给了AI一本“设计系统使用手册”。AI知道它只能在这个调色板和规则集内进行创作，从而避免了天马行空、不符合品牌规范的输出。它不是在“自由创作”一个UI，而是在一个成熟的“设计语言体系”内进行“合规组装”。

实操心得：在定义这套变量时，我刻意避免了像--color-gray-500这样过于具体的命名，而是采用了--kit-surface、--kit-text-2这类语义化命名。这能更好地引导AI（和人）理解这个变量的用途（这是用于表面背景的，这是用于次级文本的），而不是去记忆一个色值编号。这对于后续的主题切换和品牌适配至关重要。

3. 项目结构与内容深度解析

DesignKit的仓库结构经过精心设计，旨在同时满足人类浏览和AI程序化读取的需求。它不是一堆杂乱无章的代码片段，而是一个有层次、有组织的设计资源库。

3.1 核心目录：组件与完整设计

DesignKit/ ├── components/ # 核心组件库 │ ├── app-mobile/ # 204个移动端组件 (iOS/Android风格) │ ├── web/ # 200个网页端组件 (响应式设计) │ └── common/ # 98个通用组件 (图标、插画、占位图) └── previews/ └── full-designs/ # 33套完整的多页面设计 ├── mobile/ # 17个完整的移动端应用设计 └── web/ # 16个完整的网页端应用设计

components/目录是构建的基石。里面的每个HTML文件都是一个独立、完整的UI单元。例如，components/web/card-stat.html可能就是一个展示统计数据的卡片，包含了所有HTML结构和内联样式。这种“自包含”特性意味着你可以像搭积木一样，直接复制粘贴这些代码到任何地方。

• app-mobile/：这里的组件严格遵循移动端交互习惯，考虑了状态栏、安全区域（Safe Area）、底部导航栏固定等移动端特有场景。组件的尺寸和交互反馈（如按钮按压态）都是为触摸屏优化的。
• web/：这里的组件是响应式的，使用Flexbox或Grid布局，确保从桌面到平板都有良好的适配。包含了更复杂的桌面端交互模式，如悬停（Hover）效果、多列布局等。
• common/：这里存放着与具体平台无关的资源，比如一套统一的SVG图标库、一些用于占位的品牌插画（Mockup）设备框架图。这些资源同样使用CSS变量控制颜色，确保能随主题变化。

previews/full-designs/目录是“脚手架”和“灵感库”。它展示了如何将零散的组件组合成一个真实、可用的应用界面。每个完整设计（如“金融仪表盘”）都是一个独立的文件夹，里面包含：

• tokenkit.json：该设计所使用的设计令牌的JSON表示，便于其他工具导入。
• css/tokens.css：从JSON生成的、实际作用于页面的CSS变量文件。
• index.html：一个导航画廊，展示该设计包含的所有页面截图和链接，方便快速预览。
• 各个具体页面的.html文件（如dashboard.html,settings.html）。
• Specs.md：设计说明，简要描述设计目标、交互逻辑等。

注意事项：full-designs中的页面并不是简单的组件堆砌。它们演示了布局模式、页面流和信息层级。例如，一个移动端社交应用的设计，会展示如何将顶部导航栏、动态信息流、底部Tab栏有机地组合在一起，并处理好滚动时各元素的定位关系。这是AI学习“如何组织一个完整屏幕”的绝佳教材。

3.2 AI-AGENT.md：与AI沟通的“协议文件”

这是DesignKit项目中最具创新性的部分。AI-AGENT.md不是一个简单的README，它是一个结构化的、机器可读的提示词工程（Prompt Engineering）文件。它的存在，是为了让任何AI编码助手都能瞬间理解并正确使用这个设计系统。

这份文件通常包含以下几个核心部分：

1. 设计系统概述：简要说明DesignKit是什么，它的目标和设计哲学。
2. 令牌系统全量参考：以表格形式列出所有--kit-*变量，包括名称、默认值、描述和用途示例。这是AI的“设计字典”。

   变量名	默认值	描述	用途示例
   --kit-primary	#6366F1	品牌主色，用于主要按钮、高亮链接	.btn-primary { background: var(--kit-primary); }
   --kit-bg	#FFFFFF	应用程序或页面的主要背景色	body { background: var(--kit-bg); }
   --kit-radius	10px	默认圆角半径，用于卡片、按钮、输入框	border-radius: var(--kit-radius);

3. 组件目录与命名规范：提供一个清晰的组件列表，说明components/目录下有哪些可用的“积木”，以及它们的命名方式（如card-前缀表示卡片，nav-前缀表示导航）。这帮助AI知道“工具箱里有什么”。
4. 布局模式指南：分别说明移动端和网页端的典型布局模式。例如，移动端常见“顶部状态栏+滚动内容+底部导航栏”结构，网页端仪表盘常见“侧边导航+主内容区头部+图表网格”结构。并给出对应的CSS实现提示（如使用position: fixed;、safe-area-inset等）。
5. 输出规则与质量清单：这是强制AI遵守的“生产规范”。明确要求：
   • 必须使用内联样式：所有样式写在HTML元素的style属性中，确保单个文件可独立运行。
   • 必须使用语义化HTML标签：如<header>,<main>,<article>,<button>，而非全是<div>。
   • 禁止使用JavaScript：生成的是纯静态UI。
   • 必须引用DesignKit的CSS变量：颜色、间距、圆角等必须使用var(--kit-*)，不能出现硬编码值。
   • 响应式基础：网页组件需包含基本的媒体查询（Media Query）以适应不同屏幕。
   • 文件输出格式：指定生成单个.html文件，并保存到指定目录。

有了这份文件，你给AI的指令就可以变得极其简单和强大。例如，在Claude Code或Cursor中，你可以直接输入：

请阅读本项目中的AI-AGENT.md文件，理解设计规范。然后，设计一个健康类应用的“每日饮水记录”页面。要求：移动端视图（宽度390px），使用柔和的绿色主题，包含一个环形进度条显示今日饮水目标完成度，一个历史记录列表，以及一个快速添加饮水量的按钮。将最终HTML输出到`output/hydration.html`。

AI会首先研读AI-AGENT.md，理解绿色主题对应的变量值、移动端布局约束、以及如何用现有变量构建一个环形进度条，然后生成一个完全符合设计系统、开箱即用的HTML文件。

4. 完整工作流：从想法到多框架代码

让我们通过一个具体的场景，来走一遍使用DesignKit的完整、高效的工作流。假设你要为一个新的“个人财务管理”SaaS产品制作原型。

4.1 第一步：定位与定制设计起点

你不会从零开始。首先，浏览previews/full-designs/web/目录，你会发现有一个现成的Finance Dashboard（金融仪表盘）设计。打开它的index.html，你看到了一个包含概览卡片、消费图表、最近交易列表和预算进度的完整仪表盘。

但是，你的品牌色是深蓝色，不是默认的靛蓝色。这时，DesignKit的核心优势显现。你不需要在Figma里一个个修改图层样式。你只需要做一件事：覆盖CSS变量。

在你的项目根目录创建一个theme-override.css文件，或者直接在AI指令中说明：

/* 覆盖为深蓝色品牌主题 */ :root { --kit-primary: #1e40af; /* 深蓝色 */ --kit-bg: #f8fafc; /* 更浅的背景 */ --kit-surface: #ffffff; /* 可以根据需要覆盖其他变量 */ }

然后，让AI基于这个新的变量集，重新生成或调整金融仪表盘的页面。由于所有样式都基于变量，这个改变是全局且瞬间完成的。

4.2 第二步：使用AI生成新页面或修改现有页面

现在你需要一个“账单详情”页面。你可以直接对AI发出指令：

参考`previews/full-designs/web/finance-dashboard/`的设计语言和`AI-AGENT.md`的规范，创建一个新的“Bill Detail”页面。页面应包含： 1. 一个顶部标题栏，显示账单名称和金额。 2. 一个信息卡片，展示收款方、日期、分类等详细信息。 3. 一个交易物品列表。 4. 底部有一个“标记为已支付”和“导出PDF”的按钮组。 请使用我们刚才定义的深蓝色主题(--kit-primary: #1e40af)。输出为独立的HTML文件。

AI会基于它从现有设计中学到的布局、间距、字体层级和组件样式，结合新的需求，生成一个视觉风格完全统一的新页面。你无需描述“按钮应该多大圆角”、“阴影用多深”，因为这些规则已经在设计系统中定义好了。

4.3 第三步：将HTML原型转换为实际框架代码

这是工作流的收尾阶段，也是价值最大化的阶段。你现在拥有了一套高保真、可交互的HTML原型。接下来，你可以将其转化为你技术栈中的真实组件。

以转换为React + Tailwind CSS为例：你不再需要对着设计稿或模糊描述来编写组件。你有了确切的HTML结构和内联样式。你可以对AI说：

请将下面这个HTML卡片组件转换为一个React函数组件，使用Tailwind CSS进行样式化。注意保持原有的视觉外观和布局。

然后粘贴上DesignKit生成的某个卡片组件的HTML代码。AI可以非常准确地将内联样式映射为对应的Tailwind CSS类名（例如，style="border-radius: var(--kit-radius);"可以转换为className="rounded-lg"，前提是你的Tailwind配置中的lg值匹配--kit-radius）。由于结构清晰，它也能正确地拆分出JSX中的动态部分作为props。

转换为其他框架的指令示例：

• Vue 3：“将这个页面布局转换为一个使用<script setup>语法和组合式API的Vue 3单文件组件。”
• SwiftUI：“将这个设置项列表的HTML结构转换为一个SwiftUI的List视图，使用适当的SwiftUI修饰符实现分隔线和点击效果。”
• Flutter：“将这个数据统计仪表盘转换为一个Flutter Widget，使用Container、Row、Column和BoxDecoration来复现样式。”

实操心得：在转换过程中，一个常见的挑战是CSS变量到框架特定样式系统的映射。我的建议是，在转换指令中附带一份简单的“映射表”给AI参考。例如：“在我们的项目中，--kit-spacing-unit对应Tailwind的4（即1单位=1rem），--kit-primary对应我们Tailwind配置中的primary-600。”这能极大提高转换的准确性。

5. 常见问题、避坑指南与进阶技巧

在实际使用和推广DesignKit的过程中，我积累了一些宝贵的经验教训和技巧，希望能帮你绕过我踩过的坑。

5.1 与AI协作时的典型问题与排查

问题1：AI生成的代码没有使用CSS变量，而是硬编码了样式。

• 原因：AI可能没有充分“理解”AI-AGENT.md中关于必须使用变量的强制要求，或者它在训练数据中更习惯于输出具体的样式值。
• 解决方案：
  1. 强化提示词：在指令中明确强调“所有颜色、间距、圆角、阴影必须使用DesignKit的CSS自定义属性（如var(--kit-primary)），严禁使用硬编码的十六进制色值或像素值。”
  2. 提供反面教材：在AI-AGENT.md的“输出规则”部分，可以增加一个“错误示例”区块，展示一段使用了硬编码样式的代码，并注释说明为什么这是错的。
  3. 事后检查与修正：可以要求AI在生成代码后，自行检查一遍并列出所有使用的var(--kit-*)变量，确保没有遗漏。

问题2：移动端组件在生成时忽略了安全区域（Safe Area）。

• 原因：AI可能对移动端Web开发的特定需求（如iPhone的刘海屏）不敏感。
• 解决方案：
  1. 在AI-AGENT.md的“移动端布局模式”中明确写出：对于需要全屏或固定定位的元素（如底部导航栏），样式应包含padding-top: env(safe-area-inset-top);或padding-bottom: env(safe-area-inset-bottom);。
  2. 提供样板代码：直接给出一个包含安全区域处理的<header>或<footer>的HTML片段作为参考。
  3. 使用现有组件作为参考：指令中可以写明“请参考components/app-mobile/nav-bottom-fixed.html中处理底部安全区域的方式”。

问题3：生成的复杂布局（如仪表盘网格）在响应式表现上不佳。

• 原因：AI可能生成了固定像素宽度或使用了不灵活的布局方式。
• 解决方案：
  1. 规定布局工具：在规范中明确推荐使用CSS Grid或Flexbox进行布局，并禁止使用float或过时的表格布局。
  2. 提供响应式断点参考：在AI-AGENT.md中定义几个基本的响应式断点（如768px,1024px）以及对应的布局调整建议（例如“在移动端单列排列，在平板端两列，在桌面端四列”）。
  3. 先求正确，再求优化：可以先让AI生成一个桌面端布局，然后通过后续指令让其添加媒体查询来实现响应式。将复杂任务拆解。

5.2 维护与扩展DesignKit的实用技巧

1. 如何添加新的组件？保持一致性是关键。新建一个.html文件时：

• 命名规范：使用[类型]-[描述].html的格式，如card-pricing-tier.html,avatar-group-stacked.html。
• 样式内联：所有样式必须内联在元素的style属性中。
• 全面使用变量：检查每一个color,padding,margin,border-radius,font-size，确保它们都引用了--kit-*变量。绝对不要出现#fff或16px这样的值。
• 添加注释：在文件开头用HTML注释简要说明组件的用途和主要结构，方便他人和AI理解。
• 更新索引：记得在AI-AGENT.md的组件列表部分，添加这个新组件的名称和简短描述。

2. 如何创建一套新的主题预设？主题预设是快速切换风格的神器。我建议在项目根目录创建一个themes/文件夹，里面存放不同的CSS文件，如theme-finance-dark.css,theme-health-light.css。 每个主题文件只做一件事：重新定义:root下的CSS变量集合。例如，theme-finance-dark.css可能将--kit-bg设为深灰色，--kit-primary设为金色。在AI-AGENT.md中，你可以直接告诉AI：“要使用金融深色主题，请在生成的HTML文件头部引入../themes/theme-finance-dark.css。”

3. 与现有设计工具（如Figma）的协作流DesignKit并非要取代Figma，而是互补。一个高效的流程是：

• 在Figma中完成高保真视觉探索和复杂交互设计。Figma在探索阶段有无与伦比的优势。
• 当视觉风格确定后，将核心的设计令牌（颜色、字体、间距等）提取出来，映射到DesignKit的--kit-*变量体系中。你可以手动创建，也可以尝试使用Figma插件导出为CSS变量格式。
• 使用DesignKit和AI，基于确定的设计令牌，快速生成大量中低保真的页面原型和组件变体。这个阶段追求的是速度和结构，而不是像素级的完美。
• 将生成的HTML作为开发参考，或直接转换为框架代码。对于开发人员来说，一份真实的HTML代码比一张静态设计图包含更多布局和结构信息。

5.3 性能与可访问性考量

性能：由于所有样式都是内联的，对于单个页面或原型来说，这避免了额外的HTTP请求，加载很快。但如果是大型应用，内联样式会导致HTML文件体积增大，且样式无法被浏览器缓存。这正是DesignKit的定位：它是原型工具和生产代码的“中间件”。你用它快速生成和验证设计，然后通过转换步骤，将其变成使用外部CSS或CSS-in-JS的生产代码，从而解决性能问题。

可访问性：在AI-AGENT.md中，我强烈建议加入可访问性规则：

• 要求AI为所有图片添加alt属性。
• 要求按钮使用<button>标签，而非<div>模拟。
• 要求表单控件有对应的<label>。
• 确保颜色对比度符合WCAG标准（可以通过在CSS变量定义时选择对比度足够的颜色来从源头保证）。 通过在这些规则上约束AI，可以确保生成的原型不仅好看，也具备良好的可访问性基础。

开源DesignKit的初衷，是希望将我从无数次低效的“描述-调整-再描述”循环中解放出来的经验，固化成一套可复用的工具。它本质上是一套精心编排的“设计语言”和与AI沟通的“协议”。当你把明确的设计规则交给AI时，它就不再是一个难以捉摸的黑盒，而是一个高效、听话的协作者。这个项目还在成长，我非常期待看到社区用它创造出什么，无论是新的组件、更酷的主题，还是与不同框架集成的惊艳案例。