DESIGN.md 规范

DESIGN.md 格式的正式规范——token schema、章节结构与类型系统。

一份 DESIGN.md 文件包含两层。YAML front matter 存放机器可读的设计 token——智能体用来强制保持一致性的精确数值。markdown 正文按 ## 章节组织，提供人类可读的设计依据。正文可以使用描述性的颜色名称（如“Midnight Forest Green”），与系统化的 token 名称（如 primary）相对应。Token 才是规范性数值；正文提供的是如何应用这些数值的上下文。

该规范是一份基础，而非处方。它提供智能体、工具和团队都能依赖的共同基础，同时保留了为特定领域需求扩展格式的自由。

设计 token

DESIGN.md 把设计 token 以 YAML front matter 的形式嵌入文件开头。Front matter 块必须以一行恰好为 --- 的内容开始，并以一行恰好为 --- 的内容结束。两个分隔符之间的 YAML 内容遵循下方定义的 schema。

这套 token 体系受 W3C Design Token Format 启发。Token 可以方便地与 tokens.json、Figma 变量和 Tailwind 主题配置相互转换。

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
---

Schema

version: <string>          # optional, current version: "alpha"
name: <string>
description: <string>      # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

<scale-level> 占位符表示尺寸或间距尺度中的一个具名层级。常见的层级名称包括 xs、sm、md、lg、xl 和 full。任何具有描述性的字符串键都是有效的。

Token 类型

类型格式示例
Color# + 十六进制色码（sRGB）"#1A1C1E"
Dimension数值 + 单位（px、em、rem）48px, -0.02em
Token Reference{path.to.token}{colors.primary}
Typography复合对象见下方属性

Typography 属性

属性类型说明
fontFamilystring字体族名称
fontSizeDimension字号大小
fontWeightnumber数值字重（如 400、700）。在 YAML 中，裸数字与带引号的字符串等价
lineHeightDimensionnumber
letterSpacingDimension字距调整
fontFeaturestring配置 font-feature-settings
fontVariationstring配置 font-variation-settings

Token 引用

Token 引用用花括号包裹，内含一条指向 YAML 树中另一个值的对象路径。对于大多数 token 组，引用必须指向原始值（如 {colors.primary-60}），而不是指向一个组。在 components 章节内，允许引用复合值（如 {typography.label-md}）。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"

章节

每份 DESIGN.md 都遵循相同的结构。与项目无关的章节可以省略，但出现的章节应按下文列出的顺序排列。所有章节都使用 ## 标题。出于文档命名的目的，可以出现一个可选的 # 标题，但它不会被解析为章节。

章节结构有意保持开放。规范章节提供了一套共享词汇；设计系统可以自由地在这些章节之外添加领域特有的章节。

章节顺序

#章节别名
1OverviewBrand & Style
2Colors
3Typography
4LayoutLayout & Spacing
5Elevation & DepthElevation
6Shapes
7Components
8Do’s and Don’ts

Overview

另称“Brand & Style”。对产品外观与感受的整体描述。这一章节定义品牌个性、目标受众，以及 UI 应当唤起的情感反应。当某条具体规则或 token 未定义时，它会作为基础上下文。

## Overview
A calm, professional interface for a healthcare scheduling platform.
Accessibility-first design with high contrast and generous touch targets.

Colors

定义设计系统的调色板。至少应定义 primary 调色板。其他调色板可以自由命名；常见约定是 primary、secondary、tertiary 和 neutral。

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** The sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.

设计 token： 一个 map<string, Color>，把 token 名称映射到它的十六进制色值。

colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"

Typography

定义排版层级。大多数设计系统有 9–15 个层级，每个层级都有语义角色（headline、body、label）和尺寸变体（small、medium、large）。

## Typography

- **Headlines:** Public Sans Semi-Bold for an institutional voice.
- **Body:** Public Sans Regular at 16px for long-form readability.
- **Labels:** Space Grotesk for technical data and metadata.

设计 token： 一个 map<string, Typography>，把 token 名称映射到它的排版属性。

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em

Layout

另称“Layout & Spacing”。描述布局与间距策略——网格模型、间距尺度和内容约束原则。

## Layout

The layout follows a Fluid Grid model for mobile and a Fixed-Max-Width
Grid for desktop (max 1200px). A strict 8px spacing scale is used.

设计 token： 一个 map<string, Dimension | number>，把间距尺度标识符映射到尺寸值或无单位数值（如列数或比例）。

spacing:
  base: 16px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px

Elevation & Depth

另称“Elevation”。描述视觉层级如何传达。对于使用阴影的设计，它定义阴影属性；对于扁平化设计，它说明替代方法（边框、色调层次、色彩对比）。

## Elevation & Depth

Depth is achieved through tonal layers rather than heavy shadows.
Background uses a soft off-white; primary content sits on pure white cards.

Shapes

描述视觉元素如何成形——圆角半径、边缘处理和整体形状语言。

## Shapes

All interactive elements use a minimal 4px corner radius.
Modern enough to feel current, rigid enough to feel engineered.

设计 token： 一个 map<string, Dimension>，把尺度层级映射到圆角半径。

rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px

Components

针对组件原子的样式指南。规范定义了常见组件类型——Buttons、Chips、Lists、Inputs、Checkboxes、Radio buttons、Tooltips——但鼓励设计系统定义与其领域相关的更多组件。

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill, secondary uses outline
- **Inputs**: 1px border, surface-variant background, 12px padding
- **Cards**: No elevation, 1px outline border, 12px corner radius

设计 token： 一个 map<string, map<string, string>>，把组件标识符映射到一组子 token 属性。Token 值可以是字面值，也可以是对先前已定义 token 的引用。

变体。 组件可以针对不同的 UI 状态（hover、active、pressed）提供变体。变体定义为单独的组件条目，使用相关联的键名。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

组件属性 token

属性类型
backgroundColorColor
textColorColor
typographyTypography
roundedDimension
paddingDimension
sizeDimension
heightDimension
widthDimension

Do’s and Don’ts

实用准则与常见误区。它们在生成过程中充当护栏。

## Do's and Don'ts

- Do use the primary color only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

消费方对未知内容的行为

这套规范的设计目的就是可以被扩展。当消费方遇到本规范未定义的内容时：

场景行为示例
未知章节标题保留；不报错## Iconography
未知色彩 token 名称若值有效则接受surface-container-high: '#ede7dd'
未知排版 token 名称视为有效排版接受telemetry-data
未知间距值接受；若不是有效尺寸则以字符串存储grid-columns: '5'
未知组件属性接受并给出警告borderColor
重复的章节标题报错；拒绝该文件两个 ## Colors 标题

推荐的 token 名称

以下名称在设计系统中广泛使用。它们不是必需的，但作为保持一致性的指引提供。

色彩： primary、secondary、tertiary、neutral、surface、on-surface、error

排版： headline-display、headline-lg、headline-md、body-lg、body-md、body-sm、label-lg、label-md、label-sm

圆角： none、sm、md、lg、xl、full

原文: https://stitch.withgoogle.com/docs/design-md/specification/

本页翻译自 Google Stitch 官方文档，原文版权归 Google LLC 所有。本站为独立第三方翻译，与 Google 无关联。

← 上一页从代码库导入下一页 →查看、编辑与导出