@shadcn/lint工作原理揭秘：它如何读懂你的组件、主题与类分类

@shadcn/lint工作原理揭秘：它如何读懂你的组件、主题与类分类

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

如果你在用 AI 编写 UI 代码，很可能遇到过这样的烦恼：Agent 写出了不符合设计规范的颜色或间距，而你很难用一行报错让它明白"应该怎么改"。@shadcn/lint正是为此而生——它是一个agent-first（面向 Agent）的 Tailwind 设计系统 Linter，能读懂你项目里的组件、主题令牌和类名分类，并在报错时给出"符合你设计系统"的修复建议。

这篇文章将拆解它的核心工作机制，让你明白它如何在不运行应用的情况下，静态分析你的代码并精准定位违规点。

读懂组件：从 import 到真实定义文件

Linter 的第一步是搞清楚"你正在改的是哪个设计系统组件"。它主要依赖以下路径：

• components.json指向你的 UI 目录，Linter 读取其中导出的组件；
• 通过@/、tsconfigpaths、packageimports、workspaceexports等机制解析 import；
• 跟随re-export 和重命名导入一路回溯到真正的定义文件。

这意味着，即使你这样间接使用组件：

// components/widgets.ts export { Button as Action } from "./ui/button"

// 页面里 import { Action } from "@/components/widgets" return <Action className="bg-primary">Save</Action>

no-restyle规则依然能识别出Action其实就是Button，并正确报告对它的颜色覆盖。

相关源码见 packages/lint/src/project/component-imports.ts 与 packages/lint/src/project/components.ts。

读懂主题：解析 CSS 令牌

主题分析来自components.json中声明的 CSS 文件。Linter 会跟随其中的@import，读取@theme下的--color-*声明：

@theme inline { --color-primary: var(--primary); --color-brand: var(--brand); }

于是它就能区分：

• bg-brand✅ 允许，因为它指向一个已声明的令牌；
• bg-zinc-100❌ 报告，因为它使用了原始调色板颜色；
• bg-highlight❌ 报告，因为它指向一个未声明的令牌。

颜色工具类还会读取自己的命名空间：--background-color-surface只声明bg-surface，而--text-color-ink声明text-ink。这些逻辑集中在 packages/lint/src/project/theme.ts 与 packages/lint/src/grammar/tailwind-theme.ts。

类分类：区分排版、颜色与布局

text-sm、text-primary、text-center都以text-开头，但含义完全不同。Linter 利用cn的类分组（class groups）来区分它们：

每个分组会映射到color、typography、spacing、shape、effects、motion 或 layout中的一类。这样allow: ["layout"]就能精确地只放行布局类。分类表定义在 packages/lint/src/grammar/categories.ts，分类算法在 packages/lint/src/grammar/classifier.ts。

Tailwind 类验证：问你的 Tailwind 能否生成 CSS

no-unknown-classes规则会加载你项目安装的 Tailwind v4（连同主题、自定义工具类、变体、插件和配置），逐一判断每个类能否生成 CSS。它能抓到hovr:flex、rounded-huge这类拼写错误，并在发现相近的合法类时给出建议。

由于 Tailwind 加载器是异步的，它运行在一个worker 线程中，并按主题缓存结果。若 Tailwind 或主题无法加载，规则会告警并回退到语法检查。实现见 packages/lint/src/tailwind/oracle.ts。

变体、变量值与包装器

• 变体：no-restyle会从组件文件读取cva/tv定义，以及类型化的 props（如variant?: "default" | "destructive"），并据此给出变体建议。
• 变量值：Linter 会跟随类值"一跳"进入同文件变量，读取const/let初始值、条件分支、模板文本、数组和对象值。
• 包装器：一个把className转发给设计系统组件的包装组件（如SaveButton），会继承被包装组件的契约与变体建议；renderprop 的转发同样被追踪。

它看不到什么

Linter 静态分析有边界。以下情况它不会处理：

• 父选择器[&_button]:bg-primary无法回溯到子组件；
• 不可读的对象 props与跨 import 的类值；
• 纯 CSS 声明与@apply；
• 在 Oxlint 下的.svelte/.vue模板（Oxlint 只提供<script>块）。

完整的边界说明见 docs/how-it-works.md。

小结

@shadcn/lint的核心价值在于：它不只是一条报错，而是把组件识别、主题令牌、类分类三者结合，让每一条诊断都携带来自你设计系统的可执行修复建议。理解它的工作原理后，你就能更放心地把 UI 校验交给 Agent——它知道哪里错了，更知道该怎么改。

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