AI 写界面总跑偏？给它一份 Design.md 就稳了！

一、全文速览图

之前给大家分享过 68 套品牌 DESIGN 文档合集，可以打开每个品牌文件夹，看它的颜色、字体、间距、组件以及完整的视觉规范。

仓库：github.com/ricocc/brands-design-md

这套品牌库作为参考很好用，但实际拿来做项目时，我还是觉得有些麻烦。每次要先找文件、复制内容、确认结构，再慢慢改成自己的设计规范。改完以后，如果还要继续给前端或者 AI 使用，又要整理 Token、CSS 等文件。

另外，我手上的项目和站点越来越多，设计规范平时散落在 Figma、协作文档、截图和项目代码里，很多细节时间久了自己也记不住。到了用 AI 写界面这一步，这个问题更明显：AI 手里如果没有一份明确的设计约束，只能根据当前页面去猜，做着做着就很容易出现颜色、字号、圆角和组件风格不统一的问题。

所以我一直在尝试用 DESIGN.md 把这些设计规则集中起来。

也基于这个需求，我做了 RICOUI DESIGN，一个我自己在用的 DESIGN.md 设计系统工作台，项目已经开源。之前整理的品牌库，现在也是这个项目的一部分。

网站：design.ricoui.com

仓库：github.com/ricocc/ricoui-design-md

它主要做几件事：在网页里创建、编辑和预览 DESIGN.md；浏览品牌设计参考；从公开网站生成 DESIGN.md 初稿；最后再把同一份文档派生为 Design Tokens、CSS 和 ZIP，继续给前端和 AI 使用。

二、DESIGN.md 是什么

先简单解释一下这里说的 DESIGN.md。

它本质上还是一份 Markdown 文档，只是按照一定结构去记录一套设计系统。人打开可以直接阅读，AI 也能读取里面的颜色、字体、间距、组件规则和设计约束。

在 RICOUI DESIGN 里，我约定了一套固定的结构，方便编辑器识别和继续派生 Token、CSS。这里的“固定结构”是这个项目采用的设计方式，不代表 DESIGN.md 已经像 HTML、CSS 一样有完全统一的行业标准。

一个最小骨架大概长这样：

# Acme — Style Reference

> 一句话品牌调性

**Theme:** light

## Tokens — Colors

## Tokens — Typography

### Type Scale

## Tokens — Spacing & Shapes

### Spacing Scale

### Border Radius

## Components

## Do's and Don'ts

## Imagery

## Layout

骨架确定之后，每个章节各自负责一部分内容：

写 DESIGN.md 时，我比较在意下面几点：

1. Token 用 Markdown 表格存，保留 Name / Value / Token / Role，方便阅读和解析；
2. 字体直接写完整的 fallback chain，不需要另外维护一份字体清单；
3. 组件继续引用前面的 Token，而不是重新写一套颜色和尺寸；
4. Do's and Don'ts 单独保留，因为很多时候“不应该怎么设计”比单纯告诉 AI 一个数值更有用。

它和 Figma、Design Token 也不是替代关系。

Figma 仍然更适合做视觉设计和组件协作，Design Token 更适合保存颜色、字号、间距、圆角这些原子值。DESIGN.md 在我的工作流里更像一层“设计上下文”：除了告诉 AI 某个值是什么，还继续告诉它这个值应该怎么用、组件之间是什么关系，以及哪些视觉做法应该避免。

所以我现在会把 DESIGN.md 当作唯一需要维护的源文件，预览、Token、CSS 和其他交付格式都从它继续派生，而不是各自维护一份。

三、使用说明与教程

design.ricoui.com 打开浏览器就可以使用，不需要注册。AI 功能接入自己的 API Key；如果需要跨设备同步和私有交付，再登录并开启云端。

整个产品我现在主要分成两个方向去理解：一个是看，一个是做。

“看”是品牌参考库，可以拆解成熟产品的设计语言；“做”则是创建、编辑、预览和交付自己的 DESIGN.md。

示例流程：从品牌参考到自己的设计库

如果第一次用，我建议先从品牌库开始，这样比从空白文档理解 DESIGN.md 更直观。

1. 在 Brands 页面寻找喜欢的品牌

进入 brands 页面后，可以浏览已经整理好的品牌规范。这里不是只展示一张截图，而是把一个品牌对应的 DESIGN.md、Token、CSS 和视觉预览放在一起。

看到视觉方向比较接近的品牌，可以先点进去继续看。

2. 查看品牌详细信息

品牌详情页里可以查看完整规范，右上角也可以直接下载多个文件。

我觉得这种参考方式比只保存网页截图更有用。截图只能告诉我们“最后长什么样”，拆成 DESIGN.md 以后还能继续看颜色有几级、字号如何组织、间距有没有统一阶梯、组件用了哪些 Token，以及哪些规则是整个产品反复遵守的。

3. 复制到工作台编辑

如果这套规范和自己的项目比较接近，可以直接复制到工作台，再修改品牌名、颜色、字体、间距和组件规则。

不用从空白文件开始，先借一个成熟结构做起点，再慢慢改成自己的版本，会轻松很多。

4. 保存到设计库

整理完成后，可以保存到自己的设计库。草稿继续用于修改，设计库则更适合存已经相对稳定、准备长期使用的规范。

四、谁适合用，分别能拿到什么

不同身份进来，关心的东西不太一样，但最后使用的是同一份 DESIGN.md。

设计师更在意“不写代码也能精确调整视觉”。在结构化视图里，颜色有色盘，字号和间距有数值控件，改完可以直接看预览，不需要一直在 Markdown 源码里找变量。品牌库里的规范也可以直接复制成草稿，再改成自己项目的样子。

前端开发者更关心“规范怎么变成可以直接使用的代码”。一份 DESIGN.md 通过派生检查后，可以继续得到 DTCG 格式的 tokens.json、variables.css、Tailwind v4 的 theme.css 和 ZIP。这些文件都来自同一份文档，不需要另外维护。

用 AI 做界面的人更关心“怎么让 AI 真正读懂设计”。把 DESIGN.md 放进 Cursor、Claude、Codex 等项目上下文，AI 看到的是具体的颜色变量、字体层级、组件约束和 Do’s and Don’ts，而不只是“做成某个品牌风格”这种模糊描述。

五、怎么用

页面入口指引

功能按“想做什么”分布在不同页面里：

创建第一份 DESIGN.md

如果不想从品牌模板开始，也可以直接从零创建。

流程很简单：

1. 打开首页，选择“新建草稿”；
2. 在编辑器切换到“源码”视图；
3. 输入名称、描述、主题、颜色、字体、间距和组件说明；
4. 等待顶部状态显示“已保存到本机”；
5. 切到“阅读”检查排版，再用“结构化”修改具体颜色和字号，最后打开“预览”看视觉结果。

可以直接用下面这个最小骨架起步：

# Acme — Design System

> A clear design language for product interfaces.

**Theme:** light

## Tokens — Colors

| Name | Value | Token | Role |
| --- | --- | --- | --- |
| Brand | #2563EB | --color-brand | Primary actions |
| Background | #FFFFFF | --color-background | Application canvas |
| Text | #0F172A | --color-text | Primary text |

## Tokens — Typography

| Name | Value | Token | Role |
| --- | --- | --- | --- |
| Sans | Inter, ui-sans-serif, system-ui, sans-serif | --font-sans | Interface |

### Type Scale

| Role | Size | Line Height | Letter Spacing | Token |
| --- | --- | --- | --- | --- |
| Body | 16px | 1.5 | 0 | --font-size-body |

## Tokens — Spacing & Shapes

### Spacing Scale

| Name | Value | Token |
| --- | --- | --- |
| 1 | 4px | --space-1 |
| 2 | 8px | --space-2 |

### Radius Scale

| Name | Value | Token |
| --- | --- | --- |
| Medium | 8px | --radius-md |

## Components

### Button

**Role:** Primary action control.

Use the brand color for the primary state and keep one primary action per surface.

## Do's and Don'ts

### Do

- Keep action labels short and specific.

### Don't

- Do not use multiple primary actions in one panel.

不用一开始就把所有章节写完整。先建一个可以正确识别和预览的骨架，再逐项补内容，反而更容易知道是哪里出了问题。

六、用 AI 从一个网站生成 DESIGN.md

如果连第一版 DESIGN.md 都不想自己写，也可以输入一个公开网站，让 AI 先起草。

这一步需要自己的 AI Key。Key 保存在自己的浏览器里，应用不提供统一的公共 Key。

1. 配置 AI 服务

先在“设置 → AI 服务”里配置 Provider 和 Key，然后测试连接。

2. 输入品牌网站地址

在首页搜索框或全局搜索中粘贴网址，选择“从网址生成 DESIGN.md”。

3. 提取并生成

应用会先查找公开的 DESIGN.md，同时读取页面元信息、可读内容和能够提取到的样式信号，再交给模型整理。

生成完成后，需要自己检查品牌色、字体、Token、组件说明和来源链接，确认没有明显问题再保存。

这里我一直把网址生成定位成分析起点，而不是逐像素复制网页。

复杂网站背后的完整设计系统不可能只从一个页面完全还原，模型对布局和视觉层级的理解也会有误差，所以重要数值仍然需要自己确认。

安全边界也需要说明：应用会拒绝 localhost、私有 IP、带用户名密码的 URL，以及 DNS 解析到私有网络的主机。生成 DESIGN.md 也不代表获得了原网站品牌资产的授权。

七、检查、导出说明

这里有一个我比较在意的设计：一份文档“能保存”和“能正确派生 Token、CSS”是两件事。

普通 Markdown 只要有内容，就应该可以继续保存和阅读；但如果 Token 名称不合法、变量引用最终无法解析，再继续生成 CSS 就容易让人误以为结果是正确的。

所以 RICOUI DESIGN 会按照文档状态开放不同能力：

通过检查之后，可以导出：

派生的前置条件是 Token 名称和值合法，var(--token) 这类引用最终也能正确解析。

如果检查没有通过，CSS 导出会被锁住，但原始 Markdown 仍然可以继续保存和修改。这样做是为了避免导出一份彼此对不上的 CSS，还以为它就是最终结果。

要修改时，继续修改 DESIGN.md，再重新派生就可以了。不要把生成后的 JSON 或 CSS 当成另一份源继续手动维护。

八、云端服务

RICOUI DESIGN 默认以本地使用为主。没有配置云端时，应用不会自动上传草稿，本地数据保存在浏览器的 IndexedDB 中，刷新页面后仍然可以恢复。

如果开启云端，不同数据大致放在这些位置：

如果只是个人整理 DESIGN.md，本地模式已经能完成创建、编辑、预览和导出。跨设备同步、私有交付或者团队独立部署，再按需开启云端即可。

云端容量和文件大小目前也有限制，具体额度以后可能继续调整，以项目最新说明为准。比较重要的一点是：云端同步不应该被当成永久备份。 重要的 DESIGN.md 仍然建议保留本地文件，或者直接放进自己的代码仓库。

九、自己部署

在线版已经够大部分个人用户使用。

如果想要跨设备同步、私有交付版本，或者给团队部署独立实例，可以直接把项目克隆到本地。项目使用 Apache-2.0 License 开源。

最快启动只需要：

git clone https://github.com/ricocc/ricoui-design-md.git
cd ricoui-design-md
pnpm install
pnpm dev

不配置任何环境变量，也能先使用本地编辑、预览和导出。

AI、Supabase、Vercel 部署等完整配置，我都放在仓库 /GUIDE 目录里，需要哪部分能力再继续配置，不需要第一次使用时全部打开。

十、我的设计思路

我一直在尝试以 DESIGN.md 为核心去维护产品和品牌的视觉文档。现在自己的项目基本都会配一套 DESIGN.md，把设计规范整理清楚，一方面给自己和前端看，另一方面也直接给 AI 读取。

它解决的并不是 Figma 不够用，而是项目里缺少一份可以长期保留、能跟代码放在一起、又方便 AI 读取的设计上下文。

我觉得 DESIGN.md 最有用的地方，也不是单纯把 Token 再写一遍。

最底层的颜色、字体、间距、圆角当然很重要，但 AI 真正做界面时，还需要知道这些值怎么组合，组件应该在什么场景出现，以及哪些做法应该避免。所以除了 Tokens，我还会继续写 Components 和 Do’s and Don’ts。

比如：

### Do

- 保持大面积留白。
- 一屏只保留一个主要操作。
- 产品截图优先于无意义的装饰插图。

### Don't

- 不随意增加新的强调色。
- 不同时出现多个主要按钮。
- 不为了填满页面而增加装饰元素。

这些内容没办法直接变成 CSS，但在实际 AI Coding 里很有用。它们描述的是“这个产品应该继续怎么设计”，而不只是“目前用了哪些值”。

RICOUI DESIGN 这个工作台，就是为了让我维护这些文档时更方便。

前面提到的“看”和“做”，其实也是整个产品现在最核心的两个部分。

看，是浏览和参考。品牌库把成熟产品的 DESIGN.md、Token、CSS 和预览放在一起，可以拆开看别人怎么处理颜色、Typography、Spacing 和 Components，也可以直接复制成自己的草稿。

做，是创建、编辑和交付。从零写、从品牌模板开始，或者让 AI 从网站先生成都可以。后续修改仍然围绕同一份 DESIGN.md 完成，再继续派生 Token、CSS 和 ZIP。

这样设计师不需要放弃 Figma，前端也不需要换一套开发方式，只是在两者之间多了一份更适合项目长期保存，也更适合 AI 阅读的设计规范。

十一、最后

这个网站最开始就是为了解决我自己关于 DESIGN.md 的使用需求，目前项目还是 Beta。

内置品牌参考只作为学习和设计参考，不代表品牌官方规范。品牌本身也会持续更新设计，这边没办法保证及时同步每一次变化。

如果第一次体验，我建议先走最简单的一条路径：去 Brands 找一套接近的参考，复制到工作台，改几个颜色、字体和组件，再看预览和导出结果。跑通这一步之后，再决定要不要继续使用 AI、云端同步或者自己部署。

1. 网站：design.ricoui.com
2. 仓库：github.com/ricocc/ricoui-design-md

有兴趣的话，我之后会继续分享这个产品的设计和开发流程，以及技术栈选择过程中踩过的一些坑。

文章中的截图样机美化，是用了自己近期开发的另一个网站 shot.ricoui.com， 也是开源的，有需要的话可以体验一下