DESIGN.md 实战指南：用 YAML 设计令牌 + Markdown 设计理由，为 Coding Agent 建立可持久化的设计系统规范

DESIGN.md 实战指南用 YAML 设计令牌 Markdown 设计理由为 Coding 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.mdDESIGN.md 是一种面向编码 Agentcoding agent的视觉身份描述格式它用 YAML front matter 承载机器可读的设计令牌design tokens用 Markdown 正文承载人可读的设计理由让 Agent 在设计会话之间持续获得对设计系统稳定、结构化的理解。本文以仓库根目录 README.md 为主线结合完整规范文档 docs/spec.md、CLI 源码与三套真实示例examples/atmospheric-glass/DESIGN.md 等展开读完你将掌握如何编写一份合规的 DESIGN.md、如何用lint/diff/export/spec四个子命令校验与消费它以及如何将它导出为 Tailwind v3/v4 与 W3C DTCG 令牌格式。格式总览两层结构一个文件一份 DESIGN.md 文件由两层组成YAML front matter——机器可读的设计令牌位于文件顶部用恰好包含---的行作为开始与结束定界符。令牌是**规范性normative**的值是 Agent 需要精确取用的硬数据。Markdown 正文——人可读的设计理由按##章节组织。正文提供上下文context说明这些值为什么存在、应该如何应用正文还可以使用与令牌名对应的描述性颜色名如 Midnight Forest Green ↔ 令牌primary。令牌是规范值正文是应用语境。文档正文的第一行写明了这一核心定位A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.一个最小但完整的例子取自 README 的 The Format 一节--- name: Heritage colors: primary: #1A1C1E secondary: #6C7278 tertiary: #B8422E neutral: #F7F5F2 typography: h1: fontFamily: Public Sans fontSize: 3rem body-md: fontFamily: Public Sans fontSize: 1rem label-caps: fontFamily: Space Grotesk fontSize: 0.75rem rounded: sm: 4px md: 8px spacing: sm: 8px md: 16px --- ## Overview Architectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish — a high-end broadsheet or contemporary gallery. ## Colors The palette is rooted in high-contrast neutrals and a single accent color. - **Primary (#1A1C1E):** Deep ink for headlines and core text. - **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata. - **Tertiary (#B8422E):** Boston Clay — the sole driver for interaction. - **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.读取该文件的 Agent 会据此生成这样的界面Public Sans 深墨色标题、暖石灰岩背景、Boston Clay 主色按钮——这正是令牌给精确值正文给应用理由协同工作的效果。在仓库中可以看到同一模式被规模化应用atmospheric-glass示例的 DESIGN.md 定义了 40 颜色令牌、6 级排版、6 级圆角与 10 个组件含 hover 变体其正文则用 Glassmorphismvibrant-minimalist 等语言描述品牌人格与情绪目标。另外两个示例paws-and-paths/DESIGN.md、totality-festival/DESIGN.md展示了同一规范在不同设计语言下的落地。令牌模式Token Schemafront matter 遵循如下 YAML 模式完整定义见 docs/spec.md 与 spec-config.yamlversion: string # 可选当前版本: alpha name: string description: string # 可选 omitted: string[] | OmittedSection[] # 可选声明有意省略的章节 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关键点scale-level是尺寸/间距刻度上某个具名层级常用xs、sm、md、lg、xl、full任何描述性字符串键都合法。version当前为alpha见 spec-config.ts 中SPEC_VERSION常量格式仍在积极演进升级可能带来破坏性变更。omitted允许显式声明本设计系统有意不定义某章节从而抑制 linter 对缺失章节的告警。条目可以是纯字符串也可以是带理由的对象omitted: - spacing - section: rounded reason: No rounded corners defined in brand book从源码看规范配置由 spec-config.ts 通过 zod 校验后懒加载为单例且设置了两个安全限制max_token_nesting_depth: 20令牌最大嵌套深度与max_reference_depth: 10引用最大解析深度防止解析器被病态输入拖垮。令牌类型Token Types类型格式示例Color任意合法 CSS 颜色hex、rgb()、oklch()、具名颜色等#1A1C1E、oklch(62% 0.18 250)Dimension数字 单位px、em、rem48px、-0.02emToken Reference{path.to.token}{colors.primary}Typography含fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation的对象见上文示例规范对颜色做了更细的说明docs/spec.md支持#RGB/#RGBA/#RRGGBB/#RRGGBBAA、具名颜色red、transparent等、函数式rgb()/rgba()/hsl()/hsla()/hwb()、广色域oklch()/oklab()/lch()/lab()以及color-mix(in srgb, ...)。所有颜色在内部都会被转换为 sRGB 用于 WCAG 对比度检查但原始格式在显示与导出时保持不变#RRGGBB是推荐的默认写法。排版子属性方面fontWeight允许裸数字或引号字符串lineHeight接受带单位维度或无单位倍数如1.6即推荐 CSS 实践中的 fontSize 倍数fontFeature/fontVariation分别配置font-feature-settings与font-variation-settings。关于 Token Reference 有一条容易被忽略的规则对大多数令牌组引用必须指向原始值如{colors.primary-60}不能指向组如{colors}但在components中允许引用复合值如{typography.label-md}。章节顺序Section Order正文章节使用##标题。章节可以省略但出现的章节必须按以下规范顺序排列存在时顶部可选的h1仅用于文档标题不会被解析为章节。#章节别名1OverviewBrand Style2Colors3Typography4LayoutLayout Spacing5Elevation DepthElevation6Shapes7Components8Dos and Donts在源码中别名到规范名的解析由 spec-config.ts 的SECTION_ALIASES与resolveAlias()实现是section-order规则的判定基础。各章节的职责与配套令牌详见 docs/spec.mdOverview / Brand Style整体观感的概括描述——品牌人格、目标受众、UI 应唤起的情感活泼或专业、紧凑或疏朗为没有明确规则/令牌的高层风格决策提供基础语境。Colors定义调色板至少必须定义primary。多调色板时常见约定按primary、secondary、tertiary、neutral顺序命名并赋予语义角色。Typography定义排版层级多数设计系统有 9~15 级常见命名约定用语义类别headline、display、body、label、caption 尺寸small、medium、large。Layout / Layout Spacing布局与间距策略网格、安全区、动态 padding 等。spacing令牌是mapstring, Dimension | number单位数字可用于列数或比例这类语义。Elevation Depth / Elevation视觉层级的实现方式——阴影spread/blur/color或扁平设计下用边框、颜色对比等替代手段。Shapes元素形态语言配套rounded令牌是mapstring, Dimension。Components组件原子按钮、Chips、列表、Tooltip、复选框、单选框、输入框等的风格指南该章节规范仍在演进为领域自定义组件保留了刻意设计的灵活性。Dos and Donts实用准则与常见陷阱作为创作时的护栏。组件令牌与变体Component Tokenscomponents把组件名映射到一组子令牌属性components: button-primary: backgroundColor: {colors.tertiary} textColor: {colors.on-tertiary} rounded: {rounded.sm} padding: 12px button-primary-hover: backgroundColor: {colors.tertiary-container}合法组件属性VALID_COMPONENT_SUB_TOKENS定义于 spec-config.tsbackgroundColorColortextColorColortypographyTypographyroundedDimensionpaddingDimensionsizeDimensionheightDimensionwidthDimension属性值可以是字面量也可以是对已定义令牌的引用。变体hover、active、pressed 等通过相关键名表达为独立的组件条目例如button-primary/button-primary-hover/button-primary-active——Agent 会综合所有变体做出恰当的样式决策。atmospheric-glass示例中的glass-card-standard引用{rounded.lg}与{spacing.glass-padding}与button-primary-hover引用{colors.primary-fixed-dim}是变体与引用语法的真实用法。未知内容的消费行为Consumer Behavior规范明确了消费端遇到未定义内容时的行为这决定了格式的向前兼容性场景行为未知章节标题保留不报错如## Iconography未知颜色令牌名值合法则接受如surface-container-high: #ede7dd未知排版令牌名作为合法排版接受未知间距值接受若非合法维度则存为字符串未知组件属性接受但告警如borderColor重复章节标题报错拒绝该文件CLI 快速上手lint / diff / export / specCLI 包名为google/design.md版本 0.3.0要求 Node 18同时暴露design.md与designmd两个 bin见 packages/cli/package.json。所有命令都接受文件路径或-stdin输出默认为 JSON。安装npm install google/design.mdWindows 提示若 shell 对有特殊处理PowerShell 等请给包名加引号npm install google/design.md也可以直接运行始终从公共 npm registry 解析npx google/design.md lint DESIGN.md在Windows/PowerShell上上述直接形式可能无输出甚至因design.mdbin 名中的.md后缀与 Windows Markdown 文件关联冲突而在命令解析时打开DESIGN.md。请改用无点的designmd别名——用-p让 npx 指向包再调用designmdnpx -p google/design.md designmd lint DESIGN.mddesignmdshim 指向同一入口在所有平台上行为一致。同理在package.json脚本中直接调用时也应使用designmd// package.json { scripts: { design:lint: designmd lint DESIGN.md } }npm error ENOVERSIONSNo versions available for google/design.md排障该 CLI 发布在 npm 上ENOVERSIONS几乎总是意味着 npm 没有查询公共 registry——常见原因有.npmrc自定义了registry、企业镜像未同步该包、或googlescope 配置了错误的google:registry。先检查生效的 registrynpm config get registry正常联网安装时应为https://registry.npmjs.org/。修复配置后若旧 404 被缓存可重试npm cache clean --force。lint结构校验校验 DESIGN.md 的结构正确性包括破坏的令牌引用、WCAG 对比度、结构性问题等输出结构化 JSON 供 Agent 直接行动npx google/design.md lint DESIGN.md npx google/design.md lint --format json DESIGN.md cat DESIGN.md | npx google/design.md lint -OptionTypeDefaultDescriptionfilepositionalrequiredDESIGN.md 路径或-表示 stdin--formatjsonjson输出格式发现错误时退出码为1否则为0。从 lint.ts 源码可见--format参数虽描述为json or text但默认并输出 JSON文件读取失败FileReadError时退出码为2。典型输出{ findings: [ { severity: warning, path: components.button-primary, message: textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA. } ], summary: { errors: 0, warnings: 1, infos: 1 } }diff设计系统回归检测对比两个版本的设计系统报告令牌级与文本级回归npx google/design.md diff DESIGN.md DESIGN-v2.mdOptionTypeDefaultDescriptionbeforepositionalrequired之前 的 DESIGN.mdafterpositionalrequired之后 的 DESIGN.md--formatjsonjson输出格式若检测到回归之后 文件的错误或告警数更多退出码为1。从 diff.ts 源码可见它分别对两份文件执行lint()用diffMaps按 colors/typography/rounded/spacing/components 五个维度对比令牌差异并给出before/after/delta三个视角的 findings 汇总与布尔型regression{ tokens: { colors: { added: [accent], removed: [], modified: [tertiary] }, typography: { added: [], removed: [], modified: [] }, rounded: { added: [], removed: [], modified: [] }, spacing: { added: [], removed: [], modified: [] }, components: { added: [], removed: [], modified: [] } }, findings: { before: { errors: 0, warnings: 1, infos: 1 }, after: { errors: 0, warnings: 1, infos: 1 }, delta: { errors: 0, warnings: 0 } }, regression: false }export导出到其他令牌格式将 DESIGN.md 令牌导出为 Tailwind 与 W3C 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.jsonOptionTypeDefaultDescriptionfilepositionalrequiredDESIGN.md 路径或-表示 stdin--formatjson-tailwind|css-tailwind|tailwind|dtcgrequired输出格式FormatOutputDescriptionjson-tailwindJSONTailwind v3theme.extend配置对象css-tailwindCSSTailwind v4theme { ... }块CSS 自定义属性tailwindJSONjson-tailwind的别名dtcgJSONW3C Design Tokens Format Module导出成功时退出码为0——无论源文件是否有 lint findings那是lint的职责--format无效或 emitter 出错时退出码为1输入文件无法读取时为2。从 export.ts 源码可见底层分别由TailwindEmitterHandlerv3 JSON、TailwindV4EmitterHandlerserializeTailwindV4v4 CSS、DtcgEmitterHandler与CssVarsEmitterHandler实现。仓库示例 examples/atmospheric-glass/tailwind.config.js 展示了从同一份 DESIGN.md 生成的 v3theme.extend产物形态所有颜色令牌落入theme.extend.colors、排版落入fontFamily/fontSize、圆角落入borderRadius、间距落入spacing。spec把规范注入 Agent Prompt输出 DESIGN.md 格式规范全文适合将规范上下文注入 Agent 提示词npx google/design.md spec npx google/design.md spec --rules npx google/design.md spec --rules-only --format jsonOptionTypeDefaultDescription--rulesbooleanfalse追加当前启用的 lint 规则表--rules-onlybooleanfalse只输出 lint 规则表--formatmarkdown|jsonmarkdown输出格式十一项 Linting 规则linter 对解析后的 DESIGN.md 运行十一项规则规则清单见 rules/index.ts 的DEFAULT_RULE_DESCRIPTORS按序执行每条规则产生固定严重级别的 findingsRuleSeverity检查内容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 键疑似已知 schema 键的拼写错误如colours:→colors:自定义扩展键保持静默token-like-ignoredwarning未知顶层键的值形似令牌hex 颜色、字体族、维度暗示它可能被丢弃或拼错omitted-rulesinfo校验omitted配置映射中未知或冗余的章节程序化 APIProgrammatic APIlinter 也以库的形式提供入口见 linter/index.ts 的lint导出import { lint } from google/design.md/linter; const report lint(markdownString); console.log(report.findings); // Finding[] console.log(report.summary); // { errors, warnings, info } console.log(report.designSystem); // Parsed DesignSystemState除此之外库还导出了可直接组合的独立规则brokenRef、missingPrimary、contrastCheck、orphanedTokens、tokenSummary、missingSections、missingTypography、unknownKey、tokenLikeIgnored、omitted、runLinter/preEvaluate高级 linting 入口、contrastRatio对比度计算函数、各 Emitter Handler以及fixSectionOrder自动修复章节顺序的 fixer。设计令牌互操作Tailwind 与 DTCGDESIGN.md 的令牌系统受 W3C Design Token Format 启发——尤其采纳了带类型的令牌组colors、typography、spacing与{path.to.token}引用语法。这些令牌可以轻松地在tokens.json、Figma variables 与 Tailwind theme config 之间互相转换docs/spec.md。export命令支持三种互操作目标Tailwind v3 配置JSON——--format json-tailwind输出可直接并入tailwind.config.js的theme.extend对象--format tailwind是向后兼容别名。Tailwind v4 主题CSS——--format css-tailwind输出 Tailwind v4 的theme { ... }块使用其 CSS 变量令牌命名空间--color-*、--font-*、--text-*、--leading-*、--tracking-*、--font-weight-*、--radius-*、--spacing-*。DTCG tokens.jsonW3C Design Tokens Format Module——--format dtcg输出符合 W3C 规范定义的 tokens.json。编写建议与当前状态规范还提供了一组非规范性non-normative的推荐令牌名不强制但鼓励一致使用详见 docs/spec.mdColorsprimary、secondary、tertiary、neutral、surface、on-surface、errorTypographyheadline-display、headline-lg、headline-md、body-lg、body-md、body-sm、label-lg、label-md、label-smRoundednone、sm、md、lg、xl、full推荐的组件原子包括按钮主/次/三级变体、尺寸、padding、状态、Chips选择/过滤/操作、列表、Tooltip、复选框含 indeterminate、单选框、输入框含错误态等。写作时的通用建议Colors 章节至少定义primary用语义化命名组织 9~15 级排版Dos and Donts 里给出可执行护栏如 Do maintain WCAG AA contrast ratios (4.5:1 for normal text)。StatusDESIGN.md 格式当前处于alpha版本version: alpha。规范、令牌模式与 CLI 均在活跃开发中格式成熟过程中可能发生变化。使用前建议查看 docs/spec.md 与 spec-config.yaml 以确认当前版本定义并在 CI 中通过lint与diff守护设计系统的质量与一致性。【免费下载链接】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），仅供参考