Write design system rules that agents can verify.
@shadcn/lint is an agent-first linter for Tailwind design systems.
You define what’s allowed. When an agent breaks a rule, the error explains what’s wrong and suggests a fix based on your components, variants, and theme.
Works with your existing design system. No rewrite required.
@shadcn/lint works with Tailwind v4 projects (shadcn/ui not required). Available for both ESLint and Oxlint. Works with React, Svelte, and Vue.
Give your coding agent this prompt:
Read https://github.com/shadcn-ui/lint/blob/main/SETUP.md
and set up @shadcn/lint in this project.
Once installed, choose your rules and configure what’s allowed in your design system.
Prefer to configure it yourself? See Get started.
Take a Button that allows margin and width, but controls its own padding.
You can enforce that with types by limiting its style prop to
Pick<React.CSSProperties, "margin" | "width">.
<Button style={{ padding: 16 }}>Submit</Button>TS2353: Object literal may only specify known properties, and 'padding' does not exist in type 'Pick<CSSProperties, "margin" | "width">'.
The rule works. But this error only tells the agent that padding is not allowed. It doesn’t tell it how to size the Button.
With @shadcn/lint, the same rule comes with guidance from your design
system:
<Button className="p-4">Submit</Button>"p-4" is not allowed on <Button>: <Button> owns its spacing.
Use a size (sm, lg), or margin here or gap on the parent for space around it.
Add a size in components/ui/button.tsx only if the design explicitly calls for one.
Expressing these policies in TypeScript can take complex types. With
@shadcn/lint, you configure them without changing your component API.
Here are some examples.
Allow spacing with margin. Allow full width. Keep size and shape in the Button.
"shadcn/no-restyle": ["error", {
allow: ["layout"],
contracts: [
{ pattern: "^Button$", allow: ["w-full", "mt-*", "mb-*"] },
],
}]// Allowed: use a size and let the page control placement and full width.
<Button size="lg" className="mt-4 md:w-full" />
// Error: you are not allowed to change padding and shape.
<Button className="p-4 hover:rounded-full" />
// Error: you are not allowed to set a custom height or fixed width.
<Button className="md:h-12 w-48" />Give each part of a component its own rules.
Let Card titles change typography, but keep their font family and weight. Let Card content change spacing, but keep its typography.
"shadcn/no-restyle": ["error", {
allow: ["layout"],
contracts: [
{
pattern: "^CardTitle$",
allow: ["layout", "typography"],
deny: ["font-*"],
},
{ pattern: "^CardContent$", allow: ["layout", "spacing"] },
],
}]// Allowed: titles can change text size; content can change padding.
<CardTitle className="text-lg" />
<CardContent className="p-6" />
// Error: you are not allowed to change the title’s font weight.
<CardTitle className="md:font-bold" />
// Error: you are not allowed to change the content’s typography.
<CardContent className="text-lg" />Allow spacing changes. Require theme values.
Opening up spacing doesn’t have to mean allowing arbitrary values. Combine rules to let Card content change padding while keeping it on your theme’s spacing scale.
"shadcn/no-restyle": ["error", {
allow: ["layout"],
contracts: [
{ pattern: "^CardContent$", allow: ["layout", "spacing"] },
],
}],
"shadcn/no-arbitrary-values": "error",// Allowed: padding uses the theme’s spacing scale.
<CardContent className="p-6 md:p-8" />
// Error: you are not allowed to use an arbitrary padding value.
<CardContent className="md:p-[13px]" />Both approaches enforce the rule. With @shadcn/lint, the agent also sees
how to fix the code using what’s already in your design system.
We built @shadcn/lint for agents that write UI. The errors tell them
what broke, what to use instead, and where to find it. Suggestions come from your components, variants, and theme.
You can add custom messages and contracts so agents get your design system’s instructions with the error.
We tested these rules with coding agents across more than 150 task runs. Almost every task reached zero violations in one correction round.
Here are the errors before and after lint feedback in one run per model:
| Model | Completed tasks | Errors before | Errors after |
|---|---|---|---|
| Sonnet 5 | 8/8 | 69 | 0 |
| Haiku 4.5 | 8/8 | 66 | 0 |
| Opus 5 | 8/8 | 42 | 0 |
| GPT 5.6 Terra | 8/8 | 117 | 0 |
| GPT 5.6 Sol | 6/8 | 98 | 0 |
In the Claude control runs, fixing violations with lint feedback cost 10% to 48% less than with rules alone.
See the evals for results and methodology.
A linter is programmable. You can write rules for your design system without changing your components.
You define what’s allowed and what to use instead. Agents run your lint command to check their work.
- Ship the same components with different rules. Each project can define its own contracts without changing the component code.
- Use components you don’t own. Apply rules to components from third-party packages. No forks. No wrappers.
- Share rules across projects. Keep a shared configuration for your design system and let projects add their own rules.
Your components stay flexible. You decide how they should be used.
You can write custom error messages that tell agents what to do.
"shadcn/no-restyle": ["error", {
allow: ["layout"],
message: {
spacing: "Use the size prop instead of padding.",
},
}]When an agent writes:
<Button className="p-4">Save changes</Button>It sees:
Use the size prop instead of padding.
Use your component’s sizes, variants, and file paths in error messages.
For spacing errors, {{sizes}} lists the available sizes:
"shadcn/no-restyle": ["error", {
allow: ["layout"],
message: {
spacing: "Use a {{component}} size: {{sizes}}.",
},
}]For a Button with sm and lg sizes, the error becomes:
Use a Button size: sm, lg.
You can also tell agents where to find theme colors. For example, in
no-raw-colors:
message: "Use a theme color from {{file}}."If your theme is in src/index.css, the error becomes:
Use a theme color from src/index.css.
See all message placeholders.
Give each component its own rules. For example, let pages change a card title's typography:
"shadcn/no-restyle": ["error", {
allow: ["layout"],
contracts: [
{ pattern: "^CardTitle$", allow: ["layout", "typography"] },
],
}]// Allowed by the contract.
<CardTitle className="text-sm">Account settings</CardTitle>
// Reported: the contract does not allow color overrides.
<CardTitle className="text-pink-500">Account settings</CardTitle>See contracts and custom messages.
Requires Node.js 20.19 or later and a version supported by your linter.
Bun 1.3 or later works too, with bun lint or bun --bun lint.
Requires ESLint 9.30 or later.
npm install -D @shadcn/lint eslint @typescript-eslint/parserCreate eslint.config.mjs. If your framework already configures ESLint,
keep its parser setup and add the plugin, rule, and component override.
import { plugin as shadcn } from "@shadcn/lint"
import tsParser from "@typescript-eslint/parser"
import { defineConfig } from "eslint/config"
export default defineConfig([
{
files: ["**/*.{js,jsx,ts,tsx}"],
languageOptions: {
parser: tsParser,
parserOptions: { ecmaFeatures: { jsx: true } },
},
plugins: { shadcn },
rules: {
"shadcn/no-arbitrary-values": "error",
},
},
])npx eslint .Requires Oxlint 1.80 or later.
npm install -D @shadcn/lint oxlintCreate .oxlintrc.json:
{
"jsPlugins": ["@shadcn/lint"],
"rules": {
"shadcn/no-arbitrary-values": "error"
}
}npx oxlintRequires ESLint 9.30 or later.
npm install -D @shadcn/lint eslint @typescript-eslint/parser vue-eslint-parserCreate eslint.config.mjs. If you already use eslint-plugin-vue, keep
its parser setup and add the plugin and rule to that block.
import { plugin as shadcn } from "@shadcn/lint"
import tsParser from "@typescript-eslint/parser"
import { defineConfig } from "eslint/config"
import vueParser from "vue-eslint-parser"
export default defineConfig([
{
files: ["**/*.vue"],
languageOptions: {
parser: vueParser,
parserOptions: { parser: tsParser },
},
plugins: { shadcn },
rules: {
"shadcn/no-arbitrary-values": "error",
},
},
])npx eslint .Requires Oxlint 1.80 or later. Oxlint reads the <script> blocks of
.vue files, not the template. See the Oxlint limitation.
npm install -D @shadcn/lint oxlintCreate .oxlintrc.json:
{
"jsPlugins": ["@shadcn/lint"],
"rules": {
"shadcn/no-arbitrary-values": "error"
}
}npx oxlintRequires ESLint 9.30 or later.
npm install -D @shadcn/lint eslint @typescript-eslint/parser svelte-eslint-parserCreate eslint.config.mjs. If you already use eslint-plugin-svelte,
keep its parser setup and add the plugin and rule to that block.
import { plugin as shadcn } from "@shadcn/lint"
import tsParser from "@typescript-eslint/parser"
import { defineConfig } from "eslint/config"
import svelteParser from "svelte-eslint-parser"
export default defineConfig([
{
files: ["**/*.svelte"],
languageOptions: {
parser: svelteParser,
parserOptions: { parser: tsParser },
},
plugins: { shadcn },
rules: {
"shadcn/no-arbitrary-values": "error",
},
},
])npx eslint .Requires Oxlint 1.80 or later. Oxlint reads the <script> blocks of
.svelte files, not the markup. See the Oxlint limitation.
npm install -D @shadcn/lint oxlintCreate .oxlintrc.json:
{
"jsPlugins": ["@shadcn/lint"],
"rules": {
"shadcn/no-arbitrary-values": "error"
}
}npx oxlint