AI一致性前端UI设计解决方案：Design.md实战指南

Design.md：构建 AI 驱动前端 UI 一致性的结构化方案

AI 辅助前端开发中，生成 UI 的一致性始终是核心痛点。一份结构化的 design.md 能从根本上解决这个问题。本文基于我们搭建设计画廊站点的实战经验，阐述如何将零散的设计规范整合为一份 AI 可解析的“设计宪法”。

深度使用 AI 编写前端代码的开发者，大概率经历过这种挫败感：同一页面需求，连续生成几次，每次输出的风格天差地别。圆角半径从 4px 跳到 20px，间距从 8px 变成 24px 已是常态，同一个按钮在不同会话中看起来像出自两个设计团队。这并非个别现象——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。本文是对该方案的完整复盘。

先看最终首页效果。首页将设计画廊入口、站点仓库、上游仓库和 HagiCode 背景信息汇聚在同一界面，帮助团队先建立统一上下文，再深入阅读具体条目。

分析

动手编码之前，先拆解这个问题的几个技术难点。

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

上游 awesome-design-md 仓库虽然包含大量设计文档，但需要一种方式将其纳入自身项目。方案很直接：使用 git submodule。

awesome-design-md-site
└── vendor/awesome-design-md          # 上游资源（git submodule）

这么做有几个实质性收益：版本可控，可锁定特定上游版本；离线构建，无需构建时请求外部 API；内容审阅更便捷，能在 PR 中看到具体变更。

数据标准化：不同文档结构如何统一？

不同公司的设计文档结构五花八门，有的缺少预览文件，有的命名不规范。我们需要在构建期进行标准化处理。核心方案是构建期扫描并生成标准化条目。核心模块叫 awesomeDesignCatalog.ts，负责扫描目录、校验文件完整性、提取并渲染 Markdown 内容为 HTML，最终生成标准化条目数据。

// src/lib/content/awesomeDesignCatalog.ts

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 查询参数同步。这样做的好处很明显：保留静态站点的可部署性，能直接部署到任何静态托管服务，同时提供即时过滤的用户体验。

// src/components/gallery/SearchToolbar.tsx

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  {
    setQuery(e.target.value);
    updateURL(e.target.value);
  }} />;
}

设计文档化：如何让 AI 理解并遵守设计规范？

这才是整个方案的核心。我们需要创建一份结构化的 design.md，让 AI 能够理解并应用我们的设计规范。用什么模板？借鉴 ClickHouse DESIGN.md 的结构。ClickHouse 的这份文档是一个很好的参考，它包含了 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. 内容摄取管线

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

// src/lib/content/awesomeDesignCatalog.ts

export async function scanSourceEntries(): Promise {
  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 {
  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 条目平铺在一个统一的视觉框架中，方便快速对比品牌风格、按钮模式和排版节奏。

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

3. 搜索功能

搜索功能基于客户端过滤，使用 URL 查询参数保持状态。代码实现上，通过 useState 管理查询状态，通过 useEffect 从 URL 初始化，过滤后更新 URL 但不触发页面刷新。

// src/components/gallery/SearchToolbar.tsx

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) => {
    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 (
    

      
      {results.length} 个结果
    
  );
}

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 使用指南

创建了 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 生成代码的一致性，也能帮助团队内部保持设计规范的高度统一。