DESIGN.md自定义lint规则实战覆盖默认11条规则的rules选项【免费下载链接】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 是面向编码智能体的设计系统描述格式规范其官方 CLI 内置了 11 条 lint 规则来校验设计令牌design tokens的结构正确性。本篇实战教程将手把手教你使用 linter 的rules 选项自定义 lint 规则——精简、扩展或替换默认的 11 条规则让校验完全贴合你的设计系统。1. 先认识 DESIGN.md 的 lint 能力google/design.md是一个轻量级 CLI 库核心命令lint会解析 DESIGN.mdYAML 令牌 Markdown 说明然后执行一组 lint 规则输出结构化的 JSON 报告npx google/design.md lint DESIGN.md报告包含两部分findings每条问题含severity、path、messagesummary按严重级别汇总的{ errors, warnings, infos }计数默认情况下linter 会依次执行11 条内置规则定义在 packages/cli/src/linter/linter/rules/index.ts 的DEFAULT_RULE_DESCRIPTORS中。完整规范见 docs/spec.md。 默认 11 条 lint 规则速览规则严重级别检查内容broken-referror令牌引用{colors.primary}无法解析missing-primarywarning定义了颜色但没有primarycontrast-ratiowarning组件背景/文字色对比度低于 WCAG AA (4.5:1)orphaned-tokenswarning颜色令牌从未被任何组件引用token-summaryinfo各分区令牌数量摘要missing-sectionsinfo其他令牌存在时缺少 spacing/rounded 等分区missing-typographywarning定义了颜色但没有字体令牌section-orderwarning分区顺序不符合规范unknown-keywarning顶层 YAML 键疑似拼写错误如colours:→colors:token-like-ignoredwarning未知键的值像令牌hex 色值、字号等疑似被漏写omitted-rulesinfo校验omitted配置是否映射了未知或冗余分区关键点命令行lint固定执行全部 11 条规则而rules 选项是编程式 API 的能力它才是覆盖默认规则的入口。2. rules 选项如何覆盖默认规则在 packages/cli/src/linter/lint.ts 中lint()函数接受一个可选的LintOptionsinterface LintOptions { /** 自定义 lint 规则省略时默认使用 DEFAULT_RULES */ rules?: LintRule[]; }执行流程在 packages/cli/src/linter/linter/runner.ts你传入rules后只有你列出的规则会被执行其余默认规则全部跳过。它同时支持两种规则形式形式结构适用场景LintRule函数(state) Finding[]快速自定义最简写法RuleDescriptor描述符{ name, severity, description, run }复用内置规则、统一注入严重级别规则类型定义在 packages/cli/src/linter/linter/rules/types.ts每条规则接收解析好的设计系统状态DesignSystemState含colors、components等返回发现问题列表——纯函数、无副作用非常好调试。3. 实战一按需精简只保留关键规则最常见的需求是11 条规则太吵了。所有内置规则都从 linter 入口导出你只需挑选需要的子集import { lint, brokenRef, contrastCheck } from google/design.md/linter; // 只跑 2 条最关键的规则其余 9 条默认规则全部不执行 const report lint(markdown, { rules: [brokenRef, contrastCheck] });想要全部默认规则直接不传rules或显式传DEFAULT_RULES想要子集如上按需组合想要全新规则集见下一节4. 实战二编写一条自定义 lint 规则一条规则本质上就是读状态 → 返回 findings。以每个颜色必须提供配套的on-文字色为例灵感来自内置规则 missing-primary.ts 的写法import { lint, brokenRef } from google/design.md/linter; // 自定义规则颜色缺少 on- 配套文字色时告警 const requireOnColor (state) [...state.colors.keys()] .filter((name) !name.startsWith(on-) !state.colors.has(on-${name})) .map((name) ({ severity: warning, path: colors.${name}, message: 颜色 ${name} 缺少配套文字色 on-${name}, })); const report lint(markdown, { rules: [brokenRef, requireOnColor] });报告里就会多出你的自定义 finding例如{ severity: warning, path: colors.primary, message: 颜色 primary 缺少配套文字色 on-primary }⚙️ 进阶如果你想让规则自带固定严重级别每条 finding 就不用手写severity了改用RuleDescriptor形式const onColorRule { name: require-on-color, severity: warning, description: 颜色缺少配套 on- 文字色, run: (state) { /* 同上逻辑返回 { path, message } 即可 */ }, };runner 会自动把描述符的severity注入到每条 finding单条 finding 也可用severity字段局部覆盖见 types.ts。5. 实战三调整默认规则的严重级别默认规则的级别是写死的如missing-primary恒为 warning。想把它升级为 error让 CI 直接失败包一层即可import { lint, missingPrimary } from google/design.md/linter; const missingPrimaryAsError (state) missingPrimary(state).map((f) ({ ...f, severity: error })); lint(markdown, { rules: [missingPrimaryAsError, /* 其余规则... */] });6. 快速上手清单三步接入自定义 rules安装npm install google/design.mdWindows 请给包名加引号选规则从 linter 入口导入需要的规则或用(state) Finding[]写自己的传选项lint(markdown, { rules: [...] })用report.summary判断门禁✅最佳实践把阻断发布的规则如broken-ref保持 error 级别把风格类规则放在 warning/info避免新人被 11 条默认规则吓退。7. 常见问题 FAQQCLI 里能直接用--rules吗A不能。命令行lint固定跑全部默认规则rules选项通过编程式 APIgoogle/design.md/linter提供适合接入 CI 或自定义工具链。Q传空数组rules: []会怎样A不执行任何规则只返回模型解析结果和 0 条 finding。Q模型解析错误如 YAML 格式错误会被 rules 影响吗A不会。解析/模型层的问题在规则执行前就已报告rules只控制规则层的校验。 总结rules选项是 DESIGN.md linter 的开关面板——子集即精简、自定义即扩展、包装即调级。配合 docs/spec.md 的完整规范和 packages/cli/src/linter/ 下的规则源码你可以把 lint 打造成完全符合团队设计标准的质检线。【免费下载链接】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），仅供参考