ISSUE 067  ·  17 NOVEMBER 2026 ELEN RSS
CodeCity
DESIGN № 0058

@shadcn/lint: the linter that corrects your agent instead of scolding it

@shadcn/lint is a plugin for ESLint and Oxlint, not a standalone command-line tool. You declare which Tailwind classes are allowed on each component, and when someone breaks the rule the error does not merely refuse: it names the class to use instead, pulled from your own components, variants and theme. It works with Tailwind v4, needs no shadcn/ui, and covers React, Svelte and Vue. MIT licence, no key and no account, and it is not an MCP server. In our test it caught both traps I set, with a message that handed over the fix; but the first pass of the second trap came back empty, because without a components.json file the no-restyle rule did not run at all and "all clean" was silence, not a check. The package is 322,286 bytes across eight files with two dependencies, version 0.2.5 shipped on 2 November 2026 at 19:21 UTC, and last week's downloads are 3,050,670. It needs ESLint 9.30 or later. Score 8.6/10.

@shadcn/lint, ο linter που διορθώνει τον πράκτορα αντί να τον μαλώνει

What it does

Your agent wrote a button with p-[13px] and bg-pink-500. You saw it in review two hours later. @shadcn/lint exists so you see it in the first minute.

Two words first. Tailwind styles elements without a CSS file: you attach short class names to the element, such as p-4 for spacing or text-sm for type size. Those names point at a scale you defined yourself, and a design system is the written set of values your project allows. In a beginner’s words: the tool keeps a list of what is allowed on each element, and checks whether the code respected it.

The keyword is “plugin”. There is no shadcn-lint command you run by itself. It is a plugin for two linters — programs that read your code and complain — ESLint and Oxlint.

You declare which Tailwind classes are allowed on each component, in the form of a contract. A contract can say that Button owns its own spacing, so from the outside it may only be given width and outer margins. When someone breaks it — often an agent writing quickly — the check fails. And here is the difference that counts: the message does not stop at “not allowed”. It says which class to use instead, taken from your components, your variants, your theme.

It works with Tailwind v4 and covers React, Svelte and Vue; shadcn/ui is not required. It exposes six rules: no-restyle, no-raw-colors, no-arbitrary-values, no-inline-styles, require-static-classes and no-unknown-classes.

And one paragraph is mandatory here, because this is the third tool of the shadcn family on our site. shadcn-mcp (article 0012) and shadcn-ui-mcp-server (article 0022) expose the component registry to an agent over MCP: they give the agent components and open the source. @shadcn/lint gives nothing; it checks which Tailwind classes were used on those components and stops the mistake before it reaches review. One hands over, the other stands guard.

What the registries say. On npm the latest version is 0.2.5, published on 2 November 2026, 19:21 UTC per the time["0.2.5"] field (package). The first release went up on 14 September 2026, and the total is 11 releases. The license field is MIT and engines.node declares >=20.19. The package is 322,286 bytes across 8 files, with only two runtime dependencies: cn 0.4.0 and @eslint/core ^0.17.0. Downloads are 3,050,670 for the week of 26 October to 1 November and 7,459,190 for the month of 3 October to 1 November (npm statistics). On GitHub shadcn-ui/lint has 3,300 stars, 71 forks and 6 open issues, in TypeScript, under the MIT licence; it was created on 2 September 2026, its last push is 2 November 2026, and it is not archived. Its description is one sentence: “An agent-first linter for Tailwind design systems.”

And the caveat up front: version 0.2.5, short of 1.0, a project two months old. Those 6 open issues are a small number, but they also hide the fact that few people have trodden this path yet.

Who it is for

For anyone who has a design system — or a set of rules they want to keep — and watches an agent punch holes in it.

The beginner sees the benefit at once. No account, no key, no need to have heard the term MCP; all you need is Tailwind in your project.

The professional gains three things: a check that fits a pipeline step and turns the pull request red the moment the contract breaks; a check that costs nothing in the assistant’s context; and the tool itself as a means of self-correction for the agent, since the message states the fix.

Who it is not for. If you do not work with Tailwind, there is nothing to check; this checks class names, not behaviour. And for a critical system, hesitate: the version is 0.2.5.

Install

The quick route, which the tool itself offers: let your agent do the setup, with one sentence.

Read https://github.com/shadcn-ui/lint/blob/main/SETUP.md and set up @shadcn/lint in this project.

Manually, from the root of the project. Start with the Node version — you need 20.19 or later, per the engines.node field:

node -v

The install as a development dependency. @shadcn/lint needs ESLint 9.30 or later, and it wants the TypeScript parser too, which is why it goes in alongside:

npm install -D @shadcn/lint eslint @typescript-eslint/parser

The config file, written once:

import { plugin as shadcn } from "@shadcn/lint";

export default [
  {
    files: ["**/*.{ts,tsx,js,jsx,svelte,vue}"],
    plugins: { shadcn },
    rules: {
      "shadcn/no-restyle": ["error", { allow: ["layout"] }],
      "shadcn/no-raw-colors": "error",
      "shadcn/no-arbitrary-values": "error",
    },
  },
];

The no-restyle rule wants a per-component contract, and allow: ["layout"] grants a first, general permission: whatever belongs to layout is allowed. You write the other contracts where you need them. And the check:

npx eslint .

Using it per LLM

@shadcn/lint is not MCP. You do not declare it in a config file as a tool, it has no tool catalogue, there is no tools/list, no restart is needed. It is a plugin of the tool the agent already runs, and the agent sees it through the error messages of ESLint or Oxlint, which are written to be read by an agent. You are not handing it a tool schema; you are handing it error output that states the fix.

Two shell commands. The check:

npx eslint .

And the attempt at automatic fixing:

npx eslint . --fix

We write the second with a question mark beside it: it leans on ESLint’s own fixing machinery, and I did not verify it, so I do not promise it.

Claude Code

In the project’s rules file you write the convention: Tailwind is checked with @shadcn/lint, the check runs before any claim of completion, and a finding gets fixed rather than bypassed.

npx eslint .

The . means the current folder; run it from somewhere else and it checks other files, and you think everything is clean. Judge by the exit code: zero means clean.

Codex CLI

The same shape in an AGENTS.md file. Tell it that the messages are written to be read, so it uses them as instruction and does not guess the fix — inside a loop, that cuts rounds.

npx eslint .

Cursor

Cursor shows ESLint findings inside the line of code, so you see the error as you type. The shell check stays the same:

npx eslint .

Where it wins, where it loses

It wins on the message: it does not say “this class is not allowed” and leave you to search; it says which one to use and where the answer comes from.

It wins on its nature: a deterministic rule over names, not a model’s opinion. And it wins on context cost: zero tool definitions in any session, one package of 322,286 bytes with two dependencies.

Now where it loses. First, and most seriously: it can fall silent without telling you. In my test no-restyle passed quietly when components.json was missing or when a component’s import could not be resolved. Zero errors meant “it did not look”. The tool says so when it cannot find a Tailwind stylesheet, but not when a rule did not run. Put it in a pipeline and trust the green, and you are trusting a lie.

Second, scope: it speaks only about Tailwind classes on components. It does not check logic, accessibility, or what happens while the program runs. And speed on a large project was measured by nobody — anyone who gives you a figure without having run it, ask them how they know.

Testing

I ran the tool and measured.

I installed @shadcn/lint@0.2.5 with ESLint 9.39.5 and built my own trap files, written wrong on purpose, because I know what should be found.

Trap 1 — a dirty component. On one component I wrote md:p-[13px], bg-pink-500, rounded-huge and text-[#ff0000]. The check produced 4 errors, and the message handed over the fix: "md:p-[13px]" hardcodes an off-token value. Use "md:p-3.25" instead (same value, on the scale). For rounded-huge it explained that it is not a class my project’s Tailwind knows, so no CSS is produced for it.

Trap 2 — the rule that falls silent. I gave no-restyle a contract, { pattern: "^Button$", allow: ["w-full", "mt-*", "mb-*"] }, and wrote <Button className="p-4 hover:rounded-full" />. My first pass came back empty. With a relative import, ./Button, and no components.json, the rule passed quietly: the code was not clean, the check was blind. After I added components.json and changed the import to @/components/ui/button, 4 errors appeared with guidance drawn from the design system: "p-4" is not allowed on <Button>: <Button> owns its spacing. And for the other, "md:h-12" ... its contract allows w-full mt-* mb-*. Use one of those, or put layout classes on a parent element — beyond the fix, it told me the rule behind it. The two allowed classes, mt-4 and w-full, passed clean.

The empty pass is the most useful part of the test: without components.json, or with an import the linter cannot resolve, no-restyle says nothing, and you see it as “all clean” when it simply did not look.

A diagnosis it produced on its own. With components.json pointing at a stylesheet that does not exist, it printed that it found no file importing Tailwind, and therefore no-raw-colors cannot check the declared tokens. It tells you what it failed to check rather than falling silent — but it does that when the failure is at the level of the theme, not the component.

Timing: ~1.9 seconds for one pass over my small sample. I did not measure time on a real, large project and I do not offer it as a prediction; I also did not run the Oxlint side, my test was done with ESLint. Any number not stated here is not ours.

What it costs

The tool. Zero money: @shadcn/lint is MIT and has no locked feature. It needs no key, no account, and no model call: its output is deterministic rules over class names.

The context. It is not an MCP server, so it loads no tool schemas into every session: its token tax before you write a word is zero. Its weight is what you install: 322,286 bytes across 8 files (measured from the registry field), with only two runtime dependencies — cn 0.4.0 and @eslint/core ^0.17.0. Installing it left 4.0 MB across 113 files on disk in our test, and one lint pass took ~1.9 seconds on our small sample. For scale: a tool with heavy model dependencies runs to hundreds of megabytes; here the cost is comparable to an ordinary ESLint plugin.

The work. The model is not touched: the check is a rule, not a model’s opinion. What you buy with your time is declaring the policies — which Tailwind classes are allowed per component, as contracts. And one cost we measured: without components.json (or with an import the linter cannot resolve) the no-restyle rule does not run at all, and you see it as “all clean”. The tool does say so when it cannot find a Tailwind stylesheet, but it does not tell you a rule went silent because it could not resolve the component.

Telemetry. There is none: the package has two dependencies and neither ships data. That is not our claim — it is its dependency list, read from the package itself.

Verdict

Score: 8.6/10.

It achieves its purpose: the error message hands over the fix from your own design system, the rules are deterministic, the context cost and the money are zero, and it works with Tailwind v4 without requiring shadcn/ui. The score is a judgement, not a measurement.

What it lacks is age — 0.2.5, two months — and, more seriously, honesty: when it cannot resolve the component it falls silent instead of shouting, and green can mean “it did not look”.

In practice: set it up on a project that already has a design system; if you have none, write the contracts first. Make sure components.json is right, or no-restyle will not run at all. Pin the version in your pipeline. And do not make it a critical gate in production yet: it is two months old, and we know one way it goes quiet.

Sources:

https://github.com/shadcn-ui/lint

https://registry.npmjs.org/@shadcn/lint

https://github.com/shadcn-ui/lint/blob/main/SETUP.md