Kumo 自定义 Lint 规则揭秘：设计系统如何用 5 条规则从源头锁住团队代码一致性

Kumo 自定义 Lint 规则揭秘设计系统如何用 5 条规则从源头锁住团队代码一致性【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumoKumo 是 Cloudflare 开源的 React 组件库设计系统。它的做法不是靠 Code Review 口头约定而是用5 条自定义 Lint 规则从源头强制颜色令牌、暗色模式、组件规范、包边界与组件契约——所有设计系统违规都在你写代码的那一刻被机器拦截。这篇文章带你拆解这 5 条 Kumo 自定义 Lint 规则各自解决什么问题以及如何借鉴到你的团队。为什么设计系统需要自定义 Lint 规则组件库中视觉一致是硬要求。但人工审查很难兜住这些情况有人图省事直接写原生颜色类绕过设计令牌有人手动用dark:前缀切换暗色模式导致暗色表现不一致新组件不遵循团队约定的变体variant命名与导出结构Monorepo 里用../../相对路径偷渡到兄弟包内部实现已废弃的 prop 被新代码重新使用。通用解法就是自定义 Lint 规则把规则写成插件挂到 Lint 检查器上Kumo 用的是基于 Rust、速度更快的 Oxlint让机器在每次检查时自动报告违规。入口文件 lint/kumo-plugin.js 一次性注册了 5 条规则规则名拦截什么no-primitive-colorsTailwind 原生色如bg-blue-500no-tailwind-dark-variant手动用dark:类切换颜色enforce-variant-standard组件变体导出不符合命名规范no-cross-package-imports相对路径跨包导入no-flow-node-custom-renderFlow 自定义节点未透传 props 和 ref规则一no-primitive-colors——封杀裸颜色强制设计令牌这是逻辑最重的一条位于 lint/no-primitive-colors.js。问题如果每个组件都写bg-blue-500、border-red-500主题一换品牌色就全乱了。做法规则启动时直接读取两份主题 CSS 文件theme-kumo.css与theme-fedramp.css位于 packages/kumo/src/styles/解析出所有--color-*与--text-color-*自定义属性构成合法令牌白名单——白名单与主题文件天然保持同步改主题不用改规则遍历 JSX 中所有类名字符串模板串、字符串拼接、三元表达式都能被递归提取出来一旦发现bg-、text-、border-、ring-等颜色前缀命中 Tailwind 原生色系red、blue、slate 等 21 个色族→ 报no-primitive-colors提示改用 Kumo 语义令牌命中未知令牌比如语义色拼错→ 报invalid-color-token错误信息里直接点出具体是哪个令牌没定义在主题文件里。亮点bg-white、text-black被刻意放行它们是通用色text-sm、bg-clip-padding这类长得像颜色但其实不是颜色的工具类通过一张非颜色工具表加正则模式精准排除避免误报。这种白名单驱动的写法是设计令牌强制落地的好范本。规则二no-tailwind-dark-variant——封杀dark:暗色模式统一收口位于 lint/no-tailwind-dark-variant.js。规则一句话任何className里的dark:bg-...、dark:text-...都不允许。问题设计系统的暗色模式应该由主题令牌统一处理换主题即自动换色而不是每个页面自己写dark:变体否则会出现双重暗色或暗色表现不一致。实现细节正则要求dark:后面必须跟着合法的工具名如dark:bg-blue-500这样就不会误报{ dark: vesper }这种普通对象键extractStrings函数能递归收集字面量、模板字符串、字符串拼接、数组、对象、函数参数、三元表达式、甚至 JSX 文本中的类名片段——想用动态字符串绕过都行不通JSX 的className/class属性被专门监听其余代码位置同样扫描。报错信息直接给出改法请使用设计系统令牌或组件 API 处理暗色模式。规则三enforce-variant-standard——变体导出必须符合命名契约位于 lint/enforce-variant-standard.js。背景Kumo 的组件采用机器可读的变体体系——每个组件必须导出KUMO_{组件名}_VARIANTS变体定义与KUMO_{组件名}_DEFAULT_VARIANTS默认值文档站、AI 组件注册表、代码生成都依赖这份结构。规则做什么只对src/components/{name}/{name}.tsx这类组件文件生效组件名直接由文件路径解析连字符自动转下划线逐个检查导出名是否与KUMO_{COMPONENT}_VARIANTS、KUMO_{COMPONENT}_DEFAULT_VARIANTS、可选的KUMO_{COMPONENT}_BASE_STYLES完全一致命名写错时报错会同时给出你写的名字和应该写的名字文件末尾若缺少必需导出还会列出你实际导出了哪些变体相关符号。这类把命名约定当契约的规则把团队文档里的承诺变成了机器硬校验。规则四no-cross-package-imports——封杀相对路径爬出包位于 lint/no-cross-package-imports.js。问题Monorepo 里写import x from ../../kumo/src/button很方便但它绕过了包的公开 API目录一重构就全线报错。判定逻辑正则匹配若干层../ 已知包目录名kumo / kumo-docs-astro / kumo-figma要求至少向上两级../../只向上一级../kumo/大概率是同包内恰好同名的本地目录不报——这个细节巧妙避免了误报静态import、动态import()、require()、export from、export * from五种入口全覆盖。错误信息直接给出替代方案改用包名如cloudflare/kumo导入。规则五no-flow-node-custom-render——用静态分析检查组件契约位于 lint/no-flow-node-custom-render.js是最硬核的一条。问题Flow 组件的Flow.Node render{...}里放入自定义节点组件时该组件必须把收到的props展开透传、把ref转发给根元素否则节点无法聚焦、拖拽和测量整个流程图行为会异常。靠人肉检查几乎不可能覆盖所有组合。规则做法一次小型静态数据流分析收集文件里的组件候选命名函数组件、const X (props) ...、forwardRef包裹的函数支持重命名导入逐个分析组件渲染体是否出现了 props 展开、是否把 ref 绑定到了元素上找出所有出现在Flow.Node的render属性里的自定义组件文件结束时对照结论缺 ref 报missingRef缺 props 报missingProps都缺则合并报告。为应对真实代码规则还处理了 TypeScript 断言as、satisfies、!解包、forwardRef重命名导入、A.B形式的 JSX 成员表达式、ref与属性访问的区分等边界情况——这是一条真正理解 React的 Lint 规则。彩蛋第 6 条只存在于包内的规则packages/kumo/lint/no-deprecated-props.js 从自动生成的 AI 组件注册表ai/component-registry.json里读取废弃信息谁用了废弃 prop例如Select的hideLabel、Banner的text就报错消息里直接附上替代方案。这展示了一个很妙的模式规则的数据源来自生成物——prop 在注册表里标记 deprecatedLint 规则自动获得无需手工维护任何清单文档与执行就是同一份数据。规则如何接线两层配置仓库根目录vite.config.ts把packages/kumo/lint/kumo-plugin.js作为 jsPlugin 加载4 条通用规则no-cross-package-imports、no-primitive-colors、no-tailwind-dark-variant、no-flow-node-custom-render全部设为error——Lint 不过提交就过不去包内packages/kumo/vite.config.ts把enforce-variant-standard也设为error这条规则只在组件源码目录生效所以放在包里每条规则都配有测试文件如 enforce-variant-standard.test.ts保证规则本身不漂移。这种根目录管通用规则、包内补充专属规则的分层是 monorepo 的通用好模式。可借鉴到你的团队的清单白名单优于黑名单令牌表直接从主题源文件解析参考no-primitive-colors规则与设计系统自动同步报错信息写出改法给出正确的导出名、包名、替代 prop而不只是这里错了误报工程化非颜色工具类白名单表、../层级 ≥ 2 的判定、dark:正则边界——好规则的价值一半在防误报的细节里规则读元数据废弃标记、变体定义等由构建期生成Lint 规则运行时读取文档即规则规则要有测试每条规则配一个.test.ts防止规则自身回归设为 error 级别能挡住合并的 Lint 才真正生效。总结Kumo 对如何让团队代码保持一致的回答不是写更多文档而是5 条自定义 Lint 规则 1 份注册表元数据颜色令牌、暗色模式、变体命名、包边界、组件契约全部在源头被机器强制。任何在做设计系统或组件库的团队都可以直接抄这套规则即规范的作业。【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考