Leadership1 publisher2 min readPublished
A shadcn linter tells coding agents which fix the design system allows
The @shadcn/lint README asks teams to write design-system rules a coding agent can verify, with errors that name the allowed substitute drawn from the project's own components, variants and theme.
The Board Room · Leadership desk
What happened
- @shadcn/lint bills itself as an agent-first linter for Tailwind design systems, where maintainers define what is allowed and a broken rule returns an error suggesting a fix drawn from the project's own components, variants and theme.
- Where a TypeScript prop-type restriction reports only that padding is disallowed, the lint error names the substitutes: a size such as sm or lg, a margin, or gap on the parent element.
- The project says it tested the rules with coding agents across more than 150 task runs, and that almost every task reached zero violations in a single correction round.
Compiled by The Board RoomSomething wrong?How this is made
Why it matters
- decision The artifact a design-system owner reviews becomes the lint config, so approving a change to an allow list approves what every agent-written file is permitted to contain.
- constraint A convention that exists only in a style guide never reaches the agent at the moment it writes the code, which limits how much of a team's standard survives as more UI is agent-authored.
- cost The reported saving applies to the correction loop, while the up-front bill is an owner writing contracts component by component and part by part before any of it binds.
- precedent If the error message is where a standard gets delivered, later rule sets aimed at agents will be judged on whether their messages name the approved substitute.
Both enforcement paths stop the same line of code. Limit `Button`'s `style` prop to `Pick<React.CSSProperties, "margin" | "width">` and the TypeScript compiler rejects a padding value with `TS2353` [4]. The README says of that error: "It doesn't tell it how to size the Button" [5]. The lint version of the same policy answers that question inside the failure: `"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.` [6]
The rule itself is a config entry. `shadcn/no-restyle` takes a global allow list plus per-pattern contracts, so a team can permit `w-full`, `mt-*` and `mb-*` on `Button` while errors fire on `p-4`, `hover:rounded-full`, `md:h-12` and `w-48` [7]. Contracts can be scoped to one part of a component: `CardTitle` allowed typography but denied `font-*`, `CardContent` allowed spacing but not typography [8]. The README says the same policies written in TypeScript "can take complex types" [13], and that the linter route needs no change to the component API [10].
The trade-off sits in who writes the allow list. Opening spacing on `CardContent` lets an agent reach for `md:p-[13px]` until `shadcn/no-arbitrary-values` is switched on, which keeps padding on the theme scale [9]. Each permission granted widens what agent output may contain; each one withheld becomes a violation the agent has to spend a round correcting.
The supporting evidence is the project's own. In its Claude control runs, fixing violations with lint feedback cost 10% to 48% less than with rules alone [12]. The top of that range is nearly five times the bottom [1]. Plan against 10%. The README gives the saving as a percentage and refers readers to the evals for results and methodology [16].
The error text is authored: custom messages and contracts put the design system's own instructions in front of the agent, with suggestions drawn from the project's components, variants and theme [15]. And the setup step is written for the agent, telling it to read the project's SETUP.md and install the package [3].
This quarter the commitment is small. The package targets Tailwind v4 projects, does not require shadcn/ui, and is published for both ESLint and Oxlint [2], so a trial costs a config file and a CI run. The longer question is which standards survive contact with agent-written code, because a convention that exists only as a page in a style guide never enters the correction round. The README states its own purpose in the first line of the page: "Write design system rules that agents can verify." [14]
What to watch
- Whether anyone outside the project replicates the 150-run result on a design system whose rules they did not write.
- Whether the linked evals state what the 10% to 48% cost saving measures, and on which models beyond the Claude control runs.
- Whether accessibility or data-access rule sets adopt the same error-plus-suggested-fix format for coding agents.