Article
**RICOUI DESIGN 是一个围绕 DESIGN.md 搭建的开源设计系统工作台。**你可以在网页里创建、编辑和预览设计规范，再把同一份文档转换成前端和 AI 能直接使用的 Design Tokens 与 CSS。
它适合需要整理设计规范的设计师、前端开发者，以及用 Cursor、Claude、Codex 等 AI 工具制作界面的人。
为什么是一份 DESIGN.md
设计规范经常散落在 Figma、协作文档、截图和口头约定里。人多、项目多以后，同一个颜色或圆角可能有好几个版本；把任务交给 AI 时，它拿不到完整约束，只能看着现有页面猜。
DESIGN.md 可以理解为设计系统的“可读原稿”。它是一份有固定结构的 Markdown 文档，把颜色、字体、间距、圆角、组件规则，以及该做什么、不该做什么写在一起。人可以直接阅读，程序和 AI 也能解析。
文档里的颜色、字号、间距等基础数值叫作 Token。它们相当于设计系统里的变量：品牌主色只定义一次，按钮、链接和其他组件都引用它，修改时不用到处寻找。
RICOUI DESIGN 以这份原稿为准，再从原文自动生成预览、tokens.json 和 CSS。这个过程下文简称“派生”。这样就不用同时维护 Markdown、JSON 和 CSS，避免几份规范互相对不上。
一份 DESIGN.md
↓
编辑和检查设计规则
↓
生成预览、tokens.json 和 CSS
↓
交给设计师、前端或 AI 使用这套方法不会代替 Figma、代码组件库或团队协作工具。它解决的是另一件事：给设计决策留下一份清楚、可传递、能被机器读取的来源。
从创建到导出，只要四步
网站打开就能使用，本地模式不要求注册，也不用先配置开发环境。第一次体验时，我建议先完成最短流程，不必一上来研究所有页面和设置。
第一步：选择参考，或者新建文档
你可以从空白文档开始，也可以到品牌参考库里找一套接近目标的视觉语言。品牌内容是只读参考；选择“用作模板”后，系统会复制一份新草稿，不会改动原始品牌文件。
从品牌参考开始时，完整流程是：
- 在品牌参考页找到接近目标风格的品牌。
- 打开详情，查看它的预览、
DESIGN.md、Token 和 CSS。 - 选择“用作模板”，复制到工作台继续编辑。
- 修改成自己项目的规范，再保存到设计库。
这些参考适合用来观察成熟产品怎样处理颜色、字体、间距和组件，但不代表对应品牌的官方授权。品牌规范也会持续更新，使用时仍要核对原品牌的最新资料。
第二步：编辑 DESIGN.md
编辑器提供四种查看同一份文档的方式：
| 视图 | 适合做什么 |
|---|---|
| 源码 | 编辑完整 Markdown，增加章节或调整 Token 名称 |
| 阅读 | 检查内容结构和排版 |
| 结构化 | 用颜色选择器和数值控件修改颜色、字号、间距 |
| 预览 | 查看当前规范生成的界面效果 |
不想手写 Markdown，可以直接使用结构化视图。改动会写回同一份 DESIGN.md。需要增加组件说明或自定义章节时，再切到源码视图。
一份文档不必一开始就写得很大。最小版本只需要主题和几组基础 Token：
# 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 | Page background |
| Text | #0F172A | --color-text | Primary text |
## Tokens — Typography
| Name | Value | Token | Role |
|---|---|---|---|
| Sans | Inter, system-ui, sans-serif | --font-sans | Interface |
## Components
### Button
Use the brand color for the primary action.
## Do's and Don'ts
### Do
- Keep action labels short and specific.
### Don't
- Do not place multiple primary actions in one panel.完整规范还可以继续增加字号阶梯、间距、圆角、图片风格和布局规则。项目仓库里有更完整的格式说明，第一次使用不必全部填完。
第三步：检查预览和规则
写完后先切到阅读视图检查章节，再打开预览确认颜色、字体和组件效果。如果结构化视图无法识别某一部分，先回到源码检查表格结构、Token 名称和数值。
设计规范写进文档并不代表它自动正确。工具可以检查结构和引用，但无法替你判断品牌色是否准确、字号层级是否合适。
第四步：导出给前端和 AI
文档能保存，不等于所有格式都能立即导出。工具会按照文档的完整程度逐层开放能力：
| 文档状态 | 可以做什么 |
|---|---|
| 非空的普通 Markdown | 保存、阅读、复制和下载原文 |
能被识别的 DESIGN.md | 使用结构化编辑和预览 |
| Token 名称、数值和引用通过检查 | 导出 tokens.json、CSS 和 ZIP |
所以，即使一份文档暂时通不过 Token 检查，已经写下的内容也不会丢失，仍然可以保存和下载。完成检查后，核心导出物有三类：
| 格式 | 用途 |
|---|---|
DESIGN.md | 唯一需要继续编辑的设计规范原文 |
tokens.json | 供设计工具、脚本或前端工程读取的 Token 数据 |
| CSS | 可直接进入前端项目的 CSS 变量 |
工具还支持 Tailwind CSS v4 的 theme.css 和包含多种产物的 ZIP。tokens.json 使用 DTCG 格式，也就是一套通用的 Design Token 数据结构；普通用户不需要先理解这项标准才能导出。
如果 Token 名称、数值或变量引用有问题，CSS 导出会暂停，但原始 Markdown 仍然可以保存。修正 DESIGN.md 后重新生成即可，不建议把导出的 JSON 或 CSS 当成另一份源文件单独修改。
用 AI 从网站生成初稿
不想从空白文档开始，可以输入一个公开网站地址，让 AI 分析页面并生成 DESIGN.md 初稿。
这项功能需要使用你自己的 AI API Key，操作分三步：
- 打开“设置 → AI 服务”，添加 Provider 和 API Key，再测试连接。
- 回到首页，粘贴一个公开网站地址，选择“从网址生成 DESIGN.md”。
- 等待初稿生成，检查内容和修改差异，确认后再保存。
API Key 保存在当前浏览器里，不会随着云端同步上传。
生成后重点检查品牌色、字体、Token、组件说明和来源链接。AI 对复杂布局的理解并不总是准确，它给出的是方便继续修改的初稿，不是对原网站的逐像素复制，也不代表你获得了原站品牌资产的使用权。
AI 修改文档时会先展示差异，需要你确认后才会应用。我的建议是每次只让它处理一类问题，例如“检查颜色 Token 是否重复，不改字体和间距”。范围越小，越容易判断改动是否可靠。
本地、云端和数据边界
默认使用本地模式时，草稿保存在当前浏览器的 IndexedDB 中，应用不会自动上传。刷新页面后可以继续编辑，但浏览器里的本地数据不等于永久备份，重要文档仍应及时下载保存。
需要跨设备同步、管理私有交付版本时，可以登录并按需开启云端。云端会保存账户下的文档和相关信息，但不会保存 AI API Key。具体容量和服务限制可能变化，以仓库里的最新说明为准。
项目目前标记为 Beta。云端功能适合日常使用和测试，但不应该被当作唯一备份，也不承诺企业级服务可用性。
如果想给团队部署独立实例，项目使用 Apache-2.0 许可证开源。安装依赖、配置 AI、接入 Supabase 和部署到 Vercel 的步骤已经放在仓库的中文指南里，正文不再展开。
谁值得用
设计师可以把视觉判断整理成一份有结构的规范，不写代码也能通过控件调整颜色、字号和间距，并立即检查预览。
前端开发者可以从同一份原文获得 Token 和 CSS，不必手工把设计文档再翻译一遍。规范变化后重新生成，交付物也能保持一致。
用 AI 做界面的人可以把 DESIGN.md 和 Token 文件放进项目上下文。AI 读到的是具体颜色、字体层级和组件约束，不只是“做得像某个品牌”这样的模糊要求。
如果项目只有一两个页面，也不需要长期维护视觉规范，这套工作流可能偏重。它更适合会持续迭代、有多个页面，或者需要在设计、代码和 AI 之间传递规则的项目。
我的判断
我做这个工作台，是因为手上的项目越来越多，仅靠记忆已经管不住散落的设计规则。Figma 适合设计界面，代码组件库负责实现，但它们之间仍需要一份双方都能读懂的说明。
DESIGN.md 对我最有价值的地方，不是把设计系统换成 Markdown，而是把判断写下来：为什么使用这个颜色，组件在什么场景出现，哪些做法应该避免。只记录数值，AI 和开发只能照抄；把使用边界也写清楚，规范才真的能约束输出。
RICOUI DESIGN 做的事情很具体：让这份文档更容易创建、修改、检查和交付。它不能替你做设计判断，也不会保证 AI 自动生成的结果准确，但能减少规范散落和多份文件互相冲突的问题。
第一次使用，我建议先在本地模式建一份小规范，走完“创建 → 编辑 → 预览 → 导出”四步。确定这套方法适合自己的项目后，再尝试 AI、云端同步或自行部署。
我是 Rico，可以关注公众号“Rico的设计漫想”获得及时更新。
