前端开发 | Hagicode Docs

Design.md：让 AI 一致性进行前端 UI 设计的解决方案

Apr 8, 2026

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 Gallery 首页概览

分析

在动手写代码之前，我们先来拆解一下这个问题的几个技术挑战。

内容源管理：如何统一分散的设计资源？

上游的 awesome-design-md 仓库包含了大量设计文档，但我们需要一种方式把它纳入到我们的项目中。

方案：使用 git submodule

awesome-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
生成标准化的条目数据

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
}

静态站点架构：怎么在保持静态部署的同时提供动态搜索？

既然是设计画廊，搜索功能是必须的。但 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 理解并遵守设计规范？

这是整个方案的核心。我们需要创建一份结构化的 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. 内容摄取管线

这是整个系统的基础，负责从上游资源中提取和标准化内容。

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. 画廊浏览界面

画廊界面包括三个主要部分：

首页：展示所有设计条目的卡片网格，每个卡片包含：

设计条目标题和简介
预览图（如果有）
快速搜索高亮

详情页：聚合展示单个设计条目的完整信息：

README 文档
DESIGN 文档
预览（支持明/暗主题切换）
相邻条目导航

导航：支持返回画廊、浏览相邻条目

首页画廊使用高密度卡片布局，把不同来源的 design.md 条目平铺在一个统一的视觉框架里，方便快速对比品牌风格、按钮模式和排版节奏。

Awesome Design MD Gallery 设计卡片网格

进入具体条目后，详情页会把设计摘要和实时预览放在同一个页面中，减少在文档、预览和源码之间来回切换的成本。

Awesome Design MD Gallery 设计详情预览页

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）

这是整个方案的核心输出。我们在项目根目录创建 design.md，结构如下：

除了给 AI 消费的原始 design.md 内容，我们还把 README 和 DESIGN 两份文档放进同一个阅读界面，方便人工校对、复制片段和对照预览结果。

Awesome Design MD Gallery 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 使用指南

创建 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 许可协议。转载请注明出处!