DESIGN.md 是什么，怎么用。

DESIGN.md 是一个纯文本文件，用来向 AI Agent 描述你的设计系统：精确的颜色、字体、间距和组件，以及背后的设计考量。在仓库里放一份，Codex 设计的每个新界面都会沿用同一套视觉语言。

更新于 2026年11月5日 · 阅读约 8 分钟

DESIGN.md 是什么？

DESIGN.md 是 Google Labs 推出的一种开放格式，用来向编程 Agent 描述一套视觉风格。它最早出自 Google Stitch，以 Apache 2.0 许可证发布，规范目前仍标为 alpha，所以要做好它还会变的准备。

一个 DESIGN.md 文件分两层：

• YAML 格式的设计 token。 精确、机器可读的值：颜色、字体排版、圆角、间距和组件样式。一切以 token 的值为准。
• Markdown 正文。 讲清背后的考量：产品应该给人什么感觉，每种颜色什么时候用，哪些做法要避免。正文告诉 Agent 该怎么运用这些 token。

没有这样一个文件，每次你让 Agent 做一个界面，它都会挑一种新的蓝色、一种新的按钮样式。有了它，第五十个界面也能和第一个保持一致。

DESIGN.md 里写什么

token 可以放在文件顶部的 YAML front matter 里，也可以放在各个章节里的 yaml 代码块中。schema 一共有五组 token：

正文用 ## 划分章节。任何章节都可以省略，但写进去的章节要按这个顺序排列：Overview（概述）、Colors（颜色）、Typography（字体排版）、Layout（布局）、Elevation & Depth（层级与深度）、Shapes（形状）、Components（组件）和 Do’s and Don’ts（该做与不该做）。

完整示例

下面这份 DESIGN.md 描述的是我们 App 界面设计提示词页面里用到的那款阅读 App。把它保存为仓库根目录下的 DESIGN.md。

---
version: alpha
name: Pagely
description: 安静、有书卷气的阅读习惯 App 界面。
colors:
  primary: '#1F3D2B'
  on-primary: '#FAF6EE'
  secondary: '#E8735A'
  tertiary: '#F2C14E'
  neutral: '#FAF6EE'
  surface: '#FFFFFF'
  on-surface: '#1F2A22'
typography:
  headline-lg:
    fontFamily: Georgia
    fontSize: 32px
    fontWeight: 400
    lineHeight: 1.15
  body-md:
    fontFamily: system-ui
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
  label-caps:
    fontFamily: system-ui
    fontSize: 13px
    fontWeight: 500
    letterSpacing: 0.12em
rounded:
  md: 16px
  lg: 22px
  full: 9999px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: '{colors.primary}'
    textColor: '{colors.on-primary}'
    rounded: '{rounded.md}'
    padding: 18px
---

## Overview

安静、温暖、有书卷气，像一家光线很好的咖啡馆。界面宽敞、从容，每个界面只有一个清晰的下一步。

## Colors

- **Primary（#1F3D2B）：** 深森林绿，用于主要操作和连续打卡卡片。
- **Secondary（#E8735A）：** 珊瑚色，只用于进度和小面积点缀。
- **Tertiary（#F2C14E）：** 暖黄色，用于连续打卡和目标指示。
- **Neutral（#FAF6EE）：** 奶油色背景，每个界面都用，绝不用纯白。

## Typography

标题用 Georgia，带出文学气质。其余文字都用系统 UI 字体，让正文清晰利落。标签全部大写，字距加宽。

## Layout

手机上左右边距 24px。间距遵循 8px 尺寸层级。主要操作放在屏幕下半部分，拇指够得着的位置。

## Elevation & Depth

不用厚重的阴影。层次感来自奶油色背景上带 1px 暖色描边的白色卡片。

## Shapes

柔和、圆润：按钮和输入框圆角 16px，卡片圆角 22px。

## Components

主按钮通栏、深绿色、内边距 18px。每个界面只有一个主按钮。

## Do's and Don'ts

- 要保证文字对比度达到 WCAG AA 或更高。
- 要克制地使用珊瑚色：只用在进度条上，外加每个界面一处点缀。
- 不要用纯黑或纯白。
- 一张卡片里不要出现两种以上的字号。

怎么让 Codex 遵循它

Codex 会自动读取 AGENTS.md：从仓库根目录开始，一路往下读到你当前工作的文件夹。它不会自己去找 DESIGN.md，所以要在 AGENTS.md 里指向它：

## 设计

- 做任何 UI 工作之前，先读 DESIGN.md，只使用其中的 token。
- 如果某个界面需要 DESIGN.md 里没有定义的值，先问我，不要自己编一个。
- 修改 DESIGN.md 之后，运行 `npx @google/design.md lint DESIGN.md`，并修复所有错误。

然后照常让它设计界面。在提示词里提到这个文件，要求会更明确：

按照 DESIGN.md，把 [设置] 界面设计成一个自包含的 HTML 文件，尺寸 390×844。只使用 DESIGN.md 里的颜色、字号、圆角和间距；如果需要用到它没有定义的东西，告诉我。

让 Codex 帮你写 DESIGN.md

这个文件很少需要手写。如果你已经有产品，就让 Codex 从代码里提取：

读一下我们的 Tailwind 配置、全局 CSS 和最常用的五个组件，然后在仓库根目录写一份 DESIGN.md。先运行 `npx @google/design.md spec`，按它给出的格式来写：token 放在 YAML front matter 里，然后依次是 Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components 和 Do's and Don'ts 这几个章节。只使用代码里实际存在的值。最后运行 `npx @google/design.md lint DESIGN.md`，并修复所有错误。

如果是新产品，就从一个你喜欢的设计方向出发，比如你在画布上确认过的设计稿，或者一张参考截图：

这是我们确认过的界面设计 [附上截图，或者写出 HTML 文件名]。写一份 DESIGN.md，记录它的颜色、字体、间距、圆角和按钮样式，加一段简短的 Overview 说明整体应该给人什么感觉，再写五条 Do's and Don'ts。按照 `npx @google/design.md spec` 给出的 DESIGN.md 格式来写。

@google/design.md 命令行工具还能用 lint 检查对比度和失效的 token 引用，用 diff 比较两个版本，用 export 把 token 转成 Tailwind 主题或 W3C 设计 token。

DESIGN.md、SKILL.md 和 AGENTS.md 的区别

这三个文件常常放在同一个仓库里，各管各的事：

它们配合得很好。设计 skill 可以写「设计任何东西之前先读 DESIGN.md」，而 AGENTS.md 能保证即使没用这个 skill，这一步也会执行。想进一步了解 skill，参见 Codex 插件和 skill 的区别。

去哪里找示例

开源合集 awesome-design-md 收录了一批 DESIGN.md 文件，描述各个知名网站的设计系统，每份都配有预览页面。想学习别人怎么描述颜色、字体和组件，它们很有参考价值。把它们当作结构上的参考，而不是照搬别家公司品牌的捷径。

常见问题

DESIGN.md 是官方标准吗？

它是 Google Labs 的开放规范，Google Stitch 在用，发布在 GitHub 上。规范目前仍是 alpha 版，它自己的文档也说格式还会变。

Codex 支持 DESIGN.md 吗？

Codex 能读取并遵循你仓库里的任何文件。不需要特殊设置：像上面那样，在 AGENTS.md 或提示词里引用 DESIGN.md 就行。

DESIGN.md 能取代 Figma 或设计系统吗？

不能。它是设计系统的文字摘要，供 Agent 读取。如果团队以 Figma 或代码为准，可以从那里生成 DESIGN.md，并在设计系统变化时同步更新。

继续阅读

• Codex 前端设计 skill 推荐让 Codex 有审美的 skill，以及怎么为你自己的设计系统写一个。
• App 界面设计提示词让设计系统一个界面一个界面落地的提示词。