DESIGN.md 颜色令牌怎么定 primary、secondary、tertiary、neutralpalette 命名约定与 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段下它是一个mapstring, 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” 一节给出两条规则颜色令牌应从正文## Colors中定义的关键色板派生出来色板到令牌的具体映射“可以遵循任何一致的命名约定”。也就是说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.mddesignmdshim 解析到同一入口各平台行为一致。missing-primary 警告解析missing-primary是 lint 11 条规则之一severity 固定为warning。规则实现见 packages/cli/src/linter/linter/rules/missing-primary.ts触发条件是精确的两点合取colors段定义了至少一个颜色令牌colors.size 0其中不存在名为primary的键精确匹配键名primarymain、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.tscolors为空时不报此警告只要primary键存在哪怕只有一个令牌也不报。用下面的最小文件可以复现这个警告accent与#ff0000取自规则单测的测试数据--- name: Demo colors: accent: #ff0000 ---对它运行npx google/design.md lint DESIGN.mdfindings中会出现上面那条 warning。修复方式给primary一个显式值即可例如把accent改名为primary或补一行primary: #1A1C1E。重新 lint 后验证两点findings中不再有No primary color defined这条 warningsummary.warnings相应减少若文件本来没有 error退出码保持0warning 本就不触发退出码 1。顺带的相关检查与限制颜色令牌定下来后同一份 lint 输出里还有两条与颜色直接相关的规则值得留意contrast-ratiowarning检查组件的backgroundColor/textColor配对是否低于 WCAG AA 最小值 4.5:1。所有颜色值内部会转成 sRGB 再参与对比度计算原始格式保留用于展示和导出。orphaned-tokenswarning定义了但没有任何组件引用的颜色令牌。如果你的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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考