shadcn/lint六大核心规则一次讲透从no-restyle到no-unknown-classes全解析【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lintshadcn/lint 是一个面向 Tailwind 设计系统的 Lint 工具它帮你把哪些样式能改、哪些颜色能用变成机器可检查的规则。当 AI 编码代理或团队成员写错样式时它不仅能报错还会告诉你该用哪个变体、哪个主题色来替代——这正是它被称为 agent-first linter 的原因。本文用一篇带你吃透它的6 大核心规则。一、为什么需要 shadcn/lint用 TypeScript 类型也能限制style属性但类型报错只说不行不说该怎么做。而 shadcn/lint 的报错自带基于你组件库的修复建议列出可用的 size、variant、主题色 token 和定义它们的文件路径。它的核心特点✅不改组件 API规则写在 Lint 配置里组件代码保持灵活✅无需 shadcn/ui自己的 Tailwind 组件和主题就能用✅多框架支持React、Vue、SvelteESLint 和 Oxlint 双引擎✅官方实测在 150 次任务跑测中AI 代理基本一轮纠错即可清零违规成本降低 10%~48%二、六大规则速览 规则拦截什么一句话定位no-restyle通过className重设计系统组件外观归组件布局归页面no-raw-colorsbg-pink-500等裸色板色、未声明 token、SVG 硬编码色颜色必须走主题no-arbitrary-valuesp-[13px]、bg-[#333]等任意值值必须落在标尺上no-inline-stylesstyle内联属性、style元素样式必须走 classno-unknown-classesrounded-huge等 Tailwind 生成不了 CSS 的类名拼写和存在性兜底require-static-classesbg-${color}这类 linter 读不懂的类名保证其他规则看得见每条规则的完整文档都在 docs/rules/ 目录下规则共享的allow/deny/contracts/message选项说明见 docs/rules.md。三、no-restyle设计系统组件的外观锁 这是最核心的一条规则。设计原则是外观用组件变体布局才交给className。它怎么工作规则把你的类名分成 8 个类别layout布局、color颜色、typography排版、spacing间距、shape形状、effects特效、motion动效和unclassified无法识别。以allow: [layout]为例mt-4、w-full放行而p-4、bg-pink-500、rounded-full全部报错——且报错会列出组件的 sizes 和 variants。三个进阶玩法Contracts契约给不同组件定不同规则比如允许CardTitle改排版、允许CardContent改间距颜色谁都不能动deny 精准排除布局整体放行但单独禁掉w-*自定义文案报错信息可写成 Use a Button size: sm, lg直接告诉代理该用什么它能穿透 import、re-export 和转发className的包装组件所以SaveButton classNamep-4一样会被识别为对 Button 的重设计。 详见docs/rules/no-restyle.md四、no-raw-colors颜色只认主题 这条规则拦截三类野生颜色色板裸色bg-pink-500、text-amber-500未声明 token主题里没有highlight写bg-highlight照样报错SVG 硬编码色fill#ec4899、strokered这类字面量报错时会列出主题已声明的 token、给出附近颜色的建议并指明主题文件在哪。white、black、transparent、currentColor这类通用名直接放行。新手常见的疑问为什么utility tap-target自定义工具类不报错因为它属于你自己的词表而.text-danger { color: #f00 }这种普通选择器不会被当 token背后的颜色仍是裸色照样会被抓。 详见docs/rules/no-raw-colors.md五、no-arbitrary-values值必须落在标尺上 p-[13px]、rounded-[10px]、bg-[#333]是设计系统的大敌——它们绕过了你的 spacing 标尺和色彩 token。这条规则的亮点是能给出精确替代默认--spacing为 4px 时p-[13px]会提示Use p-3.25 instead (same value, on the scale)而且变体、负值、important 标记都会保留。注意两个边界data-[stateopen]:flex、bg-(--brand)这类任意变体和变量简写不算任意值直接放行布局类任意值可用allow: [layout]放行比如侧边栏的w-[320px]往往是合理的 详见docs/rules/no-arbitrary-values.md六、no-inline-styles样式请走 class 通道 组件里写style{{ color: red }}或塞一个style元素都会让设计系统形同虚设。这条规则的检查相当细腻✅放行用 CSS 自定义属性传递动态值style{{ --panel-width: \${width}px }}是官方推荐姿势❌报错普通内联属性、自定义属性里的硬编码色值--label-color: #ec4899、读不懂的 style 对象、style元素会顺藤摸瓜同文件的const colors { accent: #ec4899 }再引用colors.accent一样会被查出来例外按CSS 属性名配置如动画库的transform注意它不接收 Tailwind 类名。 详见docs/rules/no-inline-styles.md七、no-unknown-classes拼写错误的最后防线 rounded-huge、flex-cols、hovr:flex——这些类名 Tailwind 根本生成不了 CSS页面看起来能跑其实没生效。这条规则直接调用你项目里安装的 Tailwind v4 主题 自定义工具类 插件来做存在性校验拼写接近时给出纠错建议flex-cols→ Did you mean flex-col?编辑器里可一键替换主题里的utility自定义工具和 CSS 类选择器都被识别不误报外部样式表提供的类如editor-root通过allow加白名单官方建议先从warn级别启用边加白名单边收严。 详见docs/rules/no-unknown-classes.md八、require-static-classes让其他规则看得见 前五条规则都有一个前提类名要可读。如果你写了className{bg-${color}}linter 根本无法检查等于规则失效。这条规则专门拦截读不懂的类名✅ 放行静态字符串、完整类名间的三元选择、cn(mt-4, wide w-full)❌ 报错模板拼接、导入的未知变量、未知函数调用它是整个体系的地基读不懂的类名交给它报读懂的部分继续由其他规则把关。官方建议在组件目录内关闭它组件自己调用 variant 函数属于正常写法。 详见docs/rules/require-static-classes.md九、六条规则如何协同作战 单独使用当然可以但组合起来才是完整防线场景谁负责Button classNamep-4不该改间距no-restyleButton classNamep-[13px]值不在标尺上no-arbitrary-valuesButton classNamebg-pink-500用了裸色no-raw-colorsdiv classNameflex-cols类名不存在no-unknown-classesstyle{{ color: red }}内联样式no-inline-stylesbg-${color}读不懂require-static-classes⚠️ 两条容易踩的联动细节白名单互不通用某条规则的allow只对它自己生效no-restyle放行p-*不会放过no-arbitrary-values对p-[13px]的检查组件目录记得关规则no-restyle、no-arbitrary-values、require-static-classes要在组件目录内关闭否则组件自己给自己定样式也会报错而颜色类和存在性规则建议在组件目录保持开启完整的渐进式接入路径先 warn 后 error、逐条加规则见 docs/adoption.md规则背后的工作原理见 docs/how-it-works.md。十、新手快速上手路径 装包Node.js 20.19npm install -D shadcn/lint eslint typescript-eslint/parserOxlint 用户装oxlint即可配最小规则集先开no-arbitrary-values熟悉后再逐条加完整步骤见 SETUP.md让 AI 代理跑 lint在AGENTS.md里加一句改动后运行npm run lint并修复所有错误规则的价值立刻翻倍shadcn/ui 项目零配置components.json会自动发现组件目录和主题自建组件用settings.shadcn指定ui前缀即可规则的具体实现代码在 packages/lint/src/rules/ 下每条规则一个文件想深挖某个规则的边界行为读源码 对应测试是最高效的方式。一句话总结no-restyle管能不能改no-raw-colors和no-arbitrary-values管值对不对no-unknown-classes和no-inline-styles管写没写对require-static-classes管看不看得见。六条规则各司其职你的设计系统从此有了机器可执行的契约。【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考