什么是 DESIGN.md？

每个项目都有自己的视觉识别：色彩、字体、间距、组件样式。传统上，这些内容存在于 Figma 文件、品牌 PDF 或设计师的脑海中。而这些都无法被 AI 智能体读取。

**DESIGN.md 改变了这一切。**它是一份纯文本的设计系统文档，人和智能体都能读取、编辑并执行。可以把它看作设计领域的 AGENTS.md：

文件	谁来读取	定义了什么
README.md	人类	项目是什么
AGENTS.md	编码智能体	如何构建项目
DESIGN.md	设计智能体	项目应有的外观与感受

它能为你带来什么

当 Stitch 这样的设计智能体读取你的 DESIGN.md 时，它生成的每一个屏幕都遵循相同的视觉规则：你的调色板、你的排版、你的组件模式。没有它，每个屏幕各自为政；有了它，它们看起来浑然一体。

DESIGN.md 是一份活文档，而不是静态配置文件。它随着你的设计一同演进。智能体生成它，你打磨它，并在你迭代时把它重新应用到各个屏幕上。

在底层，每份 DESIGN.md 都包含两层：YAML front matter 存放机器可读的设计 token（精确的十六进制色值、字体属性、间距尺度），markdown 正文则提供人类可读的设计依据。Token 为智能体提供精确的数值；正文则告诉它们这些数值_为何_存在。完整格式见规范。

设计理念

DESIGN.md 规范是一套基础，而非处方。它提供一个智能体、工具和团队都能依赖的共同基础——一套描述色彩、排版、布局和组件的共享词汇——同时保留了为特定领域需求扩展格式的自由。未知章节和自定义 token 会被接受，而不是被拒绝。

创建方式

通往 DESIGN.md 的路径有三条，从毫不费力到精雕细琢。

Stitch

让智能体生成

描述你想要的氛围。智能体会把你的美学意图转化为 token 和准则。

Stitch 会生成一套完整的设计系统（色彩、排版、间距、组件样式），并将其归纳为一份 DESIGN.md。

从品牌推导

如果你已经有品牌资产，只需提供 URL 或图片。智能体会提取其中的调色板、排版和风格模式，基于已有内容构建 DESIGN.md。

Stitch

手动撰写

高级用户可以直接撰写 DESIGN.md，把精确的设计偏好编码进去。每个章节都只是 markdown，可选择搭配用于设计 token 的 YAML front matter。除了标准 markdown 和 YAML 之外，没有特殊语法。

示例

下面是一份深色主题生产力应用的极简 DESIGN.md。YAML front matter 定义了精确的 token 值；markdown 正文则阐释设计意图。

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

这就是智能体在生成你的下一个屏幕时所读取的内容。完整的格式规范见规范。若要依据规范校验你的 DESIGN.md，见用 CLI 校验。