Paws Paths 实战解读：用 DESIGN.md 为编码 Agent 定义一套完整的设计系统

Paws & Paths 实战解读：用 DESIGN.md 为编码 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 是一种面向编码 Agent 的视觉身份描述格式：它以 YAML frontmatter 承载机器可读的设计令牌（Design Tokens），以 Markdown 正文承载人类可读的设计理由，二者合二为一，让 AI 在设计会话之间保持对品牌视觉系统的一致理解。本文以仓库示例 examples/paws-and-paths/DESIGN.md 为完整蓝本，逐层拆解一个真实产品（宠物遛弯与宠物护理平台）的设计系统文件——从 50+ 个色彩令牌、8 级排版尺度、圆角与间距体系，到带{path.to.token}引用语法的组件令牌，再到解析、lint 校验与 Tailwind / DTCG 互操作导出。读完你将掌握：如何阅读、验证、扩展一份 DESIGN.md，以及如何把它转换成可直接落地的tailwind.config.js与tokens.json。

DESIGN.md 的双层结构：令牌是规范值，正文是上下文

依据格式规范 docs/spec.md 的定义，DESIGN.md 是一个自包含、纯文本的设计系统表示：一个文件包含两个部分——可选的 YAML frontmatter 与 Markdown 正文。

• YAML frontmatter：以行首精确为---的行开始、以另一个精确的---行结束，其中声明机器可读的设计令牌，包括colors、typography、rounded、spacing、components等分组。
• Markdown 正文：以##二级标题组织的若干章节（Overview/Brand & Style、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts），提供设计理由与应用语境。

规范的核心原则是：令牌是规范性（normative）的值，正文负责解释"为什么"以及"怎么用"。正文可以使用描述性颜色名（如 "Golden Retriever" orange），只要它能对应到系统化令牌名（如primary）即可；Agent 读取令牌拿到精确数值，读取正文拿到应用原则。

Paws & Paths 示例完整遵循了这一结构，其 frontmatter 与正文共同勾勒出一套"公园漫步的愉悦能量 + 高端专业服务的可靠性"的视觉系统。下面是逐层解读。

逐令牌拆解 Paws & Paths 的 frontmatter

顶层元数据

--- name: Paws & Paths ---

顶层支持的可选字段（依据 docs/spec.md 的 Schema 定义）包括：

omitted的两种写法：字符串形式- spacing；或带理由的对象形式- section: rounded, reason: "No rounded corners defined in brand book"。在 Paws & Paths 中未使用omitted，因为八个章节与五类令牌全部齐备。

colors：Material 风格的角色化色彩体系

Paws & Paths 的色彩令牌是一套典型的 Material 3 风格角色化体系，包含 51 个令牌。其设计动机来自正文 Colors 一节：以 **"Golden Retriever" 橙（primary: #855300）**驱动行动与能量，以 **"Sky Walk" 蓝（secondary: #0058be）**提供管理任务与排程的冷静反衬。

此外还有surface-tint、background/on-background、inverse-surface/inverse-on-surface等令牌，构成一套完整的明暗双态可映射色板（darkMode: "class"在配套的 tailwind.config.js 中开启，正是为这套体系的暗色变体准备的）。

在底层，颜色字符串由 packages/cli/src/linter/model/color-parser.ts 的parseCssColor()解析：它支持 hex（#RGB/#RGBA/#RRGGBB/#RRGGBBAA）、命名色（内置约 140 个 CSS 命名色表）、rgb()/rgba()/hsl()/hsla()/hwb()、宽色域lab()/lch()/oklab()/oklch()，甚至递归解析color-mix(in srgb, ...)（最大嵌套深度 32 层，防止栈溢出）。解析结果统一转换为 sRGB 并计算 WCAG 相对亮度（computeLuminance，见 color-parser.ts），供对比度校验使用；原始格式在展示与导出时保留。

typography：Plus Jakarta Sans 的 8 级排版体系

Paws & Paths 的排版全部基于Plus Jakarta Sans（正文解释其选择理由：圆润的字端与出色的可读性，比标准几何无衬线体更亲和）。8 个排版令牌构成完整层级：

Typography 对象的完整属性（依据 docs/spec.md）包括fontFamily（string）、fontSize（Dimension）、fontWeight（数值，YAML 中裸数字与带引号字符串等价）、lineHeight（Dimension 或无单位数字——无单位数字表示相对fontSize的倍数，是推荐的 CSS 实践）、letterSpacing（Dimension），以及可选的高级属性fontFeature（映射 CSSfont-feature-settings）与fontVariation（映射 CSSfont-variation-settings）。

从正文排版章节可以提炼三条 Agent 应用原则：Headlines 用粗体建立层级，引导视线快速定位关键信息；Body 用宽行高维持"高级与干净"的观感；Labels 用中等/半粗字重保证小字号下的可辨识度。

rounded 与 spacing：8px 节奏与圆角语言

rounded: sm: 0.25rem DEFAULT: 0.5rem md: 0.75rem lg: 1rem xl: 1.5rem full: 9999px spacing: base: 8px xs: 4px sm: 12px md: 24px lg: 40px xl: 64px gutter: 16px margin: 24px

• rounded：规范要求其为map<string, Dimension>，尺度名可为任意描述性字符串，常用xs/sm/md/lg/xl/full。Paws & Paths 提供了 6 级，其中full: 9999px用于胶囊形徽章。
• spacing：规范允许map<string, Dimension | number>，值既可以是带单位尺寸，也可以是无单位数字（例如列数或比例）。Paws & Paths 的间距严格基于 8px 体系（xs是 4px 半步长，用于微调），正文 Layout & Spacing 一节明确："Whitespace 采用 generous 哲学，区块纵向分隔使用lg/xl，节奏严格基于 8px 刻度"。gutter与margin则是栅格语义的间距令牌。

components：带引用语法的组件令牌

Paws & Paths 定义了 10 个组件令牌，全部通过{path.to.token}引用语法组合底层令牌。组件名遵循"基础名 + 状态后缀"的变体约定（hover 态），这是规范明确推荐的模式——Agent 会综合所有变体做出恰当的样式决策。

components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" typography: "{typography.label-md}" rounded: "{rounded.lg}" padding: "{spacing.md}" button-primary-hover: backgroundColor: "{colors.primary-container}" textColor: "{colors.on-primary-container}" # ... button-secondary / button-secondary-hover ... card-profile: backgroundColor: "{colors.surface-container-lowest}" rounded: "{rounded.xl}" padding: "{spacing.md}" card-walk-stat: backgroundColor: "{colors.secondary-container}" textColor: "{colors.on-secondary-container}" rounded: "{rounded.md}" padding: "{spacing.sm}" input-field: backgroundColor: "{colors.surface-container-low}" textColor: "{colors.on-surface}" typography: "{typography.body-md}" rounded: "{rounded.DEFAULT}" padding: "{spacing.sm}" list-item-walker: backgroundColor: transparent padding: "{spacing.sm}" rounded: "{rounded.md}" list-item-walker-hover: backgroundColor: "{colors.surface-container-high}" badge-status: backgroundColor: "{colors.tertiary-container}" textColor: "{colors.on-tertiary-container}" typography: "{typography.label-sm}" rounded: "{rounded.full}" padding: "{spacing.xs}"

关于引用语法，docs/spec.md 有一条关键约束：令牌引用必须用花括号包裹，并指向 YAML 树中的对象路径；对于大多数令牌组，引用必须指向原始值（如{colors.primary}），不能指向组本身（如{colors}）；但在components段内，允许引用复合值（如{typography.label-md}——一个排版对象）。Paws & Paths 恰好示范了这两种用法：组件同时引用原始颜色值和复合排版对象。

组件属性的合法键（Component Property Tokens）为：backgroundColor、textColor、typography、rounded、padding、size、height、width。注意list-item-walker使用了字面量transparent（background-color: transparent在 design_tokens.json 中被序列化为 alpha 为 0 的 sRGB 颜色），说明组件的值既可以是字面量，也可以是令牌引用。

正文章节：Agent 应用设计的完整语境

frontmatter 之外，DESIGN.md 的正文才是让 Agent 做出合理风格决策的关键。Paws & Paths 的正文覆盖了除 "Do's and Don'ts" 外的全部规范章节，顺序完全符合 docs/spec.md 的规范顺序：

1. Overview（Brand & Style）——品牌人格：乐观、可信、活跃；风格为Modern Corporate加上友好的人性化转折；用干净布局与大面积留白降低忙碌宠物主人的认知负荷；界面轻盈透气，避免厚重边框，改用柔和阴影与色调渐变。
2. Colors——"Golden Retriever" 橙驱动行动与能量，"Sky Walk" 蓝提供管理任务的冷静反衬；Primary 用于主要动作/激活态/高亮，Secondary 用于次级信息/信任标识/导航强调，中性灰用于背景与边框营造"premium"感，Deep Charcoal 用于全部主文本保证高可读性。
3. Typography——Plus Jakarta Sans 的理由与三类用法（见上文）。
4. Layout & Spacing——Fixed Grid移动优先模型，手持设备使用 4 列系统；内容在大屏上居中并限制最大宽度，让"Paths"（用户旅程）保持聚焦。
5. Elevation & Depth——采用Ambient Shadows与Tonal Layers定义垂直层级：主背景用最浅的中性色调，交互卡片在纯白表面上"高一级"；阴影高度弥散柔和（Blur 20-40px、Opacity 4-8%），且混入一点主橙或次蓝以避免"脏灰"；hover/tap 时元素轻微抬升、扩大阴影扩散以提供触觉反馈。
6. Shapes——Rounded圆角语言，呼应宠物的柔软特征：主 CTA 按钮12px（rounded-lg）显得厚重可点，宠物档案与遛狗师卡片1.5rem（rounded-xl）营造柔软容器感，表单字段0.5rem保持专业又现代，图标采用圆头圆角以与 UI 结构元素和谐。
7. Components——按 Buttons & Inputs、Cards & Elevation、Lists & Navigation 三个子节给出应用细则：交互状态使用 150ms ease-in-out 的背景色过渡；card-profile是"英雄容器"，用rounded-xl+ 染色环境阴影营造"悬浮"感，card-walk-stat在蓝色次级调色板内做高对比数据可视化；列表项保持宽触摸目标、hover 用surface-container-high；badge-status用于宠物可用性/散步进度指示，小字号下仍须保持排版可读。

这七个章节加 frontmatter，共同构成 Agent 落地界面的完整依据：README 中对本项目的定位是"Agent 读取此文件即可产出具有深墨标题、暖石灰背景与品牌 CTA 按钮的 UI"——正文保证了风格方向，令牌保证了数值精确。

解析、校验与互操作：从 DESIGN.md 到工程产物

解析器如何读取 DESIGN.md

packages/cli/src/linter/parser/handler.ts 使用unified+remark-parse+remark-frontmatter将文件解析为 AST，支持两种 YAML 嵌入模式：frontmatter（---包围）与 fenced yaml 代码块。它收集所有yaml节点与yaml/yml代码块，并按##二级标题切分文档章节。关键行为包括：

• 未找到任何 YAML 时返回NO_YAML_FOUND错误（可恢复）；
• YAML 语法错误返回YAML_PARSE_ERROR；
• 跨多个块出现重复顶层键返回DUPLICATE_SECTION错误——这与规范中"重复章节标题视为错误、拒绝文件"的消费者行为一致；
• 所有错误以ParserResult形式返回，解析器本身从不抛出异常。

lint：结构校验与 WCAG 对比度检查

CLI 的lint命令（实现于 packages/cli/src/commands/lint.ts）调用lint(content)生成{ findings, summary }并输出 JSON，发现 error 时退出码为 1。lint子命令支持--format json以及从 stdin 读取（cat DESIGN.md | ... lint -）。

linter 默认执行 11 条规则（规则清单见 packages/cli/src/linter/linter/rules/index.ts 的DEFAULT_RULE_DESCRIPTORS）：

其中section-order规则（见 packages/cli/src/linter/linter/rules/section-order.ts）通过CANONICAL_ORDER与SECTION_ALIASES（即 "Brand & Style"→Overview、"Layout & Spacing"→Layout、"Elevation"→Elevation & Depth 这类别名映射）解析章节，检查任意相邻两个已知章节是否逆序。contrast-ratio与missing-primary规则则直接消费 color-parser.ts 计算出的相对亮度与 sRGB 值。linter 还以库形式开放：import { lint } from '@google/design.md/linter'，返回report.findings、report.summary与report.designSystem。

导出：Tailwind 与 DTCG

export子命令可以把 DESIGN.md 令牌转换为工程可直接使用的格式：

• --format json-tailwind（别名tailwind）→ Tailwind v3theme.extendJSON 配置对象；
• --format css-tailwind→ Tailwind v4 的@theme { ... }CSS 块（--color-*、--font-*、--text-*、--leading-*、--tracking-*、--font-weight-*、--radius-*、--spacing-*命名空间）；
• --format dtcg→ W3C Design Tokens Format Module 的tokens.json。

Paws & Paths 示例目录正好提供了这两个导出产物的真实样例，可以直接对照学习：

• examples/paws-and-paths/tailwind.config.js：把 51 个颜色令牌映射为theme.extend.colors；8 个排版令牌被拆解为fontFamily（8 个条目）与fontSize（每个条目携带lineHeight、letterSpacing、fontWeight元组）；borderRadius与spacing原样映射。该文件刻意排除了组件令牌——正如 examples/paws-and-paths/README.md 所说明的，Tailwind 的 utility-first 方式通过组合这些原语来表达组件样式。
• examples/paws-and-paths/design_tokens.json：所有令牌（包含组件级令牌）被序列化为 DTCG 格式——颜色带colorSpace: "srgb"与components数组、排版拆为fontSize: { value: 44, unit: "px" }结构、transparent被编码为 alpha 0 的 sRGB 颜色。该格式可与 Figma、Style Dictionary 等令牌管线互操作。

这套"一份 DESIGN.md → lint 校验 → export 生成 Tailwind/DTCG"的工作流，正是 DESIGN.md 作为"人与 Agent 共同维护的活的事实源（living source of truth）"的落地方式。

编写你自己的 DESIGN.md：实践清单

基于对 Paws & Paths 与格式规范的综合分析，可以从零开始编写一份合格的 DESIGN.md：

1. 文件结构：开头以---包围 YAML frontmatter，正文按 Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts 的顺序组织##章节；不需要的章节可以省略，但存在的章节必须保持顺序（section-order规则会校验）。
2. 至少定义primary色板：missing-primary规则会告警；多色板时按primary、secondary、tertiary、neutral的惯例命名并分配语义角色。
3. 颜色尽量用 hex（#RRGGBB）：规范推荐其为默认格式以换取简洁性与广泛工具支持；同时可以自由使用rgb()、oklch()乃至color-mix()——解析器全部支持。
4. 排版用无单位lineHeight（如1.6）：规范明确这是推荐的 CSS 实践。
5. 组件用引用语法组合令牌：components内允许引用复合排版对象；hover/active/pressed 等变体用相关键名单独定义，让 Agent 能感知全部状态。
6. 刻意省略的章节用omitted声明：可以带reason，避免 linter 误报。
7. 校验与导出：

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

（Windows 下若直接使用design.md二进制名与 Markdown 文件关联冲突，可改用npx -p @google/design.md designmd ...的无点别名。）

总结

Paws & Paths 是一份结构完整、可以直接当作模板研读的 DESIGN.md 实例：51 个色彩令牌、8 级排版、6 级圆角、8 个间距刻度与 10 个组件变体，配合七个章节的正文语境，完整演示了"机器可读的精确值 + 人类/Agent 可读的设计理由"这一 DESIGN.md 格式的核心哲学。配合 docs/spec.md 的 Schema 定义、packages/cli/src/linter/parser/handler.ts 的解析实现、11 条 lint 规则，以及 examples/paws-and-paths/tailwind.config.js 与 examples/paws-and-paths/design_tokens.json 两个真实导出产物，你可以完整复现"定义 → 校验 → 导出 → 交付给 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