DESIGN.md 实战：以 Meridian「制图师图集」为例编写面向 AI Agent 的设计系统规范-平芜编程栈

DESIGN.md 实战：以 Meridian「制图师图集」为例编写面向 AI Agent 的设计系统规范

【免费下载链接】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 实例 MERIDIAN.md 为骨架，系统讲解如何在 YAML frontmatter 中定义机器可读的设计令牌（color / typography / spacing），并在 Markdown 正文中为 AI Agent 提供人类可读的品牌叙事、排版原则与组件规范。读完本文，你将掌握 DESIGN.md 的标准结构、令牌命名与引用约定、各章节（Section）的写法要点，以及如何用仓库内置的 lint 命令与源码解析流程校验自己的 DESIGN.md 文件。

一、DESIGN.md 是什么：一个文档、两种语言

根据格式规范 docs/spec.md，DESIGN.md 是"自包含、纯文本"的设计系统描述文件，其核心目标是为编码代理（coding agent）提供持久、结构化的视觉身份理解。一个文件中同时承载两种信息层：

YAML frontmatter：以---开始、以---结束的机器可读设计令牌块，规范定义了colors、typography、rounded、spacing、components等令牌组；
Markdown 正文：以##小节组织的人类可读设计原理与使用指南，正文中可以用描述性颜色名（如 "Antique Gold"）对应系统性令牌名（如tertiary）。

规范明确：令牌是规范性取值（normative values），正文为应用语境提供上下文。这一点在 MERIDIAN.md 中得到完整示范——frontmatter 里的精确色值、字号、行高，配合正文里 "为什么用这种衬线体" 的叙事，共同构成 Agent 可执行的设计约束。

MERIDIAN.md 是一个虚构品牌 "The Cartographer's Atlas（制图师图集）" 的完整 DESIGN.md 样例，也是本仓库 linter 的 fixtures 之一，与其同级的还有 ALPINE_OBSERVATORY.md 等样例，共同验证解析器与校验规则。

二、MERIDIAN.md 的 YAML 令牌区：逐字段拆解

MERIDIAN.md 的 frontmatter 声明了name、colors、typography、spacing四组顶层内容，完整如下（节选关键结构）：

--- name: The Cartographer's Atlas colors: surface: '#0f131c' primary: '#c3c6d7' on-primary: '#2c303d' secondary: '#b9c8dc' tertiary: '#ecc246' error: '#ffb4ab' ... typography: display-xl: fontFamily: Newsreader fontSize: 84px fontWeight: '700' lineHeight: '1.1' letterSpacing: 0.05em ... spacing: unit: 8px gutter: 24px margin: 64px panel-padding: 120px ---

2.1 name 与顶层字段

name是必填字符串，标记设计系统名称。规范 docs/spec.md 还允许可选的version（当前为"alpha"）、description、omitted（声明有意省略的令牌组，用于抑制 lint 的缺失警告，可写成字符串或带reason的对象）。

2.2 colors 令牌：Material 式表面色体系

MERIDIAN.md 的colors令牌组包含 40+ 个令牌，覆盖了surface、surface-container-*、on-surface、inverse-surface、outline、primary/secondary/tertiary及其-container、-fixed变体、error、background等，是一套接近 Material 3 语义的深色表面体系。核心取值如下：

令牌	色值	设计角色
`surface`	`#0f131c`	页面基底（深色画布）
`surface-container-lowest`	`#0a0e16`	最深一级容器，用于与基底形成分层
`surface-container`	`#1c2028`	常规内容容器
`on-surface`	`#dfe2ee`	基底上的前景文字
`outline`	`#909096`	发丝线边框、分隔线
`primary`	`#c3c6d7`	主强调色（冷银蓝灰）
`tertiary`	`#ecc246`	金褐色点缀色（Antique Gold 的令牌对应）
`error`	`#ffb4ab`	错误态

规范要求colors中至少必须定义primary，多调色板时推荐按primary、secondary、tertiary、neutral的次序命名；MERIDIAN.md 正是按此约定组织。所有颜色值会在内部统一转换为 sRGB 用于 WCAG 对比度校验，原文格式则保留用于展示与导出（见 docs/spec.md 的 Color 一节）。

2.3 typography 令牌：三层字体系统

typography令牌组为每个文本层级定义fontFamily、fontSize、fontWeight、lineHeight、letterSpacing：

层级令牌	字体	字号	字重	行高	用途
`display-xl`	Newsreader	84px	700	1.1	巨幅展示标题
`headline-lg`	Newsreader	48px	600	1.2	一级标题
`headline-md`	Newsreader	32px	500	1.3	二级标题
`body-lg`	Noto Serif	20px	400	1.7	长文正文
`body-md`	Noto Serif	17px	400	1.7	常规正文
`label-caps`	Space Grotesk	12px	500	1.5	全大写标注、标签
`quote-editorial`	Newsreader	28px	400	1.4	编辑性引言

注意fontWeight在 YAML 中写成带引号的'700'，解析器会将其规范化为数字（测试 fixture.test.ts 断言'700'解析为700）；lineHeight的'1.1'这类无单位数字被解释为相对fontSize的倍数——这是规范推荐的 CSS 写法。

2.4 spacing 令牌：4 级间距尺度

spacing: unit: 8px gutter: 24px margin: 64px panel-padding: 120px

spacing是map<string, Dimension | number>，既接受带单位的维度（px/em/rem），也接受无单位数字（如列数、比例）。MERIDIAN.md 用语义化键名unit/gutter/margin/panel-padding而非sm/md/lg刻度——规范允许任意描述性字符串作为键，这印证了令牌命名的灵活性。

三、正文 Section：从 Brand & Style 到 Components 的叙事骨架

规范定义了 8 个标准小节及其顺序（Overview/Brand & Style→Colors→Typography→Layout→Elevation & Depth→Shapes→Components→Do's and Don'ts），MERIDIAN.md 依次实现了前七个，可作为照抄的模板。

3.1 Brand & Style：一锤定音的总体气质

MERIDIAN.md 的开篇用两段话定义了品牌基调：知性权威与发现感，目标受众是重视长篇调查报道、历史语境与精确数据的受众；美学路线是High-Contrast / Minimalist（高对比 / 极简），拒绝柔和阴影与圆角，追求"被一盏高亮度台灯照亮的幽暗图书馆"般的专注情绪。规范指出，该小节是 Agent 在"没有明确规则或令牌时"做高层级风格决策的兜底语境，因此值得用明确形容词写透。

3.2 Colors：四色叙事的正文版

正文将调色板收敛为四种核心色调，与令牌一一对应：

Obsidian Canvas（#080C14）：基础地面，深色空洞，让内容浮现；
Ink Navy（#0A0E1A）：主要内容容器与标题，与背景形成微妙层次；
Slate Structure（#2C3A4A）：技术性色彩，用于发丝线边框、网格线与功能性 UI；
Antique Gold（#C9A227）：唯一的强强调色，必须克制使用，理想情况每屏仅出现一次，充当最重要操作或数据点的"灯塔"。

注意正文色值与 frontmatter 色值存在有意差异（如正文写#C9A227，令牌tertiary为#ecc246）。这正是规范反复强调的：令牌是规范性取值，正文中的描述性色名仅提供语义参照。

3.3 Typography：衬线叙事 × 无衬线标注

正文将字体分为三层，与令牌一一对应：

Headlines — Newsreader：高对比笔画的锐利衬线，大字号下加宽字距（tracking）强化"纪念碑式"体量；
Body — Noto Serif：长时间阅读的温暖与易读性，1.7 行高是强制要求，防止文本块显得密集；
Labels & UI — Space Grotesk：全大写 + 宽字距，模仿地形图上的坐标标注。

3.4 Layout & Spacing：全出血面板网格

布局采用Full-Bleed Panel Grid（全出血面板网格）并配合 scroll-snap，每个面板代表体验中的一个"章节 / 地图页"：

偏移文本块：避免居中，内容应偏置在垂直中线左侧或右侧，营造编辑性节奏；
交替面板：视觉重量在面板间轮换（如文字密集的 Slate 面板之后接全屏图像 / 数据可视化）；
边距：慷慨的 64px+ 边距保证内容不拥挤，维持"图集"的辽阔感。

3.5 Elevation & Depth：扁平制图学，严禁阴影

与制图学的扁平性质一致，阴影被严格禁止，深度只通过三种手段构建：

色调阶梯（Tonal Stepping）：将 Ink Navy 层叠于 Obsidian 之上；
发丝线边框：1px 实线 Slate 定义面板或组件边界；
Z 轴分层：固定导航、标签等元素以 100% 不透明度浮于内容之上，靠色彩对比而非模糊/阴影突出。

3.6 Shapes：0px 圆角，直角即精度

形状语言定义为0px border radius：所有容器、按钮与装饰元素必须使用锐利直角，体现制图工具的精度与建筑制图的刚性线条。没有例外——连圆形头像与图标也应置于方形/矩形容器中。

3.7 Components：五个组件的精修细节

Buttons：主按钮用 Antique Gold 填充 + Navy 文字，矩形（0px 圆角），无 hover 阴影，hover 态以 1px Slate 描边或金色轻微偏移表示；
Pull Quotes：大字 Newsreader 斜体，左侧 2px 竖向金色边框锚定，常置于"偏移"布局区以打破正文流；
Lists & Annotations：项目符号/编号用 Label 字体（Space Grotesk），条目间以 Slate 水平发丝线分隔；
Input Fields：Navy 表面上的 1px Slate 描边，聚焦时边框变金，标签恒位于字段上方，全大写宽字距 Space Grotesk；
Data Panels：独特的"Coordinate Panel"（坐标面板）——视口角落的小型固定 UI，以 Label 字体展示进度或元数据，模仿地图图例。

四、源码侧印证：令牌如何被解析与校验

4.1 解析器：frontmatter 与 fenced yaml 双模式

解析入口是 packages/cli/src/linter/parser/handler.ts。ParserHandler.execute()使用unified+remark-parse+remark-frontmatter构建 AST，然后遍历节点收集三类信息：

yaml 节点（---frontmatter）与fenced yaml/yml 代码块，均作为令牌来源；
##二级标题，作为 Section 列表（sections）；
每个 Section 的原文切片（documentSections）。

随后mergeCodeBlocks()会检测跨块重复的顶层键并返回DUPLICATE_SECTION错误（对应规范中 "Duplicate section heading → Error" 的消费者行为表）。toDesignSystem()将原始 YAML 映射为结构化的colors/typography/rounded/spacing/components/omitted字段。也就是说，MERIDIAN.md 的 frontmatter 会先经过这一层校验性解析，才能进入 lint 阶段。

4.2 校验规则：11 条默认规则的靶向检查

解析后的设计系统状态会交给 packages/cli/src/linter/linter/runner.ts 的runLinter()，它按序执行 packages/cli/src/linter/linter/rules/index.ts 中注册的 11 条默认规则：

brokenRef、missingPrimary、contrastCheck、orphanedTokens、tokenSummary、missingSections、missingTypography、sectionOrder、unknownKey、tokenLikeIgnored、omitted。

对 MERIDIAN.md 这类规范文件，最有意义的检查包括：missingPrimary（colors必须含primary）、sectionOrder（Section 必须按规范顺序出现）、contrastCheck（颜色转 sRGB 后做 WCAG 对比度评估）、brokenRef（{path.to.token}引用是否悬空）。每项 rule 都有独立测试文件（如 missing-primary.test.ts、section-order.test.ts），fixture 级测试则通过 fixture.test.ts 对整份 DESIGN.md 做端到端断言。

4.3 CLI 实战：校验你自己的 DESIGN.md

仓库提供lint命令用于验证文件的"结构正确性"，入口见 packages/cli/src/commands/lint.ts：

bun run cli lint path/to/DESIGN.md # JSON 输出（默认） bun run cli lint path/to/DESIGN.md -f text # 纯文本输出 cat path/to/DESIGN.md | bun run cli lint - # 从 stdin 读取

命令行为：读取文件 → 调用lint(content)得到{ findings, summary }→ 打印报告；只要存在error级别 finding，进程退出码即为 1（process.exitCode = report.summary.errors > 0 ? 1 : 0），适合接入 CI 门槛。

五、从样例到自己的 DESIGN.md：可复用的写作清单

对照 MERIDIAN.md 与仓库其他示例，编写一份合格 DESIGN.md 的检查清单如下：

frontmatter 必填：name+ 至少colors.primary；无 YAML 时解析器返回NO_YAML_FOUND错误（见 parser/handler.ts）；
令牌优先：所有正文提到的关键色值、字号都要在令牌区有对应取值，正文中的命名色只作语义注释；
Section 顺序：按 Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Do's and Don'ts 排列，避免sectionOrder规则报警；不需要的小节可省略；
深色 / 浅色体系都要定义on-*与container层级：MERIDIAN.md 与 ALPINE_OBSERVATORY.md 都提供了完整的 Material 式表面色阶梯，可当作深色主题模板直接改写；
无圆角 / 禁阴影等极端约束要写成"禁止"句式：规范与正文都以明确的 "strictly prohibited"、"No exceptions" 句式约束 Agent 行为，避免歧义；
写完立即 lint：用上文 CLI 命令验证零 error，再提交。

如需参考浅色主题与不同字体组合，可对比 examples/paws-and-paths/DESIGN.md（Material 风格浅色色板 + Plus Jakarta Sans / Space Grotesk）；该文件同时被 Tailwind v4 导出测试引用（见 packages/cli/src/linter/tailwind/v4/fixture.test.ts），说明同一份 DESIGN.md 令牌还可流向 Tailwind@theme生成。

结语

MERIDIAN.md 的价值在于它完整演示了 DESIGN.md 的"双轨"写法：机器可读的令牌区给出精确数值，人类可读的正文区给出审美意图与使用边界，二者互为表里。对 Agent 而言，前者是可执行的规则，后者是决策的语境；对设计团队而言，这是一份既能进 CI 校验、又能被模型消费的"活的设计真源"。以它为模板，配合本仓库的 lint 工具与解析源码，任何人都能在几小时内产出一份高质量、可验证、可被 AI 代理稳定消费的设计系统文档。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考