捕捉rounded-huge拼写错误：@shadcn/lint的no-unknown-classes规则实战指南

捕捉rounded-huge拼写错误：@shadcn/lint的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/lint

Tailwind 类名写错时不会报任何错误——rounded-huge、flex-cols、hovr:flex会静默失效，页面样式悄悄丢失，而你完全不知道发生了什么。@shadcn/lint 的no-unknown-classes规则专为解决这个痛点而生：它是 @shadcn/lint 这个面向 Tailwind 设计系统的智能 linter 中最实用的规则之一，能直接对照你项目里安装的 Tailwind v4、主题、自定义工具和插件，判断每个类名是否真的能生成 CSS。发现拼写错误时，它还会给出「Did you mean…?」式的纠正建议。

为什么 Tailwind 类名拼写错误如此危险 🕳️

在 CSS 的世界里，拼错一个类名是「无声失败」：

• 没有报错：浏览器和 Tailwind 都不会提醒你rounded-huge不存在；
• 没有样式：该元素上不会生成任何 CSS，视觉效果直接丢失；
• 排查困难：往往要等到设计稿和页面比对时，才意识到某个圆角、某条间距「凭空消失」了。

对于手写代码的开发者，这多是一个小坑；对于 AI 编码智能体，这更是灾难——智能体生成的类名拼写错误如果不被拦截，错误会一路流进生产代码。

这正是 @shadcn/lint 的设计哲学：让规则成为智能体可以验证的指令。当 no-unknown-classes 检测到未知类名时，报错信息不止于「这里错了」，而是直接告诉修复方向，例如：

"flex-cols" is not a class this project's Tailwind knows, so no CSS is generated for it. Did you mean "flex-col"?

并且这个纠正建议可以直接作为编辑器的一键替换建议应用，智能体看到报错后一轮修正即可通过，无需人工介入。

rounded-huge 实战：规则如何工作 🔍

来看一个典型的失败场景。假设你写了下面这样的代码：

<div className="hovr:flex tablet:flex rounded-huge" />

一行代码里有三个问题，no-unknown-classes 会逐一指出：

规则的工作方式可以概括为三步：

1. 加载你的主题：规则读取components.json指向的主题 CSS，连同其中的@import、自定义@utility、@custom-variant和插件一起加载；
2. 逐个提问 Tailwind：对每个类名询问「你能生成 CSS 吗？」——Tailwind 在独立 worker 线程中回答，结果按主题缓存，不拖慢检查速度；
3. 给出可执行的建议：找到相近的合法类名时建议替换（拼写纠正用了编辑距离算法，相邻字母颠倒只算一次改动，所以itms-center能精准指向items-center）；没有相近候选时，则引导你在主题中用@utility声明它。

关于「相近」的判定，算法源码在 similar.ts，其中「短词最多容错 1 个字符、长词最多 2 个」的预算设计，让建议始终精准而不会乱指。规则完整实现见 no-unknown-classes.ts。

三个常用选项：allow、contracts、message ⚙️

规则文档给出了清晰的选项说明（见 no-unknown-classes.md），上手时只需要记住三个：

• allow：放行来自主题之外样式表的类名，比如编辑器组件引入的外部类editor-root。注意豁免不等于生成 CSS，只放行应用真实加载的类；
• contracts：把外部类名限制在特定组件上。例如约定editor-root只能出现在Editor组件上，用在普通div上仍会被报告；
• message：用你自己的话写报错，{{suggestions}}、{{file}}等占位符可插入建议类名和主题文件路径，让智能体拿到你的设计系统专属指令。

官方建议的启用方式是先以warn级别开启，把外部样式表产生的误报逐一加入allow，再提升为error。这样既不会一上来就被大量警告淹没，又能渐进式建立干净的类名白名单。

主题加载失败时的兜底机制 🛟

如果你的主题 CSS 无法被加载（比如@import了不存在的文件），规则会自动降级：改用内置的 Tailwind 类名语法表，加上项目中发现的@utility名称和 CSS 类选择器继续检查，同时输出一条警告。

需要留意的是，兜底模式检查得更宽松——它接受任意变体前缀，也不会给出拼写建议，比如hovr:flex可能悄悄通过。看到主题加载警告后，先修复它再信任检查结果，这是文档中明确给出的提醒。多项目中某个主题损坏时，其他项目不受影响，会各自使用自己的主题继续检查。

与其他规则的黄金搭档 🤝

no-unknown-classes 很少单打独斗，它和 rules.md 中列出的其他规则形成互补：

• 搭配no-raw-colors：hovr:bg-primary（变体拼错）由本规则报告，bg-primry（色板 token 拼错）则交给no-raw-colors，后者能基于你的主题 token 给出更聪明的建议，两者各管一段、互不越位；
• 搭配no-restyle：本规则管「类名是否存在」，no-restyle管「组件允不允许被这样改样式」，rounded-huge在组件上未分类的类名甚至可能同时触发两者；
• 搭配require-static-classes：像`bg-${color}`这类 linter 读不懂的动态类名，需要后者先把它们暴露出来。

总结：给你的 Tailwind 项目装上拼写雷达 ✅

回到标题的问题——rounded-huge这类拼写错误为什么必须被捕捉？因为它静默、无声、且越到后期发现成本越高。no-unknown-classes 规则的价值在于三点：

1. 零误杀：以你项目里真实安装的 Tailwind 为准，新语法、插件类名（如 typography 插件的prose）、自定义@utility全部天然识别；
2. 可执行的建议：报错即修复方案，对新手是学习路径，对 AI 智能体是一轮修正确的闭环；
3. 可定制的边界：allow、contracts、自定义message让你精确划定「哪些类名合法」，而不必改动组件代码。

启用只需要一条配置，把它加入 ESLint 或 Oxlint 的规则列表即可，完整规则一览与共享选项说明见 rules.md，各框架（React / Vue / Svelte）的接入细节参考 react.md、vue.md、svelte.md。给项目装上这个拼写雷达，让每一个「无声失效」的类名都现出原形。

【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lint