企业官网建设流程全解析

DESIGN.md 颜色令牌怎么定 primary、secondary、tertiary、neutral？palette 命名约定与 missing-primary 警告解析

【免费下载链接】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 的 YAML front matter 中为设计系统定义颜色令牌——该用哪些名字、值怎么写、命名约定有什么规则，以及跑 lint 时出现的missing-primary警告到底在说什么。完成目标：你的 DESIGN.md 中颜色令牌命名符合 spec 约定，npx @google/design.md lint不再报missing-primary，且组件引用{colors.xxx}能正确解析。

适用前提：文件遵循 DESIGN.md 格式（YAML front matter + Markdown 正文，见 docs/spec.md），验证使用 npm 上的@google/design.mdCLI（需 Node.js 环境，npx可直接拉取，无需全局安装）。

在 front matter 中写四个颜色令牌

DESIGN.md 有两层：front matter 里的令牌是规范值（机器可读），正文是设计理由（给人读）。颜色令牌写在colors段下，它是一个map<string, Color>，键是令牌名，值可以是任意合法 CSS 颜色：hex（#RGB到#RRGGBBAA）、具名颜色（red）、rgb()/hsl()等函数式写法、宽色域（oklch()等）乃至color-mix()。spec 推荐默认用#RRGGBBhex，理由是简洁且工具兼容性好。

docs/spec.md 对颜色部分的规定是：

• 至少必须定义primary色板，其余色板按需添加；
• 多个色板时，常见约定是按primary、secondary、tertiary、neutral的顺序为它们命名，并给每个色板分配一个语义角色。

最小可 lint 的文件（取值来自 spec 官方示例）：

--- name: Heritage colors: primary: "#1A1C1E" secondary: "#6C7278" tertiary: "#B8422E" neutral: "#F7F5F2" --- ## Colors - **Primary (#1A1C1E):** 用于标题和核心文字的深墨色。 - **Secondary (#6C7278):** 用于边框、说明文字、元信息的灰色。 - **Tertiary (#B8422E):** 唯一的交互驱动色，仅用于主要操作和关键高亮。 - **Neutral (#F7F5F2):** 页面底色的暖石灰，比纯白更柔和。

## Colors正文的作用不是重复色值，而是说明每个色板的角色（什么场景用哪块颜色）。spec 明确指出：令牌是规范值，正文提供“如何应用”的上下文；正文里的描述性名字（如 "Midnight Forest Green"）对应系统化的令牌名（如primary）。

palette 命名约定：四个基础名之外还能叫什么

spec 在 “Colors / Design Tokens” 一节给出两条规则：

1. 颜色令牌应从正文## Colors中定义的关键色板派生出来；
2. 色板到令牌的具体映射“可以遵循任何一致的命名约定”。

也就是说，primary/secondary/tertiary/neutral是约定俗成的基础名，不是封闭集合。spec 另有一节 “Recommended Token Names (Non-Normative)”，列出非强制的推荐颜色名：primary、secondary、tertiary、neutral、surface、on-surface、error。遇到未知颜色令牌名时，消费者的行为是“值合法就接受”，不会报错。

仓库内的示例展示了扩展命名的实际写法。examples/paws-and-paths/DESIGN.md 和 examples/atmospheric-glass/DESIGN.md 都在四个基础名之外定义了on-primary、primary-container、secondary-fixed等成组令牌，并且组件里引用它们：

components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}"

两条使用限制需要注意：

• 令牌引用必须用{path.to.token}语法，且对大多数令牌组，引用必须指向基本值（如colors.primary-60），不能指向整个分组；组件段内允许引用复合值（如{typography.label-md}）。
• 引用了未定义的令牌会触发broken-ref规则，severity 是error——这是 lint 退出码为 1 的情形，务必和 warning 区分开。

用 lint 验证颜色令牌

对文件跑 lint（命令来自 README.md 的 CLI 参考）：

npx @google/design.md lint DESIGN.md

也可以从标准输入读：cat DESIGN.md | npx @google/design.md lint -。默认输出 JSON，结构是findings数组加summary计数：

{ "findings": [ { "severity": "warning", "path": "...", "message": "..." } ], "summary": { "errors": 0, "warnings": 1, "infos": 1 } }

（以上为 README 展示的输出结构示例。）退出码规则：有 error 时为 1，否则为 0——warning 不影响退出码。

Windows/PowerShell 下直接用npx @google/design.md可能无输出或误打开 Markdown 文件（bin 名的.md后缀与文件关联冲突），改用无点号别名：

npx -p @google/design.md designmd lint DESIGN.md

designmdshim 解析到同一入口，各平台行为一致。

missing-primary 警告解析

missing-primary是 lint 11 条规则之一，severity 固定为warning。规则实现见 packages/cli/src/linter/linter/rules/missing-primary.ts，触发条件是精确的两点合取：

1. colors段定义了至少一个颜色令牌（colors.size > 0）；
2. 其中不存在名为primary的键（精确匹配键名primary，main、brand等都不算）。

命中时产出的 finding 为：

{ "severity": "warning", "path": "colors", "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette." }

这段话的含义：没有primary令牌时，读取该文件的 agent 会自动生成关键颜色，你对色板的控制权随之下降。注意另外两个边界行为（来自规则的单测 missing-primary.test.ts）：colors为空时不报此警告；只要primary键存在（哪怕只有一个令牌）也不报。

用下面的最小文件可以复现这个警告（accent与#ff0000取自规则单测的测试数据）：

--- name: Demo colors: accent: "#ff0000" ---

对它运行npx @google/design.md lint DESIGN.md，findings中会出现上面那条 warning。

修复方式：给primary一个显式值即可，例如把accent改名为primary，或补一行primary: "#1A1C1E"。重新 lint 后验证两点：

• findings中不再有No 'primary' color defined这条 warning，summary.warnings相应减少；
• 若文件本来没有 error，退出码保持0（warning 本就不触发退出码 1）。

顺带的相关检查与限制

颜色令牌定下来后，同一份 lint 输出里还有两条与颜色直接相关的规则值得留意：

• contrast-ratio（warning）：检查组件的backgroundColor/textColor配对是否低于 WCAG AA 最小值 4.5:1。所有颜色值内部会转成 sRGB 再参与对比度计算，原始格式保留用于展示和导出。
• orphaned-tokens（warning）：定义了但没有任何组件引用的颜色令牌。如果你的secondary、neutral没有出现在components段的任何{colors.*}引用中，会收到这条提示，可作为检查令牌是否被真正使用的线索。

限制方面：spec 当前处于alpha版本，格式、令牌 schema 与 CLI 都在活跃开发中，字段可能有变化；colors段中除primary外的名字均非强制，但一旦用了扩展命名（如on-primary），要确保命名一致且被组件实际引用，避免留下 orphan 令牌。

完整规则表见 README.md 的 “Linting Rules” 一节，格式全文规范见 docs/spec.md。

【免费下载链接】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