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 TokensJSON文件、甚至是一些专为AI定义的DSL领域特定语言。最终选择纯HTMLCSS变量这套看似“复古”的技术栈是基于以下几个深思熟虑的考量这些考量直接决定了它能否被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 InterpreterAI能立刻解析并开始工作。对于想快速上手的用户学习成本几乎为零。第四框架无关的“设计源头”。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个其他变量控制间距、动画、特殊状态色等 */ }这套机制带来了几个革命性的优势全局主题切换只需一行代码想要从浅色模式切换到深色模式不需要修改502个组件中的任何一个。你只需要在一个地方比如一个新的style块或CSS文件重新定义这些变量。例如覆盖--kit-bg: #0F172A;和--kit-text: #F1F5F9;整个组件库的颜色会瞬间随之改变。这使得创建多主题如企业品牌色、节日主题变得异常简单。保持视觉一致性杜绝硬编码所有组件都引用这些变量而不是具体的色值或尺寸。这强制了整个系统在设计上保持高度一致。一个按钮的圆角、一个卡片的阴影、一段正文的颜色全部同源。AI在生成或修改组件时也被引导去使用这些变量从而保证了输出结果在视觉上是和谐统一的。为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编码助手都能瞬间理解并正确使用这个设计系统。这份文件通常包含以下几个核心部分设计系统概述简要说明DesignKit是什么它的目标和设计哲学。令牌系统全量参考以表格形式列出所有--kit-*变量包括名称、默认值、描述和用途示例。这是AI的“设计字典”。变量名默认值描述用途示例--kit-primary#6366F1品牌主色用于主要按钮、高亮链接.btn-primary { background: var(--kit-primary); }--kit-bg#FFFFFF应用程序或页面的主要背景色body { background: var(--kit-bg); }--kit-radius10px默认圆角半径用于卡片、按钮、输入框border-radius: var(--kit-radius);组件目录与命名规范提供一个清晰的组件列表说明components/目录下有哪些可用的“积木”以及它们的命名方式如card-前缀表示卡片nav-前缀表示导航。这帮助AI知道“工具箱里有什么”。布局模式指南分别说明移动端和网页端的典型布局模式。例如移动端常见“顶部状态栏滚动内容底部导航栏”结构网页端仪表盘常见“侧边导航主内容区头部图表网格”结构。并给出对应的CSS实现提示如使用position: fixed;、safe-area-inset等。输出规则与质量清单这是强制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类名例如styleborder-radius: var(--kit-radius);可以转换为classNamerounded-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协作时的典型问题与排查问题1AI生成的代码没有使用CSS变量而是硬编码了样式。原因AI可能没有充分“理解”AI-AGENT.md中关于必须使用变量的强制要求或者它在训练数据中更习惯于输出具体的样式值。解决方案强化提示词在指令中明确强调“所有颜色、间距、圆角、阴影必须使用DesignKit的CSS自定义属性如var(--kit-primary)严禁使用硬编码的十六进制色值或像素值。”提供反面教材在AI-AGENT.md的“输出规则”部分可以增加一个“错误示例”区块展示一段使用了硬编码样式的代码并注释说明为什么这是错的。事后检查与修正可以要求AI在生成代码后自行检查一遍并列出所有使用的var(--kit-*)变量确保没有遗漏。问题2移动端组件在生成时忽略了安全区域Safe Area。原因AI可能对移动端Web开发的特定需求如iPhone的刘海屏不敏感。解决方案在AI-AGENT.md的“移动端布局模式”中明确写出对于需要全屏或固定定位的元素如底部导航栏样式应包含padding-top: env(safe-area-inset-top);或padding-bottom: env(safe-area-inset-bottom);。提供样板代码直接给出一个包含安全区域处理的header或footer的HTML片段作为参考。使用现有组件作为参考指令中可以写明“请参考components/app-mobile/nav-bottom-fixed.html中处理底部安全区域的方式”。问题3生成的复杂布局如仪表盘网格在响应式表现上不佳。原因AI可能生成了固定像素宽度或使用了不灵活的布局方式。解决方案规定布局工具在规范中明确推荐使用CSS Grid或Flexbox进行布局并禁止使用float或过时的表格布局。提供响应式断点参考在AI-AGENT.md中定义几个基本的响应式断点如768px,1024px以及对应的布局调整建议例如“在移动端单列排列在平板端两列在桌面端四列”。先求正确再求优化可以先让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时它就不再是一个难以捉摸的黑盒而是一个高效、听话的协作者。这个项目还在成长我非常期待看到社区用它创造出什么无论是新的组件、更酷的主题还是与不同框架集成的惊艳案例。
DesignKit：基于CSS变量与AI协议的开源设计系统，加速原型到代码工作流
发布时间：2026/5/28 19:42:59
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 TokensJSON文件、甚至是一些专为AI定义的DSL领域特定语言。最终选择纯HTMLCSS变量这套看似“复古”的技术栈是基于以下几个深思熟虑的考量这些考量直接决定了它能否被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 InterpreterAI能立刻解析并开始工作。对于想快速上手的用户学习成本几乎为零。第四框架无关的“设计源头”。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个其他变量控制间距、动画、特殊状态色等 */ }这套机制带来了几个革命性的优势全局主题切换只需一行代码想要从浅色模式切换到深色模式不需要修改502个组件中的任何一个。你只需要在一个地方比如一个新的style块或CSS文件重新定义这些变量。例如覆盖--kit-bg: #0F172A;和--kit-text: #F1F5F9;整个组件库的颜色会瞬间随之改变。这使得创建多主题如企业品牌色、节日主题变得异常简单。保持视觉一致性杜绝硬编码所有组件都引用这些变量而不是具体的色值或尺寸。这强制了整个系统在设计上保持高度一致。一个按钮的圆角、一个卡片的阴影、一段正文的颜色全部同源。AI在生成或修改组件时也被引导去使用这些变量从而保证了输出结果在视觉上是和谐统一的。为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编码助手都能瞬间理解并正确使用这个设计系统。这份文件通常包含以下几个核心部分设计系统概述简要说明DesignKit是什么它的目标和设计哲学。令牌系统全量参考以表格形式列出所有--kit-*变量包括名称、默认值、描述和用途示例。这是AI的“设计字典”。变量名默认值描述用途示例--kit-primary#6366F1品牌主色用于主要按钮、高亮链接.btn-primary { background: var(--kit-primary); }--kit-bg#FFFFFF应用程序或页面的主要背景色body { background: var(--kit-bg); }--kit-radius10px默认圆角半径用于卡片、按钮、输入框border-radius: var(--kit-radius);组件目录与命名规范提供一个清晰的组件列表说明components/目录下有哪些可用的“积木”以及它们的命名方式如card-前缀表示卡片nav-前缀表示导航。这帮助AI知道“工具箱里有什么”。布局模式指南分别说明移动端和网页端的典型布局模式。例如移动端常见“顶部状态栏滚动内容底部导航栏”结构网页端仪表盘常见“侧边导航主内容区头部图表网格”结构。并给出对应的CSS实现提示如使用position: fixed;、safe-area-inset等。输出规则与质量清单这是强制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类名例如styleborder-radius: var(--kit-radius);可以转换为classNamerounded-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协作时的典型问题与排查问题1AI生成的代码没有使用CSS变量而是硬编码了样式。原因AI可能没有充分“理解”AI-AGENT.md中关于必须使用变量的强制要求或者它在训练数据中更习惯于输出具体的样式值。解决方案强化提示词在指令中明确强调“所有颜色、间距、圆角、阴影必须使用DesignKit的CSS自定义属性如var(--kit-primary)严禁使用硬编码的十六进制色值或像素值。”提供反面教材在AI-AGENT.md的“输出规则”部分可以增加一个“错误示例”区块展示一段使用了硬编码样式的代码并注释说明为什么这是错的。事后检查与修正可以要求AI在生成代码后自行检查一遍并列出所有使用的var(--kit-*)变量确保没有遗漏。问题2移动端组件在生成时忽略了安全区域Safe Area。原因AI可能对移动端Web开发的特定需求如iPhone的刘海屏不敏感。解决方案在AI-AGENT.md的“移动端布局模式”中明确写出对于需要全屏或固定定位的元素如底部导航栏样式应包含padding-top: env(safe-area-inset-top);或padding-bottom: env(safe-area-inset-bottom);。提供样板代码直接给出一个包含安全区域处理的header或footer的HTML片段作为参考。使用现有组件作为参考指令中可以写明“请参考components/app-mobile/nav-bottom-fixed.html中处理底部安全区域的方式”。问题3生成的复杂布局如仪表盘网格在响应式表现上不佳。原因AI可能生成了固定像素宽度或使用了不灵活的布局方式。解决方案规定布局工具在规范中明确推荐使用CSS Grid或Flexbox进行布局并禁止使用float或过时的表格布局。提供响应式断点参考在AI-AGENT.md中定义几个基本的响应式断点如768px,1024px以及对应的布局调整建议例如“在移动端单列排列在平板端两列在桌面端四列”。先求正确再求优化可以先让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时它就不再是一个难以捉摸的黑盒而是一个高效、听话的协作者。这个项目还在成长我非常期待看到社区用它创造出什么无论是新的组件、更酷的主题还是与不同框架集成的惊艳案例。
相关文章
【MATLAB】工业安全联锁与急停逻辑仿真验证
【MATLAB】工业安全联锁与急停逻辑仿真验证 摘要：现代化工、机械制造、电力传动等工业生产系统具备设备联动性强、运行工况复杂、自动化程度高的特点，设备误操作、工况超限、机械故障极易引发设备损坏、生产事故与人身安全隐患。安全联锁与急停系统是工业自动化的核心安全屏…
OpCore Simplify深度解析：智能黑苹果EFI配置的完整解决方案
OpCore Simplify深度解析：智能黑苹果EFI配置的完整解决方案 【免费下载链接】OpCore-Simplify A tool designed to simplify the creation of OpenCore EFI 项目地址: https://gitcode.com/GitHub_Trending/op/OpCore-Simplify OpCore Simplify是一款专为简化…
独立开发者如何借助 Taotoken 一站式管理多个 AI 项目的 API 密钥
🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度 独立开发者如何借助 Taotoken 一站式管理多个 AI 项目的 API 密钥 对于独立开发者而言，同时维护多个小型 AI 应用或实验…
基于Arduino的仿生机器人面部动画系统：从机械设计到控制算法全解析
1. 项目概述与核心思路做机器人，尤其是带点“生命感”的仿生机器人，一直是我业余时间最大的乐趣。这次分享的项目，是一个基于Arduino的仿生机器人面部动画系统，我把它叫做“AnimeBOT”。这个项目的核心目标很简单：让一…
OpenCV轮廓检测进阶：用cv2.findContours()实现简易车牌识别与数字仪表盘读数（Python教程）
OpenCV轮廓检测实战：从车牌识别到仪表盘读数的完整实现指南 在工业检测、智能交通和自动化控制领域，轮廓检测技术正发挥着越来越重要的作用。想象一下这样的场景：停车场自动识别系统需要快速定位车辆牌照，或是电力巡检机器人需要读…
【DeepSeek格式化黄金法则】：20年AI工程老兵亲授5大必避雷区与3步标准化落地指南
更多请点击： https://intelliparadigm.com 第一章：DeepSeek格式化黄金法则的底层逻辑与演进脉络 DeepSeek格式化黄金法则并非凭空设计的约束规范，而是源于对大语言模型推理机制、token化行为与指令微调范式的深度解构。其核心在于统一输入结…
AI建站避坑指南：10个常见问题与解决方案，帮你绕过那些看不见的坑
做网站最怕什么？怕花了钱和时间，最后出来的东西没法用，或者用起来一堆麻烦。下面这份高频问题清单和避坑指南，帮你提前预警。Q1：用AI建站，做出来的网站会不会很“模板化”，显得很low？…
终极WarcraftHelper完整指南：魔兽争霸III游戏优化工具一键配置
终极WarcraftHelper完整指南：魔兽争霸III游戏优化工具一键配置 【免费下载链接】WarcraftHelper Warcraft III Helper , support 1.20e, 1.24e, 1.26a, 1.27a, 1.27b 项目地址: https://gitcode.com/gh_mirrors/wa/WarcraftHelper WarcraftHelper是一款功能强…
【全平台通杀！】小白必看：Win/Mac/Linux 都能用的 OpenClaw 安装指南（包含安装包）
OpenClaw 一键安装：Windows/macOS/Linux 全平台 小白可用 本文为 OpenClaw v2.7.5 全平台一键安装教程，覆盖 Windows、macOS、Linux 三大系统，全程可视化、零命令行、无技术门槛，小白用户可快速完成部署，开启本地 AI …
大模型核心加速器：KV Cache 如何将 O(n²) 计算复杂度降至 O(n)？
KV Cache 是大模型自回归生成任务的关键优化技术，通过“空间换时间”策略缓存历史 Key 和 Value 向量，将推理复杂度从 O(n) 降至 O(n)。文章阐述了语义缓存与前缀精确匹配两种核心范式，深入分析了 KV Cache 的技术底层原理、工程化应用及规模…
物流系统如何打通信息孤岛？哲盟软件系统：一键打通内外部数据壁垒
在数字化转型加速的今天，物流企业面临的最大痛点之一就是信息孤岛——ERP、电商平台、智能硬件、OMS/TMS/WMS等系统各自为政，数据无法自由流转，导致人工操作繁琐、效率低下、出错率高。特别是在跨境物流领域，亚马逊、Shopee、TikT…
Windows Defender终极恢复指南：5种强力方法解决禁用问题
Windows Defender终极恢复指南：5种强力方法解决禁用问题 【免费下载链接】no-defender A slightly more fun way to disable windows defender firewall. (through the WSC api) 项目地址: https://gitcode.com/GitHub_Trending/no/no-defender 当你的Windo…
施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录
更多请点击： https://codechina.net 第一章：施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录 在华北某大型地铁盾构施工现场，一套轻量化AI Agent系统于2024年Q2完成全栈部署ÿ…
附录 B：术语表
本术语表面向“从 MM 到 HMM”专栏阅读过程中的快速查阅。它不是内核 API 手册，而是把文章中反复出现的概念放到同一张地图上：先给出直观含义，再说明它在 Linux MM/HMM 语境里的作用。建议阅读方式： 初读专栏时，把它当…
Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表·行业首曝）
更多请点击： https://kaifayun.com 第一章：Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表行业首曝） Midjourney 的渐变美学并非传统插值实现，而是由其隐式神经渲染器（Implicit Neu…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…