DESIGN.md 格式实战以 Neo-Esoteric Monument 为例撰写面向编码 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导读本文以本仓库 linter 测试样例 packages/cli/src/linter/fixtures/NEO_ESOTERIC_MONUMENT.md 为完整范例逐层拆解 DESIGN.md 格式的 YAML 前端数据设计令牌与 Markdown 正文设计意图的编写方式并对照 docs/spec.md 中的规范与 linter 源码说明一份合格的 DESIGN.md 应当如何组织、会被哪些规则校验、以及如何把它接入lint、diff、export等 CLI 工作流。读完本文你将掌握用一份纯文本文件向编码 Agent 描述完整视觉身份的完整方法并能独立把任意设计系统写成可通过规范校验的 DESIGN.md。一、背景DESIGN.md 是什么DESIGN.md 是面向编码 Agent 的视觉身份描述格式。它用一份自包含、纯文本的文档承载一个设计系统的全部信息**YAML 前端数据front matter**提供机器可读的设计令牌确切的值Markdown 正文提供人类可读的设计理由这些值为何存在、如何应用。正如 README.md 所述Tokens give agents exact values. Prose tells themwhythose values exist and how to apply them.这套格式的令牌体系借鉴了 W3C Design Token 规范中的类型化令牌分组colors、typography、spacing与{path.to.token}引用语法见 docs/spec.md 第 12-15 行并且可以方便地转换为tokens.json、Figma variables 与 Tailwind theme 配置。格式目前处于alpha版本规范、令牌 schema 与 CLI 都在积极演进中。一个关键事实本仓库的packages/cli/src/linter/fixtures/目录存放的是 linter 的测试样例fixturesNEO_ESOTERIC_MONUMENT.md正是其中之一——它是一份结构完整、风格统一的 DESIGN.md 样例覆盖了前端数据与全部正文章节非常适合作为学习该格式的标准答案来逐行研读。二、认识 Neo-Esoteric Monument一份完整的 DESIGN.md 样例先看这份文件的整体骨架packages/cli/src/linter/fixtures/NEO_ESOTERIC_MONUMENT.md ├── 第 1-87 行YAML 前端数据front matter │ ├── name │ ├── colors完整 Material 3 风格调色板50 个颜色令牌 │ ├── typography5 个排版层级 │ └── spacing5 个间距令牌 └── 第 89 行起Markdown 正文 ├── ## Brand Style ├── ## Colors ├── ## Typography ├── ## Layout Spacing ├── ## Elevation Depth ├── ## Shapes └── ## Components对照 docs/spec.md 的规范这份文档没有Dos and Donts章节、也没有rounded令牌组——根据规范第 102 行章节可省略、第 365-374 行消费者对未知/缺失内容的宽容处理的设计这些都是允许的。这也恰好展示了 DESIGN.md可裁剪、按需组织的设计哲学。三、前端数据逐段拆解机器可读的令牌层3.1 name文档的身份标识name: Neo-Esoteric Monumentschema中name是必填字符串docs/spec.md 第 45 行其余顶层键version、description、omitted均为可选。规范中推荐的version当前值为alpha。3.2 colors完整调色板这份样例的colors组非常值得研读——它几乎完整采用了 Material 3M3风格的令牌命名体系colors: surface: #fbf9f4 surface-dim: #dbdad5 surface-bright: #fbf9f4 surface-container-lowest: #ffffff surface-container-low: #f5f4ef surface-container: #efeee9 surface-container-high: #e9e8e3 surface-container-highest: #e3e2de on-surface: #1b1c19 on-surface-variant: #4d4545 inverse-surface: #30312e inverse-on-surface: #f2f1ec outline: #7f7575 outline-variant: #d0c4c4 surface-tint: #615d5d primary: #000000 on-primary: #ffffff primary-container: #1d1b1b on-primary-container: #878382 inverse-primary: #cbc5c5 secondary: #745b1d on-secondary: #ffffff secondary-container: #fedc91 on-secondary-container: #785f21 tertiary: #000000 on-tertiary: #ffffff tertiary-container: #410004 on-tertiary-container: #dd5853 error: #ba1a1a on-error: #ffffff error-container: #ffdad6 on-error-container: #93000a primary-fixed: #e7e1e1 primary-fixed-dim: #cbc5c5 on-primary-fixed: #1d1b1b on-primary-fixed-variant: #494646 secondary-fixed: #ffdf9a secondary-fixed-dim: #e3c37a on-secondary-fixed: #251a00 on-secondary-fixed-variant: #5a4305 tertiary-fixed: #ffdad7 tertiary-fixed-dim: #ffb3ad on-tertiary-fixed: #410004 on-tertiary-fixed-variant: #8a1b1d background: #fbf9f4 on-background: #1b1c19 surface-variant: #e3e2de几点关键观察语义化命名surface/on-surface对、primary/on-primary对、-container层级与-fixed变体遵循了 docs/spec.md 第 356-360 行推荐的令牌名primary、secondary、tertiary、neutral、surface、on-surface、error以及 M3 惯例。规范明确说明exact mapping from color palettes to color tokens may follow any consistent naming convention第 150 行所以这套命名完全合规。陌生令牌名会被宽容接受surface-container-high这类不在推荐列表里的名字正是 docs/spec.md 第 372-373 行Consumer Behavior表格中明确举例的可接受场景surface-container-high: #ede7dd消费者应Accept if value is valid。格式选择全部使用#RRGGBB十六进制。规范第 63-73 行说明颜色支持 hex、命名色、rgb()/hsl()/hwb()、宽色域oklch()/oklab()/lch()/lab()以及color-mix()内部统一转 sRGB 用于 WCAG 对比度计算但原始格式保留用于展示与导出#RRGGBB因简单且工具支持广泛而被推荐为默认写法——这份样例正是最佳实践。must 有一个primary规范第 127 行要求at least theprimarycolor palette must be defined。这里primary: #000000墨黑与正文Rich Charcoal的设定一致。3.3 typography五个排版层级typography: display-serif: fontFamily: Newsreader fontSize: 48px fontWeight: 400 lineHeight: 1.1 letterSpacing: -0.02em quote-editorial: fontFamily: Newsreader fontSize: 24px fontWeight: 400 lineHeight: 1.4 body-main: fontFamily: Inter fontSize: 16px fontWeight: 400 lineHeight: 1.6 letterSpacing: 0.01em metadata-caps: fontFamily: Inter fontSize: 11px fontWeight: 700 lineHeight: 1.2 letterSpacing: 0.15em label-small: fontFamily: Inter fontSize: 13px fontWeight: 500 lineHeight: 1 letterSpacing: 0.05em对照 docs/spec.md 第 75-84 行的 Typography schemafontFamilystring、fontSizeDimension必填fontWeight可以是裸数字或引号字符串规范第 77 行明确both are equivalent样例中400的引号写法合法lineHeight接受带单位 Dimension24px或无单位数字1.6、1.1无单位数字表示相对fontSize的倍数——这正是 CSS 推荐做法letterSpacing为 Dimension样例的负值-0.02em合法em是规范第 85 行承认的三种单位之一px、em、rem可选字段fontFeature、fontVariation用于配置font-feature-settings与font-variation-settings样例未使用。这里采用的是语义化命名display-serif、quote-editorial、body-main、metadata-caps、label-small属于规范第 169 行描述的语义类别 尺寸细分惯例的合理变体。新闻衬线体 Newsreader 与通用无衬线 Inter 的高对比双字体策略在正文 Typography 一节有完整阐述见下。3.4 spacing间距令牌spacing: unit: 4px margin-page: 64px gutter: 32px block-gap: 48px element-gap: 16pxspacing是mapstring, Dimension | numberdocs/spec.md 第 240 行除带单位的值外也允许无单位数字如列数、比例。样例用命名键margin-page、gutter、block-gap、element-gap表达了4px 基线 大幅留白的网格节奏与正文 Layout Spacing 一节相互印证——正文描述数学节奏令牌给出确切数值这正是prose 提供语境、token 是规范值的教科书式配合。3.5 缺失的 rounded 与 omitted 机制这份样例没有rounded令牌组。规范第 87-96 行提供了omitted字段来显式声明有意省略从而抑制missing-sections等 lint 警告omitted: - spacing - section: rounded reason: No rounded corners defined in brand book样例本身并未声明omitted因此 linter 的missing-sections规则info级会提示 No rounded section defined. Corner rounding will fall back to agent defaults.——因为正文 Shapes 一节声明圆角严格为 0pxSharp你完全可以通过omittedreason把这个有意为之的决策记录下来既消除了噪音警告又向 Agent 传达了设计意图。四、Markdown 正文逐节拆解人类可读的设计意图层规范docs/spec.md 第 100-113 行规定所有章节使用##标题且出现的章节必须按固定顺序排列Overview别名 Brand StyleColorsTypographyLayout别名 Layout SpacingElevation Depth别名 ElevationShapesComponentsDos and Donts这份样例的顺序Brand Style → Colors → Typography → Layout Spacing → Elevation Depth → Shapes → Components完全合规只是省略了可选的 Dos and Donts。4.1 Brand StyleOverviewThe design system is rooted in the Minimalist Neo-Esoteric aesthetic—a fusion of ancient monumentalism and modern editorial precision...The style isTactile and Minimalist, rejecting standard web conventions (like heavy gradients or standard blue links)...规范第 117-121 行指出本节是产品观感的全景描述定义品牌个性、目标受众与期望唤起的情感反应。当具体规则或令牌未明确定义时它是指导 Agent 高层级风格决策的基础上下文。本例交代了受众intellectual and discerning追求 high-signal discourse 的高知读者、情感目标reverence、focused intensity、analog tactile satisfaction以及明确的反模式拒绝 heavy gradients 和 standard blue links——这些都是高价值约束。4.2 ColorsThe palette is anchored by theWarm Alabasterbase...Rich Charcoalprovides the weight...Matte Brassis reserved for the highest tier of editorial importance...Deep Crimsonis used exclusively as a structural bloodline...规范第 123-161 行要求 Colors 正文从关键调色板推导出颜色令牌且允许在散文中使用描述性颜色名如 Warm Alabaster来对应系统性令牌名如surface——The tokens are the normative values; the prose provides contextdocs/spec.md 第 8 行。本例正是这样做的散文里的 Warm Alabaster 对应surface: #fbf9f4Rich Charcoal 对应primary/on-surface: #1b1c19Matte Brass 对应secondary: #745b1dDeep Crimson 对应tertiary-container的深红家族如#410004。散文还给出使用边界Avoid vibrant colors; the palette must remain muted, antique, and serious——这类约束对 Agent 的实际产出影响极大。4.3 TypographyNewsreader(serving the Serif requirement) is used for headlines and blockquotes...Interhandles all functional data and body text...Metadata and labels must utilizeheavy tracking(letter-spacing) and uppercase styling...正文明确了两套字体的分工衬线体负责权威、文学感无衬线体负责功能数据并强制了 metadata 的宽字距对应令牌metadata-caps的letterSpacing: 0.15em 大写化规则以及正文的宽松行高body-main的lineHeight: 1.6。这些描述与前端数据的字距/行高数值精确对应Agent 可以散文给规则、令牌给数值地执行。4.4 Layout SpacingThe layout follows aFixed Gridphilosophy, centered on the screen like an open book. It uses a rigorous 12-column grid with wide gutters...Whitespace is not empty but is treated as physical margin. Elements are spaced with a mathematical rhythm based on a 4px baseline...规范第 216-252 行说明 Layout 描述网格/布局/间距策略spacing 令牌服务于该模型如列跨度、gutter、margin。本例把4px 基线数学节奏落到spacing.unit: 4px、宽 gutter落到gutter: 32px、大尺度纵向间隔落到block-gap: 48px/margin-page: 64px。注意它没有显式写container-max——规范示例DESIGN-test.md 中的 Pacific Mint Dental 样例展示了container-max: 1200px这类键的用法你可以按需扩展。4.5 Elevation DepthDepth...achieved throughPhysical Offsetsrather than ambient blurs. 1.The Etch:...1px or 2px solid offset inDeep Crimson (#9F2B2A)... 2.The Inlay:...shift 1px down and to the right... 3.Tonal Stacking:...thin Charcoal borders (0.5pt to 1pt)...No soft shadows are permitted.规范第 254-267 行指出若使用层级elevation须定义所需样式spread、blur、color若是扁平设计则说明替代层级手段边框、颜色对比。本例属于典型的扁平设计 物理偏移方案明确禁止软阴影No soft shadows are permitted用 1-2px 实体色偏移Etch与 1px 位移Inlay模拟冲压/按键手感层级通过字阶与 Crimson 偏移传达——这是给 Agent 的可执行、可量化的层级规则比加一点阴影这类模糊指令有效得多。4.6 ShapesThe shape language is strictlySharp (0px)...All buttons, cards, and input fields must feature perfectly square corners. Decorative elements like dividers should be 1px solid lines, occasionally interrupted by a small diamond or square glyph...规范第 269-297 行说明 Shapes 描述元素造型rounded令牌组为其提供数值mapstring, Dimension如sm: 4px、full: 9999px。本例选择绝对 0px 圆角因此不需要 rounded 令牌组——0 即缺省。它在正文里同时约束了 divider 等装饰元素的形态1px 实线 菱形/方形 glyph 标记中点把品牌气质落到具体规则。4.7 ComponentsButtons:Rectangular with a 1px Charcoal border. On hover, the background fills with Matte Brass and the text remains Charcoal. Use the Etch depth...Cards (Feed Items):...Chips/Tags:...Lists:...Input Fields:...The Artifact (Special Component):...规范第 299-341 行将 Components 定义为组件原子button、chip、list、tooltip、checkbox、radio、input 等的风格指南并鼓励自定义领域组件。本例定义了 6 种组件含自定义的 The Artifact 双线框特殊组件每一种都给出了具体的交互状态与视觉规则hover 填充 Brass、输入框光标为 Charcoal 实心块等。需要特别说明的是本样例的 Components 全部以散文描述没有使用components:令牌组。而规范支持把组件参数化为机器可读令牌components: button-primary: backgroundColor: {colors.primary} textColor: {colors.on-primary} rounded: {rounded.md} padding: 12px button-primary-hover: backgroundColor: {colors.secondary}示例来自 docs/spec.md 第 319-328 行。如果给这份样例补充components:令牌就能让 linter 的contrast-ratio规则对backgroundColor/textColor组合做 WCAG 对比度校验——这是散文无法提供的机器级保障。两种写法并不互斥散文定义为何令牌定义是多少。五、把样例交给 linter11 条规则逐一对照仓库的 linter 按固定顺序执行 11 条规则见 packages/cli/src/linter/linter/rules/index.ts 第 31-43 行的DEFAULT_RULE_DESCRIPTORS。我们用这份样例逐一推演其结果规则严重级对 NEO_ESOTERIC_MONUMENT.md 的预期broken-referror通过——无components:令牌不存在悬空引用missing-primarywarning通过——colors.primary已定义见 missing-primary.tscontrast-ratiowarning通过——无组件令牌对可校验若补充组件令牌则启用见 contrast-ratio.ts阈值 4.5:1orphaned-tokenswarning可能提示——颜色令牌定义很多但无组件引用token-summaryinfo输出各令牌组数量统计missing-sectionsinfo提示rounded未定义圆角将回退到 Agent 默认值见 missing-sections.tsmissing-typographywarning通过——typography 令牌齐全section-orderwarning通过——章节顺序完全符合规范见 section-order.tsunknown-keywarning通过——所有顶层键均为 schema 已知键token-like-ignoredwarning通过——无被忽略的疑似令牌顶层键omitted-rulesinfo通过——未声明omitted从源码结构看missing-sections只检查spacing与rounded两组missing-sections.ts 第 24-27 行当对应 map 为空且已有颜色令牌时发出 info 提示section-order通过CANONICAL_ORDER与SECTION_ALIASES解析别名后检查相对顺序section-order.ts 第 28-59 行contrast-ratio遍历每个组件的backgroundColor/textColor解析结果计算对比度contrast-ratio.ts 第 25-45 行。这些规则在 runner.ts 的runLinter()中被扁平化聚合最终统计出errors/warnings/infos三个计数。六、底层实现从 Markdown 到可校验的状态机要理解这份样例为何规范需要了解它被解析后的内部表示。linter 的模型层packages/cli/src/linter/model/spec.ts定义DesignSystemStateexport interface DesignSystemState { name?: string; description?: string; omitted?: OmittedSection[]; colors: Mapstring, ResolvedColor; typography: Mapstring, ResolvedTypography; rounded: Mapstring, ResolvedDimension; spacing: Mapstring, ResolvedDimension; components: Mapstring, ComponentDef; symbolTable: Mapstring, ResolvedValue; // colors.primary → ResolvedColor sections?: string[]; // 文档中出现的 Markdown 标题 unknownKeys?: string[]; unknownKeyValues?: Recordstring, unknown; }几个与样例直接相关的实现细节颜色解析ResolvedColor除保留原始hex外还计算了 WCAG 相对亮度luminancemodel/spec.ts 第 35-45 行供contrast-ratio规则复用所有颜色格式都会先解析再统一转 sRGB。符号表symbolTable提供扁平的colors.primary → ResolvedValue查找是{path.to.token}引用解析与broken-ref检测的基础。宽容解析unknownKeys记录非 schema 顶层键但不会直接报错——这与规范Consumer Behavior表格未知章节保留、未知颜色名若值合法则接受、未知组件属性带警告接受、重复章节报错的行为一致样例中的 M3 扩展颜色名正是被这套机制接纳的。如果你用 CLI 校验这份样例命令如下详见 README.mdnpx google/design.md lint packages/cli/src/linter/fixtures/NEO_ESOTERIC_MONUMENT.md所有命令都接受文件路径或-stdin输出默认为 JSONlint在发现 error 时退出码为 1。七、从样例到实战把这份模式迁移到自己的项目Neo-Esoteric Monument 的价值在于它演示了一条可复制的设计系统文档化路径先写 Brand Style一句话锚定审美与受众给出明确的反模式清单如禁渐变、禁蓝色链接、禁软阴影——这是 Agent 的最高层约束。用散文定义语义色Warm Alabaster / Rich Charcoal / Matte Brass / Deep Crimson再用令牌给出确切值并确保至少包含primary。定义排版层级fontFamilyfontSize是底线强烈建议补全fontWeight、lineHeight无单位倍数、letterSpacing让 Agent 无需猜测。把间距节奏数值化unit基线 命名间距gutter、margin、gap让4px/8px 节奏变成可执行数据。显式处理省略若某些组如rounded有意不定义用omittedreason声明消除 lint 噪音并防止 Agent 自行发挥。把关键组件参数化为components:令牌启用contrast-ratio的 WCAG AA4.5:1自动校验——这是散文无法提供的机器保障。接入手工流程lint校验结构、diff跟踪版本回归、export输出 Tailwind/DTCG 供前端消费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命令表见 README.md 的 CLI Reference 与 Design Token Interoperability 章节。仓库的examples/目录如 atmospheric-glass、paws-and-paths、totality-festival还提供了从 DESIGN.md 到design_tokens.json、tailwind.config.js的落地样例可以作为端到端参考。八、总结NEO_ESOTERIC_MONUMENT.md 是一份结构工整、风格自洽的 DESIGN.md 范本前端数据用 Material 3 风格的完整调色板、双字体排版层级与 4px 间距节奏承载确切的数值正文用七个规范章节承载为什么这样设计两者互相印证、缺一不可。对照 docs/spec.md 的 schema 与 linter 源码rules/index.ts、runner.ts、model/spec.ts可以看到格式的每一处宽容未知颜色名、可省略章节、omitted声明都有明确的消费端行为与之对应。把它作为起点你完全可以用同样的模式为自己的产品撰写一份让编码 Agent 稳定、持久地理解设计系统的 DESIGN.md——再辅以lint/diff/export工作流让设计规范真正成为可验证、可演进、跨会话一致的活文档。【免费下载链接】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），仅供参考