Design.md让 AI 一致性进行前端 UI 设计的解决方案在 AI 辅助前端开发时代如何让 AI 生成的 UI 保持一致性本文分享了我们基于 awesome-design-md 构建设计画廊站点的实践经验以及如何创建结构化的 design.md 来指导 AI 进行规范化的 UI 设计。背景用过 AI 写前端代码的朋友应该都有过类似的经历同一个页面让 AI 多生成几次每次的风格都不一样。有时候是圆角有时候是方角有时候间距是 8px 有时候又变成 16px甚至同一个按钮在不同对话里长得都不一样。这不仅仅是个别现象。随着 AI 辅助开发的普及AI 生成的前端 UI 缺乏一致性已经成为一个普遍问题。不同的 AI 助手、不同的提示词甚至同一助手在不同对话中都会产生风格迥异的界面设计。这给产品迭代带来了巨大的维护成本。问题的根源其实很简单缺少一份权威的设计参考文档。传统的 CSS 样式文件只能告诉开发者怎么实现却无法完整传达为什么这样设计以及在什么场景下使用什么设计模式。而对于 AI 来说它更需要一个清晰的结构化描述来理解设计规范。与此同时开源社区已经有了一些很好的资源。VoltAgent/awesome-design-md 项目收集了大量知名公司的设计系统文档每个目录包含 README.md、DESIGN.md 和预览 HTML。但这些都分散在上游仓库中难以快速查阅和比较。那能不能把这些资源整合起来做成一个方便查阅的设计画廊同时沉淀出一份结构化的 design.md 给 AI 用呢答案是肯定的。接下来分享一下我们的方案。关于 HagiCode本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 辅助开发平台在开发过程中我们也遇到了 AI 生成 UI 不一致的问题。为了解决这个问题我们构建设计画廊站点并创建规范化的 design.md本文就是这套方案的总结。GitHub - HagiCode-org/site先看一眼最终做出来的首页效果。首页把设计画廊入口、站点仓库、上游仓库和 HagiCode 的背景介绍收拢在同一个界面里方便团队先建立统一上下文再继续阅读具体条目。分析在动手写代码之前我们先来拆解一下这个问题的几个技术挑战。内容源管理如何统一分散的设计资源上游的 awesome-design-md 仓库包含了大量设计文档但我们需要一种方式把它纳入到我们的项目中。方案使用 git submoduleawesome-design-md-site └── vendor/awesome-design-md # 上游资源git submodule这样做有几个好处版本可控可以锁定特定的上游版本离线构建不需要在构建时请求外部 API内容审阅可以在 PR 中看到具体变更数据标准化不同文档结构怎么统一不同公司的设计文档结构可能不同有些缺少预览文件有些命名不统一。我们需要在构建期进行标准化处理。方案构建期扫描并生成标准化条目核心模块是awesomeDesignCatalog.ts负责扫描vendor/awesome-design-md/design-md/*目录校验每个条目是否包含必需文件README.md、DESIGN.md、至少一个预览文件提取并渲染 Markdown 内容为 HTML生成标准化的条目数据// src/lib/content/awesomeDesignCatalog.tsexportinterfaceDesignEntry{slug:string;title:string;summary:string;readmeHtml:string;designHtml:string;previewLight?:string;previewDark?:string;searchText:string;}exportasyncfunctionscanSourceEntries(){// 扫描 vendor/awesome-design-md/design-md/*// 校验文件完整性// 生成标准化条目}exportasyncfunctionnormalizeDesignEntry(dir:string){// 提取 README.md、DESIGN.md// 解析预览文件// 渲染 Markdown 为 HTML}静态站点架构怎么在保持静态部署的同时提供动态搜索既然是设计画廊搜索功能是必须的。但 Astro 是静态站点生成器怎么实现实时搜索呢方案React island URL 查询参数同步// src/components/gallery/SearchToolbar.tsxexportfunctionSearchToolbar(){const[query,setQuery]useState();// URL 同步useEffect((){constparamsnewURLSearchParams(window.location.search);setQuery(params.get(q)||);},[]);// 实时过滤constfilteredentries.filter(entryentry.searchText.includes(query));returninput value{query}onChange{e{setQuery(e.target.value);updateURL(e.target.value);}}/;}这样做的好处是保留了静态站点的可部署性可以部署到任何静态托管服务同时提供了即时过滤的用户体验。设计文档化怎么让 AI 理解并遵守设计规范这是整个方案的核心。我们需要创建一份结构化的 design.md让 AI 能够理解并应用我们的设计规范。方案借鉴 ClickHouse DESIGN.md 的结构ClickHouse 的 DESIGN.md 是一个很好的参考它包含了Visual Theme AtmosphereColor Palette RolesTypography RulesComponent StylingsLayout PrinciplesDepth ElevationDo’s and Don’tsResponsive BehaviorAgent Prompt Guide我们的做法是结构参考内容重写。保留 ClickHouse DESIGN.md 的章节结构但把内容替换成我们自己项目实际使用的设计 token 和组件规范。解决基于上述分析我们的解决方案包含四个核心模块。1. 内容摄取管线这是整个系统的基础负责从上游资源中提取和标准化内容。// src/lib/content/awesomeDesignCatalog.tsexportasyncfunctionscanSourceEntries():PromiseDesignEntry[]{constdesignDirvendor/awesome-design-md/design-md;constentries:DesignEntry[][];for(constdirofawaitfs.readdir(designDir)){constentryPathpath.join(designDir,dir);if(awaitisValidDesignEntry(entryPath)){constentryawaitnormalizeDesignEntry(entryPath);entries.push(entry);}}returnentries;}asyncfunctionisValidDesignEntry(dir:string):Promiseboolean{constrequiredFiles[README.md,DESIGN.md];for(constfileofrequiredFiles){if(!(awaitfileExists(path.join(dir,file)))){returnfalse;}}returntrue;}2. 画廊浏览界面画廊界面包括三个主要部分首页展示所有设计条目的卡片网格每个卡片包含设计条目标题和简介预览图如果有快速搜索高亮详情页聚合展示单个设计条目的完整信息README 文档DESIGN 文档预览支持明/暗主题切换相邻条目导航导航支持返回画廊、浏览相邻条目首页画廊使用高密度卡片布局把不同来源的 design.md 条目平铺在一个统一的视觉框架里方便快速对比品牌风格、按钮模式和排版节奏。进入具体条目后详情页会把设计摘要和实时预览放在同一个页面中减少在文档、预览和源码之间来回切换的成本。3. 搜索功能搜索功能基于客户端过滤使用 URL 查询参数保持状态// src/components/gallery/SearchToolbar.tsxfunctionSearchToolbar({entries}:{entries:DesignEntry[]}){const[query,setQuery]useState();const[results,setResults]useState(entries);useEffect((){constparamsnewURLSearchParams(window.location.search);constinitialQueryparams.get(q)||;setQuery(initialQuery);filterEntries(initialQuery);},[]);constfilterEntries(searchQuery:string){constfilteredentries.filter(entryentry.searchText.toLowerCase().includes(searchQuery.toLowerCase()));setResults(filtered);};consthandleChange(e:React.ChangeEventHTMLInputElement){constvaluee.target.value;setQuery(value);filterEntries(value);// 更新 URL不触发页面刷新constnewUrlvalue?${window.location.pathname}?q${encodeURIComponent(value)}:window.location.pathname;window.history.replaceState({},,newUrl);};return(div classNamesearch-toolbarinput typetextvalue{query}onChange{handleChange}placeholder搜索设计条目.../span classNameresult-count{results.length}个结果/span/div);}4. 设计参考文档design.md这是整个方案的核心输出。我们在项目根目录创建design.md结构如下除了给 AI 消费的原始design.md内容我们还把 README 和 DESIGN 两份文档放进同一个阅读界面方便人工校对、复制片段和对照预览结果。# Design Reference for [Project Name] ## 1. Visual Theme Atmosphere - 整体风格描述 - 设计哲学和原则 ## 2. Color Palette Roles - 主色调、辅助色 - 语义化颜色success、warning、error - CSS Variables 定义 ## 3. Typography Rules - 字体家族 - 字号层级h1-h6, body, small - 行高和字重 ## 4. Component Stylings - 按钮样式规范 - 表单组件样式 - 卡片和容器样式 ## 5. Layout Principles - 间距系统 - 网格和断点 - 对齐原则 ## 6. Depth Elevation - 阴影层级 - z-index 规范 ## 7. Dos and Donts - 常见错误和正确做法 ## 8. Responsive Behavior - 断点定义 - 响应式适配规则 ## 9. Agent Prompt Guide - 如何将本文档用于 AI 提示词 - 示例提示词模板实践了解了方案之后具体怎么实施呢实施步骤第一步初始化子模块# 添加上游仓库为子模块gitsubmoduleaddhttps://github.com/VoltAgent/awesome-design-md.git vendor/awesome-design-md# 初始化并更新子模块gitsubmodule update--init--recursive第二步创建内容管线实现awesomeDesignCatalog.ts包括文件扫描和校验逻辑Markdown 渲染使用 Astro 的内置渲染器条目数据提取第三步构建画廊 UI使用 Astro React Islands 创建首页画廊布局卡片网格设计卡片组件搜索工具栏详情页布局第四步编写设计文档基于 ClickHouse DESIGN.md 结构填充自己项目的实际设计 token。更新 README.md添加指向 design.md 的链接。注意事项安全性Markdown 渲染需要过滤不安全的 HTML。Astro 的内置渲染器默认会过滤 script 标签但仍需注意 XSS 风险。性能大量 iframe 预览可能影响首屏加载。建议使用loadinglazy延迟加载预览内容。维护性design.md 需要与代码实现保持同步。建议在 CI 中添加检查确保 CSS 变量在文档和代码中一致。可访问性确保颜色对比度符合 WCAG AA 标准至少 4.5:1。AI 使用指南创建 design.md 之后怎么让 AI 真正用它呢这里有几个实用技巧技巧一在提示词中明确引用请参考项目根目录的 design.md 文件使用其中定义的设计规范来实现以下组件 - 按钮使用 primary 色调圆角 8px - 卡片使用 elevation-2 阴影层级技巧二要求 AI 引用具体的 CSS 变量实现一个导航栏要求 - 背景色使用 --color-bg-primary - 边框使用 --color-border-subtle - 文字使用 --text-color-primary技巧三在系统提示词中包含 design.md 内容如果你的 AI 工具支持自定义系统提示词可以将 design.md 的核心内容直接添加进去。测试策略内容管线测试文件缺失场景缺少 README.md 或 DESIGN.md格式错误场景Markdown 解析失败空目录场景搜索功能测试空结果处理特殊字符如中文、emojiURL 同步验证UI 组件测试明/暗主题切换响应式布局预览加载状态部署流程# 1. 更新子模块到最新版本gitsubmodule update--remote# 2. 重新构建站点npmrun build# 3. 部署静态资源npmrun deploy建议将子模块更新和构建部署自动化可以在上游仓库更新时自动触发 CI 流程。总结HagiCode 在开发过程中遇到的 AI 生成 UI 不一致问题本质上是缺少结构化的设计参考文档。通过构建设计画廊站点和创建规范化的 design.md我们成功解决了这个问题。这套方案的核心价值在于统一资源整合分散的设计系统文档结构化规范将设计规范以 AI 可理解的形式呈现持续维护通过 git submodule 保持内容更新如果你也在使用 AI 辅助前端开发建议尝试一下这个方案。创建一份结构化的 design.md不仅能提升 AI 生成代码的一致性也能帮助团队内部保持设计规范的统一。参考资料VoltAgent/awesome-design-md - 设计系统文档集合ClickHouse DESIGN.md - 设计文档结构参考Astro 官方文档 - 静态站点生成框架HagiCode 源码 - 本方案的实际实现如果本文对你有帮助点个赞让更多人看到来 GitHub 给个 Stargithub.com/HagiCode-org/site访问官网了解更多hagicode.com观看 30 分钟实战演示www.bilibili.com/video/BV1pirZBuEzq/一键安装体验docs.hagicode.com/installation/docker-composeDesktop 桌面端快速安装hagicode.com/desktop/公测已开始欢迎安装体验原文与版权说明感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。本文作者: newbe36524原文链接: https://docs.hagicode.com/go?platformcsdntarget%2Fblog%2F2026-04-08-design-md-consistent-ui%2F版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!