用 DESIGN.md 描述一套 Brutalist 编辑设计系统：以 “The Tracks of Washington DC“ 为例的完整实战解析

用 DESIGN.md 描述一套 Brutalist 编辑设计系统：以 "The Tracks of Washington DC" 为例的完整实战解析

【免费下载链接】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 开源仓库中的真实示例文档 TRACKS_OF_DC.md 为研究对象，完整拆解一份"粗野极简主义（Brutalist-Minimalism）"设计系统文档的写法——从 YAML frontmatter 中的机器可读设计令牌，到 Markdown 正文中面向 Agent 与人类的设计理性说明。读完本文，你将掌握 DESIGN.md 格式的完整骨架（colors/typography/spacing/rounded/components五大令牌组与八个规范章节）、令牌引用语法与消费规则，并能够用仓库提供的lint/diff/exportCLI 对这样一份文档进行校验、对比与跨格式导出。

一、这份文档是什么：DESIGN.md 的规范合规样例

TRACKS_OF_DC.md位于仓库的 linter 测试夹具目录 packages/cli/src/linter/fixtures 中，与ALPINE_OBSERVATORY.md、CARTOGRAPHERS_ATLAS.md、HERITAGE.md等同级。它是用来验证 linter 与解析器行为的真实样例，同时也是 DESIGN.md 格式一份"教科书级"的完整实现。

DESIGN.md 是一种自包含、纯文本的设计系统描述格式：它把品牌的视觉身份（颜色、字体、间距、圆角、组件样式）编码成一份人类与 AI 都能读取的文件，让编码 Agent 在不同会话、不同工具之间获得对设计系统持久、结构化的理解。其完整规范见 docs/spec.md。

一个 DESIGN.md 文件包含两个层次：

1. YAML frontmatter—— 机器可读的设计令牌（design tokens），以文件开头严格成对的---分隔符包裹；
2. Markdown 正文—— 以##二级标题组织的人类可读设计说明与使用指南。

规范明确指出：令牌是规范性（normative）的值，正文散文提供的是"为什么"与应用上下文。正文中可以使用描述性颜色名（如 "Deep Midnight Forest Green"），它们对应系统化令牌名（如primary）。这份文档正是这一理念的完整示范。

二、YAML frontmatter：五组令牌的完整数据层

TRACKS_OF_DC.md的 frontmatter 从第 1 行到第 89 行，完整使用了 DESIGN.md schema 中的name、colors、typography、spacing四个顶层键。对照 docs/spec.md 的 schema 定义：

version: <string> # optional, current version: "alpha" name: <string> description: <string> # optional omitted: <string[]|OmittedSection[]> # 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>

顶层合法的键在解析器中被定义为SCHEMA_KEYS，见 parser/spec.ts：version、name、description、omitted、colors、typography、rounded、spacing、components。

2.1name：设计系统身份

name: The Tracks of Washington DC

这是设计系统的唯一名称标识，也是设计系统状态对象DesignSystemState.name的来源。

2.2colors：51 个 Material 风格颜色令牌

该样例定义了一套完整的、Material Design 风格的角色化颜色体系，共 51 个令牌。核心角色符合规范中推荐的非规范性命名约定（primary、secondary、tertiary、neutral、surface、on-surface、error）：

此外还包含完整的一整套*-fixed、*-fixed-dim、on-*-fixed、on-*-fixed-variant色阶族（如primary-fixed: #d0e8d9、primary-fixed-dim: #b4ccbe），以及surface-tint: #4d6357这样的 M3 体系色彩，覆盖了明暗主题与各交互状态的需要。

Color 类型的合法值：根据 docs/spec.md，颜色值可以是任意合法 CSS 颜色字符串——Hex（#RGB、#RGBA、#RRGGBB、#RRGGBBAA）、命名色、rgb()/hsl()/hwb()等功能写法、oklch()/lab()等广色域写法，甚至color-mix(in srgb, ...)。所有颜色在内部都会转换为 sRGB 以进行 WCAG 对比度检查，原始格式则被保留用于展示与导出。#RRGGBB是规范推荐的默认写法，本样例全部使用该格式。

2.3typography：三声部字体系统的数据化

typography: headline-display: fontFamily: Newsreader fontSize: 72px fontWeight: '700' lineHeight: '1.1' letterSpacing: -0.02em headline-lg: fontFamily: Newsreader fontSize: 48px fontWeight: '600' lineHeight: '1.2' letterSpacing: -0.01em body-main: fontFamily: Noto Serif fontSize: 18px fontWeight: '400' lineHeight: '1.7' letterSpacing: 0.01em body-sm: fontFamily: Noto Serif fontSize: 14px fontWeight: '400' lineHeight: '1.6' letterSpacing: 0px label-mono: fontFamily: Space Grotesk fontSize: 12px fontWeight: '500' lineHeight: '1.0' letterSpacing: 0.2em

Typography 令牌支持这些属性（见 docs/spec.md 与 model/spec.ts 中的ResolvedTypography）：fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation。

值得注意的两个细节：

• fontWeight数字与字符串等价：YAML 中700（裸数字）与'700'（带引号字符串）解析结果相同。linter 测试夹具 fixture.test.ts 明确断言：fontWeight: '700'（字符串）会被解析为数字700。
• lineHeight可为无单位数字：1.1、1.7这类无单位值表示相对fontSize的倍数，是规范推荐的 CSS 做法；带单位的 Dimension（如24px、1.5rem）同样合法。

注意letterSpacing的单位是em，而 Dimension 的规范单位是px/em/rem（见 spec-config.yaml 中units配置）。model/spec.ts 中的parseDimensionParts使用正则/^(-?\d*\.?\d+)([a-zA-Z%]+)$/解析维度字符串（支持负号、小数与单位后缀），并把字符串长度上限设为 64 字符以防病态正则回溯。

2.4spacing：5 列非对称网格的数值表达

spacing: grid-columns: '5' headline-span: '3' content-span: '2' gutter: 24px margin: 40px unit: 8px

spacing是map<string, Dimension | number>：既可以是带单位的 Dimension（24px、40px），也可以是无单位的数字或字符串（列数、比例）。这里用grid-columns: '5'、headline-span: '3'、content-span: '2'表达 3/5–2/5 的分栏比例，用gutter、margin、unit定义栅格物理参数。

这正是 docs/spec.md 中所说的：固定栅格布局可以用 spacing 令牌来承载列跨度、沟槽与边距等实现所需参数。同时它也是 spec.md 中"Consumer Behavior"表里grid-columns: '5'（未知 spacing 值）被接受的直接出处——该样例就是规范文档中"未知 spacing 值按字符串存储"行为的实例。

三、Markdown 正文：八个规范章节的完整示范

TRACKS_OF_DC.md的正文从## Brand & Style开始，依次是 Colors、Typography、Layout & Spacing、Elevation & Depth、Shapes、Components，共六个章节。对照 docs/spec.md 的规范章节顺序：

章节可用别名互相替换：Brand & Style解析为Overview，Layout & Spacing解析为Layout。别名的解析逻辑见 spec-config.ts（SECTION_ALIASES映射与resolveAlias函数）以及 rules/section-order.ts 中的规范顺序检查。未出现的章节可以合法省略（Do's and Don'ts 在本样例中被省略），但已出现的章节必须按上述顺序排列，否则 linter 的section-order规则会报出 warning（见 rules/section-order.ts：遍历解析出的章节序列，一旦发现前序章节在规范顺序中的位置大于后序章节即产生 finding）。

3.1 Brand & Style（Overview）：品牌人格与美学基调

This design system establishes a high-prestige editorial aesthetic that blends collegiate tradition with modern architectural precision. The brand identity is authoritative and quiet, evoking the intellectual rigor of a historical archive and the physical presence of iron and stone.

The design style isBrutalist-Minimalism. It utilizes hard edges, raw structural lines, and a deliberate absence of decorative embellishments like shadows or gradients. The visual language favors high-contrast layouts and generous negative space to elevate the subject matter—the transit and architecture of the capital—to a level of fine art.

这一章节定义了品牌气质（权威、安静、学院传统 × 建筑精确性）与整体美学（粗野极简主义：硬边、原始结构线、无阴影无渐变、高对比、大留白）。它的作用是：当没有显式规则或令牌覆盖时，为 Agent 的高层风格决策提供基础上下文。示例中的Pacific Mint Dental（见 DESIGN-test.md）同样在 Overview 中定义了 "Clinical Serenity" 的品牌人格——这说明 Overview 是每个设计系统文档的"第一印象"层。

3.2 Colors：四角色色彩叙事

The palette is rooted in a "Warm Cream" canvas that provides a softer, more sophisticated background than pure white.

• Deep Midnight Forest Greenserves as the primary ink, used for all headlines and foundational text to ensure maximum authority.
• Warm Weathered Slateis reserved for secondary information, metadata, and captions, providing a softer visual hierarchy.
• Track Terracottais used sparingly as a singular accent for calls to action, drawing the eye to the primary interaction point on each panel.

正文用描述性命名（Warm Cream / Deep Midnight Forest Green / Warm Weathered Slate / Track Terracotta）解释各色值的存在理由与应用位置，与 frontmatter 中的surface、primary、secondary、tertiary一一对应。规范要求 Colors 章节至少必须定义primary，本样例满足（primary: #061b12）。多调色板时的推荐命名顺序是primary、secondary、tertiary、neutral。

3.3 Typography：三声部字体体系

The typographic system relies on a sharp contrast between three distinct voices:

• Headlines:Set in a condensed, high-contrast serif (Newsreader). These must always be left-aligned to maintain a rigid vertical axis.
• Body:A humanist serif (Noto Serif) designed for long-form legibility. The generous 1.7 line height ensures a luxurious, breathable reading experience.
• Labels:A monospace font (Space Grotesk) used for administrative data, timestamps, and "eyebrow" text. The wide tracking is inspired by mechanical stopwatches and archival stamps.

标题（Newsreader，高对比衬线，必须左对齐以保持刚性垂直轴）、正文（Noto Serif，人文衬线，1.7 行高保证长文可读性）、标签（Space Grotesk，等宽字体，0.2em 宽字距用于管理数据/时间戳/眉题）——三种字体与 frontmatter 中的headline-display/headline-lg、body-main/body-sm、label-mono五级令牌精确对应。正文中"1.7 line height"、"0.2em tracking"直接由令牌lineHeight: 1.7、letterSpacing: 0.2em背书，体现了"正文提供语义、令牌提供精确值"的协作模式。

3.4 Layout & Spacing：3/5–2/5 非对称分栏网格

The layout follows a strict asymmetrical split-grid model based on a 5-column system.

• Split Ratio:Content is divided into a 3/5 width for headlines and primary imagery, and a 2/5 width for descriptions, metadata, and CTAs.
• The Grid:A subtle canvas grid of thin ruled lines (0.5px Forest Green at 10% opacity) should be visible or implied, aligning all elements to a rigid structure.
• Alignment:Center-alignment is strictly prohibited. All elements must anchor to the left margin or the internal 3/5 split line.
• Imagery:Use full-bleed imagery that breaks through the margins to create a lookbook feel.

Layout 章节描述了严格的 5 列非对称分栏模型：标题与主图占 3/5，描述/元数据/CTA 占 2/5；0.5px 森林绿 10% 透明度的细网格线可见或暗示；严禁居中，所有元素锚定左边距或内部 3/5 分割线；图片全出血（full-bleed）打破边距营造画册感。这些文字规则与 frontmatter 的spacing令牌（grid-columns: 5、headline-span: 3、content-span: 2、gutter: 24px、margin: 40px、unit: 8px）互为印证。

3.5 Elevation & Depth：无阴影的调性分层

This design system avoids all drop shadows and blurs. Depth is achieved exclusively throughTonal Variationand layering.

Elements are perceived as being on different planes through the use of solid color blocks and ruled lines. To separate sections, use thin 1px horizontal rules in Primary Forest Green. High-priority panels may use a subtle shift in background color from the Neutral Cream to a slightly darker variant of the Secondary Slate at extremely low opacity (3-5%).

这是一个"扁平设计如何传达层级"的规范范例。规范 docs/spec.md 指出：若使用 Elevation 需定义其样式（spread、blur、color）；对扁平设计则需说明替代方案（边框、颜色对比）。本文档给出的是后者：完全禁用投影与模糊，深度只通过色调变化（Tonal Variation）与分层实现——1px 森林绿水平分隔线、以及高优先级面板在 Cream 底色上叠 3–5% 深度的 Slate 变体。

对比同仓库的 atmospheric-glass/DESIGN.md，后者通过backdrop-filter: blur(20px/40px)与rgba半透明背景实现玻璃拟态深度——两种设计系统对 Elevation 的处理方式截然相反，但都在各自的文档中给出了明确的实现规则，这正是该章节存在的意义。

3.6 Shapes：硬直角形状语言

The shape language is defined byHard Right Angles.

• Border Radius:All containers, buttons, and decorative elements must have a 0px radius.
• Geometry:Arcs and circles may be used for specific technical diagrams or "Track" iconography, but they must be precise, geometric, and never "organic" or "hand-drawn."

形状语言 = 硬直角：所有容器、按钮、装饰元素半径一律 0px；圆弧与圆形仅允许用于技术图表或"轨道"图标，且必须精确几何化，禁止有机/手绘感。本样例未在 frontmatter 中定义rounded令牌组——因为该设计系统所有圆角都是 0px，这是omitted机制与missing-sections规则设计的典型场景（有意省略的章节可以通过omitted配置抑制 linter 警告，见 docs/spec.md 中omitted的说明与omitted-rules规则）。

3.7 Components：五个领域组件的样式处方

• Buttons:Rectangular with a 0px radius. Fill is Track Terracotta; text is Primary Forest Green. Each button is framed by a 1px outer ring in Primary Forest Green at 10% opacity, spaced 4px from the button edge. No icons are permitted within buttons.
• Pull Quotes:Set in the editorial headline serif. These feature a 2px solid vertical border in Track Terracotta on the left side only.
• Track Labels:Monospace "eyebrow" labels used above headlines. These should always be uppercase with 0.2em tracking.
• Metadata Lists:Key-value pairs (e.g., "STATION: UNION") set in the Secondary Slate color, using a mix of Monospace for keys and Humanist Serif for values.
• Dividers:1px solid ruled lines. Use sparingly to define the 3/5 - 2/5 split or to separate editorial sections.

Components 章节定义了五个领域组件：按钮（矩形、0px 圆角、Terracotta 填充 + 森林绿文字、1px 森林绿 10% 透明度外环距按钮边缘 4px、禁止图标）、拉引文（编辑标题衬线体 + 左侧 2px Terracotta 实心竖边）、轨道标签（等宽眉题、全大写、0.2em 字距）、元数据列表（"STATION: UNION" 形式，键用等宽、值用人文衬线，Slate 色）、分隔线（1px 实线，仅用于定义 3/5–2/5 分割或分隔编辑区块）。

规范鼓励在常见组件类型（Buttons、Chips、Lists、Tooltips、Checkboxes、Radio buttons、Input fields）之外定义领域专属组件——本文档的 Pull Quotes、Track Labels、Metadata Lists 就是"根据领域扩展组件"的示范。值得注意的是，规范同时指出 components 规范正在演进中，"设计系统被鼓励定义与其领域相关的额外组件"。

若要将这些组件数据化为令牌，可用 docs/spec.md 的 components 语法（组件子令牌：backgroundColor、textColor、typography、rounded、padding、size、height、width，值可为字面量或{path.to.token}引用；变体用相关键名表达，如button-primary-hover）。完整的组件令牌实例如 atmospheric-glass/DESIGN.md 中的button-primary/button-primary-hover/glass-card-standard：

components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" typography: "{typography.label-sm}" rounded: "{rounded.xl}" height: 48px padding: 0 24px button-primary-hover: backgroundColor: "{colors.primary-fixed-dim}"

四、消费行为与容错机制：这份文档如何被解析与校验

DESIGN.md 规范为消费者定义了"遇到未知内容"时的行为契约（见 docs/spec.md 的 Consumer Behavior 表）：

本样例恰好是这张表多个条目的活标本：grid-columns: '5'对应"未知 spacing 值按字符串存储"；surface-container-high这类非推荐命名对应"未知颜色令牌名接受"；正文中## Brand & Style对应"未知章节标题保留"（它其实是 Overview 的规范别名）。

解析后的状态对象DesignSystemState（见 model/spec.ts）包含：colors/typography/rounded/spacing四个 Map、componentsMap、扁平化的symbolTable（如colors.primary → ResolvedColor）、sections标题列表与unknownKeys。颜色会被解析为带 sRGB 分量、十六进制与WCAG 相对亮度（luminance）的ResolvedColor，为对比度检查做准备。

五、用 CLI 校验、对比与导出这类设计系统文档

5.1 安装

npm install @google/design.md

在 Windows 上，若 shell 对@有特殊处理（PowerShell 等），需加引号：

npm install "@google/design.md"

或直接使用npx（始终从公共 npm registry 解析）：

npx @google/design.md lint DESIGN.md

Windows 提示：由于design.md这个 bin 名称的.md后缀会与 Windows 的 Markdown 文件关联冲突，导致命令解析异常，Windows/PowerShell 下应使用无点别名designmd：

npx -p @google/design.md designmd lint DESIGN.md

在package.json脚本中同样建议使用designmd：

{ "scripts": { "design:lint": "designmd lint DESIGN.md" } }

若遇到npm error ENOVERSIONS（"No versions available for @google/design.md"），通常意味着 npm 没有查询公共 registry（.npmrc自定义了registry=、企业镜像未同步、或@googlescope 配置了错误 registry），可运行npm config get registry检查，正常应为https://registry.npmjs.org/。

5.2lint：结构校验

npx @google/design.md lint DESIGN.md npx @google/design.md lint --format json DESIGN.md cat DESIGN.md | npx @google/design.md lint -

所有命令接受文件路径或-（stdin），输出默认为 JSON。有错误时退出码为1，否则为0。

linter 会对解析后的文档运行若干规则（源码见 linter/rules，规则注册见 linter/index.ts）：

以本文档为例：它定义了完整的primary与 5 个排版令牌，因此不会触发missing-primary/missing-typography；它未定义rounded令牌组（因为设计是 0px 圆角），可能触发missing-sectionsinfo，可通过omitted配置声明有意省略来抑制。对比度检查基于ResolvedColor.luminance计算 WCAG 相对亮度（见 model/spec.ts）。

5.3diff：令牌级与散文级回归对比

npx @google/design.md diff DESIGN.md DESIGN-v2.md

按令牌组（colors / typography / rounded / spacing / components）报告 added / removed / modified，并输出前后 lint 摘要与regression布尔值。若 "after" 文件的错误或警告数量增加，退出码为1。这对设计系统的版本演进审查非常实用——例如把本文档与它的某个 v2 版本对比，即可精确定位哪些颜色令牌被修改。

5.4export：跨格式互操作

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json npx @google/design.md export --format css-tailwind DESIGN.md > theme.css npx @google/design.md export --format dtcg DESIGN.md > tokens.json

导出成功退出码为0（无论源文件是否有 lint 发现，如需门禁请先运行lint），--format无效或 emitter 错误为1，输入文件不可读为2。

这套互操作机制在仓库示例中有完整落地：examples/atmospheric-glass目录下同时存在 DESIGN.md 源文件、通过 DTCG 导出的 design_tokens.json（其中颜色被展开为$type+ sRGB 分量 +hex，组件令牌保留{colors.primary}引用形式）以及通过 Tailwind 导出的 tailwind.config.js（theme.extend中的colors、fontFamily、fontSize、borderRadius、spacing）。你可以把TRACKS_OF_DC.md同样导入三个导出目标，生成等价的三份产物。

5.5spec：注入 Agent 上下文的规范输出

npx @google/design.md spec npx @google/design.md spec --rules npx @google/design.md spec --rules-only --format json

直接输出 DESIGN.md 格式规范全文（可用于把规范上下文注入 Agent 提示词），--rules追加当前生效的 lint 规则表，--rules-only只输出规则表，--format支持markdown/json。

六、从这份文档学到的 DESIGN.md 写作要点

综合这份样例与 docs/spec.md、README.md 及 linter 源码，写出一份高质量 DESIGN.md 的实践要点：

1. 令牌与散文双轨并行，令牌为准：精确值全部进 frontmatter（颜色、字号、行高、字距、间距、圆角、组件属性），正文用描述性语言（"Warm Cream"、"1.7 line height"）解释语义与使用场景，双方互相对应、彼此印证。
2. 按规范章节顺序组织正文：Overview(Brand & Style) → Colors → Typography → Layout → Elevation → Shapes → Components → Do's and Don'ts；不适用章节可省略，但出现的章节不得乱序（否则触发section-orderwarning）。有意省略的章节可用omitted配置声明。
3. 至少定义primary颜色与排版令牌：缺失会触发missing-primary/missing-typographywarning，Agent 会自行生成默认值——如果不想让 Agent 自由发挥，就把它们定义清楚。
4. 颜色令牌命名遵循角色体系：primary/secondary/tertiary/neutral/surface/on-surface/error是推荐命名；Material 风格的surface-container-*、*-fixed色阶族可提供完整的状态覆盖。
5. 设计决策要在正文中给出"为什么"：例如本文档解释"深度只用色调变化不用阴影"（Brutalist 风格），以及"标题必须左对齐以维持刚性垂直轴"。这些上下文正是 Agent 在没有显式规则时做出正确风格决策的依据。

如果你要动手实践，仓库中还有更多可对照的完整样例：atmospheric-glass/DESIGN.md（玻璃拟态）、totality-festival/DESIGN.md（音乐节视觉）、以及 DESIGN-test.md（linter 测试基准，验证了解析器的颜色/排版/字号/字距解析行为）。运行npx @google/design.md lint即可对它们逐一校验，亲眼观察各规则的输出。

【免费下载链接】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