Design.md：让 AI 一致性进行前端 UI 设计的解决方案
Design.md：让 AI 一致性进行前端 UI 设计的解决方案
Section titled “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
Section titled “关于 HagiCode”本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 辅助开发平台，在开发过程中，我们也遇到了 AI 生成 UI 不一致的问题。为了解决这个问题，我们构建设计画廊站点并创建规范化的 design.md，本文就是这套方案的总结。
先看一眼最终做出来的首页效果。首页把设计画廊入口、站点仓库、上游仓库和 HagiCode 的背景介绍收拢在同一个界面里，方便团队先建立统一上下文，再继续阅读具体条目。
在动手写代码之前，我们先来拆解一下这个问题的几个技术挑战。
内容源管理：如何统一分散的设计资源？
Section titled “内容源管理：如何统一分散的设计资源？”上游的 awesome-design-md 仓库包含了大量设计文档，但我们需要一种方式把它纳入到我们的项目中。
方案：使用 git submodule
awesome-design-md-site└── vendor/awesome-design-md # 上游资源（git submodule）这样做有几个好处：
- 版本可控：可以锁定特定的上游版本
- 离线构建：不需要在构建时请求外部 API
- 内容审阅：可以在 PR 中看到具体变更
数据标准化：不同文档结构怎么统一？
Section titled “数据标准化：不同文档结构怎么统一？”不同公司的设计文档结构可能不同，有些缺少预览文件，有些命名不统一。我们需要在构建期进行标准化处理。
方案：构建期扫描并生成标准化条目
核心模块是 awesomeDesignCatalog.ts，负责：
- 扫描
vendor/awesome-design-md/design-md/*目录 - 校验每个条目是否包含必需文件（README.md、DESIGN.md、至少一个预览文件）
- 提取并渲染 Markdown 内容为 HTML
- 生成标准化的条目数据
export interface DesignEntry { slug: string; title: string; summary: string; readmeHtml: string; designHtml: string; previewLight?: string; previewDark?: string; searchText: string;}
export async function scanSourceEntries() { // 扫描 vendor/awesome-design-md/design-md/* // 校验文件完整性 // 生成标准化条目}
export async function normalizeDesignEntry(dir: string) { // 提取 README.md、DESIGN.md // 解析预览文件 // 渲染 Markdown 为 HTML}静态站点架构：怎么在保持静态部署的同时提供动态搜索？
Section titled “静态站点架构：怎么在保持静态部署的同时提供动态搜索？”既然是设计画廊，搜索功能是必须的。但 Astro 是静态站点生成器，怎么实现实时搜索呢？
方案：React island + URL 查询参数同步
export function SearchToolbar() { const [query, setQuery] = useState('');
// URL 同步 useEffect(() => { const params = new URLSearchParams(window.location.search); setQuery(params.get('q') || ''); }, []);
// 实时过滤 const filtered = entries.filter(entry => entry.searchText.includes(query) );
return <input value={query} onChange={e => { setQuery(e.target.value); updateURL(e.target.value); }} />;}这样做的好处是保留了静态站点的可部署性（可以部署到任何静态托管服务），同时提供了即时过滤的用户体验。
设计文档化：怎么让 AI 理解并遵守设计规范？
Section titled “设计文档化：怎么让 AI 理解并遵守设计规范？”这是整个方案的核心。我们需要创建一份结构化的 design.md，让 AI 能够理解并应用我们的设计规范。
方案：借鉴 ClickHouse DESIGN.md 的结构
ClickHouse 的 DESIGN.md 是一个很好的参考，它包含了：
- Visual Theme & Atmosphere
- Color Palette & Roles
- Typography Rules
- Component Stylings
- Layout Principles
- Depth & Elevation
- Do’s and Don’ts
- Responsive Behavior
- Agent Prompt Guide
我们的做法是：结构参考，内容重写。保留 ClickHouse DESIGN.md 的章节结构，但把内容替换成我们自己项目实际使用的设计 token 和组件规范。
基于上述分析，我们的解决方案包含四个核心模块。
1. 内容摄取管线
Section titled “1. 内容摄取管线”这是整个系统的基础，负责从上游资源中提取和标准化内容。
export async function scanSourceEntries(): Promise<DesignEntry[]> { const designDir = 'vendor/awesome-design-md/design-md'; const entries: DesignEntry[] = [];
for (const dir of await fs.readdir(designDir)) { const entryPath = path.join(designDir, dir); if (await isValidDesignEntry(entryPath)) { const entry = await normalizeDesignEntry(entryPath); entries.push(entry); } }
return entries;}
async function isValidDesignEntry(dir: string): Promise<boolean> { const requiredFiles = ['README.md', 'DESIGN.md']; for (const file of requiredFiles) { if (!(await fileExists(path.join(dir, file)))) { return false; } } return true;}2. 画廊浏览界面
Section titled “2. 画廊浏览界面”画廊界面包括三个主要部分：
首页：展示所有设计条目的卡片网格，每个卡片包含：
- 设计条目标题和简介
- 预览图（如果有）
- 快速搜索高亮
详情页：聚合展示单个设计条目的完整信息：
- README 文档
- DESIGN 文档
- 预览（支持明/暗主题切换）
- 相邻条目导航
导航：支持返回画廊、浏览相邻条目
首页画廊使用高密度卡片布局，把不同来源的 design.md 条目平铺在一个统一的视觉框架里，方便快速对比品牌风格、按钮模式和排版节奏。
进入具体条目后，详情页会把设计摘要和实时预览放在同一个页面中，减少在文档、预览和源码之间来回切换的成本。
3. 搜索功能
Section titled “3. 搜索功能”搜索功能基于客户端过滤，使用 URL 查询参数保持状态：
function SearchToolbar({ entries }: { entries: DesignEntry[] }) { const [query, setQuery] = useState(''); const [results, setResults] = useState(entries);
useEffect(() => { const params = new URLSearchParams(window.location.search); const initialQuery = params.get('q') || ''; setQuery(initialQuery); filterEntries(initialQuery); }, []);
const filterEntries = (searchQuery: string) => { const filtered = entries.filter(entry => entry.searchText.toLowerCase().includes(searchQuery.toLowerCase()) ); setResults(filtered); };
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { const value = e.target.value; setQuery(value); filterEntries(value);
// 更新 URL（不触发页面刷新） const newUrl = value ? `${window.location.pathname}?q=${encodeURIComponent(value)}` : window.location.pathname; window.history.replaceState({}, '', newUrl); };
return ( <div className="search-toolbar"> <input type="text" value={query} onChange={handleChange} placeholder="搜索设计条目..." /> <span className="result-count">{results.length} 个结果</span> </div> );}4. 设计参考文档（design.md）
Section titled “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. Do's and Don'ts- 常见错误和正确做法
## 8. Responsive Behavior- 断点定义- 响应式适配规则
## 9. Agent Prompt Guide- 如何将本文档用于 AI 提示词- 示例提示词模板了解了方案之后，具体怎么实施呢？
第一步：初始化子模块
# 添加上游仓库为子模块git submodule add https://github.com/VoltAgent/awesome-design-md.git vendor/awesome-design-md
# 初始化并更新子模块git submodule 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 预览可能影响首屏加载。建议使用 loading="lazy" 延迟加载预览内容。
维护性：design.md 需要与代码实现保持同步。建议在 CI 中添加检查，确保 CSS 变量在文档和代码中一致。
可访问性：确保颜色对比度符合 WCAG AA 标准（至少 4.5:1）。
AI 使用指南
Section titled “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 解析失败）
- 空目录场景
搜索功能测试：
- 空结果处理
- 特殊字符（如中文、emoji）
- URL 同步验证
UI 组件测试：
- 明/暗主题切换
- 响应式布局
- 预览加载状态
# 1. 更新子模块到最新版本git submodule update --remote
# 2. 重新构建站点npm run build
# 3. 部署静态资源npm run deploy建议将子模块更新和构建部署自动化，可以在上游仓库更新时自动触发 CI 流程。
HagiCode 在开发过程中遇到的 AI 生成 UI 不一致问题，本质上是缺少结构化的设计参考文档。通过构建设计画廊站点和创建规范化的 design.md，我们成功解决了这个问题。
这套方案的核心价值在于：
- 统一资源：整合分散的设计系统文档
- 结构化规范：将设计规范以 AI 可理解的形式呈现
- 持续维护：通过 git submodule 保持内容更新
如果你也在使用 AI 辅助前端开发，建议尝试一下这个方案。创建一份结构化的 design.md，不仅能提升 AI 生成代码的一致性，也能帮助团队内部保持设计规范的统一。
- VoltAgent/awesome-design-md - 设计系统文档集合
- ClickHouse DESIGN.md - 设计文档结构参考
- Astro 官方文档 - 静态站点生成框架
- HagiCode 源码 - 本方案的实际实现
如果本文对你有帮助：
- 点个赞让更多人看到
- 来 GitHub 给个 Star：github.com/HagiCode-org/site
- 访问官网了解更多：hagicode.com
- 观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
- 一键安装体验：docs.hagicode.com/installation/docker-compose
- Desktop 桌面端快速安装：hagicode.com/desktop/
- 公测已开始，欢迎安装体验
感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。
- 本文作者: newbe36524
- 原文链接: https://docs.hagicode.com/blog/2026-04-08-design-md-consistent-ui/
- 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!