为什么禁用p-[13px]shadcn/lint的no-arbitrary-values规则深度解析【免费下载链接】lintAn agent-first linter for Tailwind design systems. Write design system rules that agents can verify.项目地址: https://gitcode.com/gh_mirrors/lint3/lint 这篇文章面向新手带你彻底搞懂shadcn/lint一款为 AI Agent 打造的 Tailwind 设计系统检查工具中的no-arbitrary-values 规则为什么p-[13px]这样的任意值会被报出来、它如何自动给出p-3.25这样的替换建议以及如何用allow、contracts等配置快速接入你的项目。什么是任意值Tailwind 允许你用方括号写出任意 CSS 值例如p-[13px]13 像素的内边距rounded-[10px]10 像素的圆角text-[#E4E4E7]任意颜色单个看没问题但设计系统的核心是有限的设计令牌design tokens。每多一个13px你的项目就偏离设计标准一次写法问题p-4✅ 来自 4px 间距刻度可预测、可复用p-[13px]⚠️ 脱离刻度团队和 AI不知道它该是什么值bg-[#333]⚠️ 脱离主题颜色换个配色就崩了no-arbitrary-values 规则正是为此而生它拦截所有脱格的任意值并直接告诉你在设计系统里应该用什么。规则说明见 docs/rules/no-arbitrary-values.md。为什么 shadcn/lint 要禁用 p-[13px]1️⃣ 保持设计一致性设计系统靠有限选项维持一致性。如果13px能随手写很快就会出现13px / 13.5px / 14px的混战视觉层次彻底失控。2️⃣ 报错不是目的给 AI 一个正确的答案才是shadcn/lint 是agent-first为 AI 编程助手优先设计的检查工具。普通 linter 只会说这里不合规而它读取你的组件、变体和主题后报错信息本身就带着修复方案p-[13px] hardcodes an off-token value. Use p-3.25 instead (same value, on the scale). 关键细节13 ÷ 4Tailwind 默认--spacing间距单位3.25正好落在刻度上所以规则说同一个值但回到刻度上。换算逻辑在 scaleEquivalent 函数 中实现——变体前缀md:、负值-mt-[8px]→-mt-2、important 标记!都会被完整保留。3️⃣ 不只有间距颜色、圆角、字号全都会查规则还会读取你的主题 CSS 来给出更聪明的建议实现见 docs/how-it-works.md违规写法规则给出的建议原理p-[13px]p-3.25精确换算到间距刻度rounded-[10px]rounded-lg主题里该令牌恰好是 10pxtext-[13px]text-xs (12px), text-sm (14px)没有精确匹配时列出最近的刻度border-[#E4E4E7]border-border, border-muted在 OKLab 色彩空间里找最近的已声明主题色这些行为在测试 packages/lint/test/no-arbitrary-values.test.ts 中有完整覆盖。另外它不会误伤data-[stateopen]:flex、bg-(--brand)这类任意变体 / CSS 变量简写不属于任意值是允许的。如何启用 no-arbitrary-values在 ESLint 或 Oxlint 配置里一行即可推荐先放行布局类宽度、边距等几何值常需要精确值shadcn/no-arbitrary-values: [error, { allow: [layout] }]这样w-[320px]侧边栏宽度可以通过而p-[13px]、rounded-[10px]仍会被拦截。完整安装步骤支持 React / Vue / Svelte、ESLint / Oxlint见 SETUP.md规则选项总览见 docs/rules.md。哪些情况需要豁免三种常见配置① 精确放行某个值——设计确实需要 13px 时连md:变体形式也一并放行shadcn/no-arbitrary-values: [error, { allow: [layout, p-[13px]] }]② 按组件设合同contracts——只允许 Sidebar 使用任意宽度shadcn/no-arbitrary-values: [error, { contracts: [{ pattern: ^Sidebar$, allow: [w-*] }], }]③ 自定义报错话术——用{{suggestions}}、{{file}}等占位符让 AI 看到你自己写的规范message: Use {{suggestions|a theme token or scale value}} instead of {{className}}.完整选项allow/deny/contracts/message/scanAllStrings见 no-arbitrary-values 规则文档。⚠️ 别忽略这几个边界例外只对本规则生效allow: [p-[13px]]不会让 no-restyle 也放行它规则之间互不干扰。精确换算有前提只有 px 值是间距单位的 1/4 步长倍数才能给出精确替换如13.5px就不行其他单位只会给通用提示。组件目录内记得关组件自己需要ring-[3px]这类结构值官方建议在components/ui/**下关闭本规则做法见 docs/adoption.md。颜色建议基于亮色模式采纳前请肉眼确认设计匹配。总结问题答案为什么禁p-[13px]它是脱离设计刻度的硬编码值破坏设计系统一致性规则只报错吗不它直接给出p-3.25这类同值刻度替换或最近令牌建议误伤怎么办用allow精确放行、contracts按组件放行或message自定义话术对 AI 有多大帮助报错自带正确答案AI 一轮修正即可归零官方 150 次任务实测见 docs/evals.md一句话no-arbitrary-values 不只是查错而是把你的设计系统翻译成 AI 能直接执行的标准答案【免费下载链接】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），仅供参考