DESIGN.md 使用指南：4 条命令让 AI 生成的界面遵循同一套设计

DESIGN.md 使用指南：4 条命令让 AI 生成的界面遵循同一套设计

【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md

DESIGN.md 是谷歌开源的一份格式规范，用一份纯文本 Markdown 把配色、字体、圆角、间距和组件这些设计信息完整地交给 AI 编码代理，让它在不同会话、不同工具里生成界面时都遵循同一套设计系统。

为什么每次生成的界面都不一样

你让 AI 写前端，让它"现代、干净、高级"。第一次生成还行，换个会话，配色、字号、圆角全变了，前后两个页面像两个产品。更麻烦的是，你的品牌规范锁在 Figma 或 PDF 手册里，代理压根读不到。

说白了，问题不在 AI 不会写界面，而在于它每次都在"裸考"——手里没有一份它读得懂的、关于你品牌的事实源。

DESIGN.md 只干一件事：给代理一份读得懂的说明单

这个项目的核心，就是把整套视觉识别写成一份代理能直接读的纯文本文档，人和模型都能看、能改、能校验。

它的边界也划得很清楚。DESIGN.md 只描述"长什么样"：颜色、字体、形状、组件这些视觉事实；它不替你实现界面，不碰后端逻辑，也不做 Figma 那种可视化编辑。你写清楚，它就照着生成。

一个文件里，数值和理由怎么分工

DESIGN.md 由两段拼成。文件顶部---之间是设计令牌（design tokens），机器读的是精确数值：哪个颜色、什么字号、多大圆角；##小节里是叙述文字，给模型读的是上下文：为什么是这个值、该用在哪儿。

令牌组各管一摊，取值形式也不一样，整理成一张表：

一个最小可运行的长这样：

--- name: Heritage colors: primary: "#1A1C1E" tertiary: "#B8422E" typography: h1: fontFamily: Public Sans fontSize: 3rem ---

代理读到它，就知道标题用 Public Sans、主色是深墨、交互色是那块陶土红。组件还能用引用把值串起来，比如按钮的backgroundColor直接指向{colors.primary}，改一处，全局跟着变。正文小节也有固定顺序：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts，可以省，但不能乱。

一条命令，校验整份规范

上手最快的路径就是跑校验。仓库随规范发了 npm 包@google/design.md，零安装直接跑：

npx @google/design.md lint DESIGN.md

拿仓库里任意一份示例文件跑，你会看到一段结构化 JSON：findings数组里每条发现带 severity、path、message，summary汇总 errors、warnings、infos 三个数。这套校验能揪出断裂的令牌引用、缺 primary 主色、WCAG AA 对比度低于 4.5:1、孤儿令牌、章节顺序错了，甚至能认出colours:这种拼写手误。一旦发现 error，退出码就是 1，正好能接进 CI 当质量门禁。

除了 lint，还有三个命令

校验只是起点。diff拿两份文件比令牌级变化，改版时能看出哪个颜色动了、是不是回归；export把令牌导成 Tailwind v3 的 JSON、Tailwind v4 的 CSS@theme块，或 W3C 标准的 DTCG tokens.json；spec直接打印格式规范全文，方便塞进代理的提示词里。

令牌体系本身借鉴了 W3C Design Token 规范，所以export出来的东西能平滑对接 Figma 变量、Style Dictionary 这类现有管道。

为什么叙述比数值更重要

DESIGN.md 最反直觉的一个决定，是把这些数值从"渲染指令"降级成"参考背景"，模型不会照着逐像素还原。官方原话说得很直白：

"Adjectives describe a region. A specific reference describes a point."

用大白话讲，形容词描画的是一片模糊区域，具体参照物指的才是一个点。你说"现代、干净、可信"，模型只能落回这些词描述的中心，产出一个平庸的中间值；可你说"一所老牌大学、七十年代的研究生讲义"，它会自动带上整组约束——不发光、不渐变、不用粗体，就像你点了"狗"，模型自然知道狗不会喵。

这就是为什么规范鼓励你多写"为什么"，把数值留给令牌。参照物点得越具体，模型自动补上的"别做什么"就越多，所以仓库示例里叙述段落往往比令牌还长。

照着仓库里的三份示例学

仓库内置三套风格完全不同的设计系统，可以直接对着抄结构：

linter 还能当库用：从@google/design.md/linter引入lint函数，把一段 Markdown 字符串丢进去就能拿到 findings，不必非得走命令行。

现在就能上手

先拿仓库里某个示例文件跑一遍lint，看看它的 JSON 长什么样，再对着 docs/spec.md 给自己的项目起一份 DESIGN.md。写的时候记住：令牌给数值，叙述给理由，参照物点得越具体越好。

一句提醒：这套格式现在还停在alpha版本，规范、令牌 schema 和 CLI 都在快速迭代，字段以后可能变。趁现在把它放进仓库根目录，成本只是多写一段说明，换回来的是——下个会话、换个工具，界面还是同一个品牌。

【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md