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 classNamebg-primarySave/Actionno-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来区分它们类名分类text-sm排版 (typography)text-primary颜色 (color)text-center布局 (layout)每个分组会映射到color、typography、spacing、shape、effects、motion 或 layout中的一类。这样allow: [layout]就能精确地只放行布局类。分类表定义在 packages/lint/src/grammar/categories.ts分类算法在 packages/lint/src/grammar/classifier.ts。Tailwind 类验证问你的 Tailwind 能否生成 CSSno-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考