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、Dos and Donts提供设计理由与应用语境。规范的核心原则是令牌是规范性normative的值正文负责解释为什么以及怎么用。正文可以使用描述性颜色名如 Golden Retriever orange只要它能对应到系统化令牌名如primary即可Agent 读取令牌拿到精确数值读取正文拿到应用原则。Paws Paths 示例完整遵循了这一结构其 frontmatter 与正文共同勾勒出一套公园漫步的愉悦能量 高端专业服务的可靠性的视觉系统。下面是逐层解读。逐令牌拆解 Paws Paths 的 frontmatter顶层元数据--- name: Paws Paths ---顶层支持的可选字段依据 docs/spec.md 的 Schema 定义包括字段类型说明versionstring可选当前规范版本为alphanamestring设计系统名称descriptionstring可选设计系统描述omittedstring[] | OmittedSection[]可选声明有意省略的章节可抑制缺失章节类 lint 告警omitted的两种写法字符串形式- spacing或带理由的对象形式- section: rounded, reason: No rounded corners defined in brand book。在 Paws Paths 中未使用omitted因为八个章节与五类令牌全部齐备。colorsMaterial 风格的角色化色彩体系Paws Paths 的色彩令牌是一套典型的 Material 3 风格角色化体系包含 51 个令牌。其设计动机来自正文 Colors 一节以 **Golden Retriever 橙primary: #855300**驱动行动与能量以 **Sky Walk 蓝secondary: #0058be**提供管理任务与排程的冷静反衬。分组代表性令牌取值角色表面层级surface/surface-dim/surface-bright#f9f9ff/#d3daea/#f9f9ff背景明暗层级容器层级surface-container-lowest→surface-container-highest#ffffff→#dce2f3由低到高的容器底色阶梯文本on-surface/on-surface-variant#151c27/#534434主文本与次级文本Deep Charcoal主色系primary/primary-container/inverse-primary#855300/#f59e0b/#ffb95f主要动作、激活态、高亮次色系secondary/secondary-container#0058be/#2170e4次级信息、信任标识、导航强调第三色系tertiary/tertiary-container#00658b/#1abdff徽章、状态指示错误error/error-container#ba1a1a/#ffdad6错误反馈描边outline/outline-variant#867461/#d8c3ad边框与分隔固定变体primary-fixed系列 /secondary-fixed系列 /tertiary-fixed系列各三枚-fixed、-fixed-dim、on-*明暗场景下的固定色变体此外还有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供对比度校验使用原始格式在展示与导出时保留。typographyPlus Jakarta Sans 的 8 级排版体系Paws Paths 的排版全部基于Plus Jakarta Sans正文解释其选择理由圆润的字端与出色的可读性比标准几何无衬线体更亲和。8 个排版令牌构成完整层级令牌fontSizefontWeightlineHeightletterSpacing用途display44px80052px-0.02em大号展示标题headline-lg32px70040px-0.01em一级标题headline-md24px70032px—二级标题title-lg20px60028px—区块标题body-lg18px40028px—大号正文body-md16px40024px—常规正文如输入框label-md14px60020px0.01em按钮与元数据label-sm12px50016px—小号标签如状态徽章Typography 对象的完整属性依据 docs/spec.md包括fontFamilystring、fontSizeDimension、fontWeight数值YAML 中裸数字与带引号字符串等价、lineHeightDimension 或无单位数字——无单位数字表示相对fontSize的倍数是推荐的 CSS 实践、letterSpacingDimension以及可选的高级属性fontFeature映射 CSSfont-feature-settings与fontVariation映射 CSSfont-variation-settings。从正文排版章节可以提炼三条 Agent 应用原则Headlines 用粗体建立层级引导视线快速定位关键信息Body 用宽行高维持高级与干净的观感Labels 用中等/半粗字重保证小字号下的可辨识度。rounded 与 spacing8px 节奏与圆角语言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: 24pxrounded规范要求其为mapstring, Dimension尺度名可为任意描述性字符串常用xs/sm/md/lg/xl/full。Paws Paths 提供了 6 级其中full: 9999px用于胶囊形徽章。spacing规范允许mapstring, 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使用了字面量transparentbackground-color: transparent在 design_tokens.json 中被序列化为 alpha 为 0 的 sRGB 颜色说明组件的值既可以是字面量也可以是令牌引用。正文章节Agent 应用设计的完整语境frontmatter 之外DESIGN.md 的正文才是让 Agent 做出合理风格决策的关键。Paws Paths 的正文覆盖了除 Dos and Donts 外的全部规范章节顺序完全符合 docs/spec.md 的规范顺序OverviewBrand Style——品牌人格乐观、可信、活跃风格为Modern Corporate加上友好的人性化转折用干净布局与大面积留白降低忙碌宠物主人的认知负荷界面轻盈透气避免厚重边框改用柔和阴影与色调渐变。Colors——Golden Retriever 橙驱动行动与能量Sky Walk 蓝提供管理任务的冷静反衬Primary 用于主要动作/激活态/高亮Secondary 用于次级信息/信任标识/导航强调中性灰用于背景与边框营造premium感Deep Charcoal 用于全部主文本保证高可读性。Typography——Plus Jakarta Sans 的理由与三类用法见上文。Layout Spacing——Fixed Grid移动优先模型手持设备使用 4 列系统内容在大屏上居中并限制最大宽度让Paths用户旅程保持聚焦。Elevation Depth——采用Ambient Shadows与Tonal Layers定义垂直层级主背景用最浅的中性色调交互卡片在纯白表面上高一级阴影高度弥散柔和Blur 20-40px、Opacity 4-8%且混入一点主橙或次蓝以避免脏灰hover/tap 时元素轻微抬升、扩大阴影扩散以提供触觉反馈。Shapes——Rounded圆角语言呼应宠物的柔软特征主 CTA 按钮12pxrounded-lg显得厚重可点宠物档案与遛狗师卡片1.5remrounded-xl营造柔软容器感表单字段0.5rem保持专业又现代图标采用圆头圆角以与 UI 结构元素和谐。Components——按 Buttons Inputs、Cards Elevation、Lists Navigation 三个子节给出应用细则交互状态使用 150ms ease-in-out 的背景色过渡card-profile是英雄容器用rounded-xl 染色环境阴影营造悬浮感card-walk-stat在蓝色次级调色板内做高对比数据可视化列表项保持宽触摸目标、hover 用surface-container-highbadge-status用于宠物可用性/散步进度指示小字号下仍须保持排版可读。这七个章节加 frontmatter共同构成 Agent 落地界面的完整依据README 中对本项目的定位是Agent 读取此文件即可产出具有深墨标题、暖石灰背景与品牌 CTA 按钮的 UI——正文保证了风格方向令牌保证了数值精确。解析、校验与互操作从 DESIGN.md 到工程产物解析器如何读取 DESIGN.mdpackages/cli/src/linter/parser/handler.ts 使用unifiedremark-parseremark-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规则严重度检查内容broken-referror{colors.primary}这类令牌引用无法解析到已定义令牌missing-primarywarning定义了颜色但缺少primary——Agent 将自动生成一个contrast-ratiowarning组件backgroundColor/textColor对比度低于 WCAG AA 下限4.5:1orphaned-tokenswarning定义了颜色令牌但没有任何组件引用它token-summaryinfo汇总各分组令牌数量missing-sectionsinfo存在其他令牌时缺少可选章节如 spacing、roundedmissing-typographywarning定义了颜色但没有排版令牌——Agent 将使用默认字体section-orderwarning章节顺序违反规范顺序unknown-keywarning顶层 YAML 键疑似已知键的拼写错误如colours:→colors:自定义扩展键保持静默token-like-ignoredwarning未知顶层键带有令牌样式的值hex 色、字体族、尺寸暗示它被遗漏或拼错omitted-rulesinfo校验omitted配置中未知或冗余的章节其中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 与 DTCGexport子命令可以把 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.colors8 个排版令牌被拆解为fontFamily8 个条目与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文件结构开头以---包围 YAML frontmatter正文按 Overview → Colors → Typography → Layout → Elevation Depth → Shapes → Components → Dos and Donts 的顺序组织##章节不需要的章节可以省略但存在的章节必须保持顺序section-order规则会校验。至少定义primary色板missing-primary规则会告警多色板时按primary、secondary、tertiary、neutral的惯例命名并分配语义角色。颜色尽量用 hex#RRGGBB规范推荐其为默认格式以换取简洁性与广泛工具支持同时可以自由使用rgb()、oklch()乃至color-mix()——解析器全部支持。排版用无单位lineHeight如1.6规范明确这是推荐的 CSS 实践。组件用引用语法组合令牌components内允许引用复合排版对象hover/active/pressed 等变体用相关键名单独定义让 Agent 能感知全部状态。刻意省略的章节用omitted声明可以带reason避免 linter 误报。校验与导出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.jsonWindows 下若直接使用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考