shadcn-ui /lint
An agent-first linter for Tailwind design systems. Write design system rules that agents can verify.
★ 3,363⑂ 76👁 4⑃ 105● 78▤ 10
+1
Daily
3,363
stars
76
forks
4
watchers
105
prs
78
issues
10
releases
README
@shadcn/lint
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.
Table of contents
- Quickstart
- TypeScript vs @shadcn/lint
- Built for agents
- Get started
- Rules
- Frameworks
- Configuration
Quickstart
Give your coding agent this prompt:
text
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.
TypeScript vs @shadcn/lint
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.
tsx
Submit
text
TS2353: Object literal may only specify known properties, and 'padding' does not exist in type 'Pick'.
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:
tsx
Submit
text
"p-4" is not allowed on : 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.
You decide what can change
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.
js
"shadcn/no-restyle": ["error", {
allow: ["layout"],
contracts: [
{ pattern: "^Button$", allow: ["w-full", "mt-", "mb-"] },
],
}]
tsx
// Allowed: use a size and let the page control placement and full width.
// Error: you are not allowed to change padding and shape.
// Error: you are not allowed to set a custom height or fixed width.
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.
js
"shadcn/no-restyle": ["error", {
allow: ["layout"],
contracts: [
{
pattern: "^CardTitle$",
allow: ["layout", "typography"],
deny: ["font-"],
},
{ pattern: "^CardContent$", allow: ["layout", "spacing"] },
],
}]
tsx
// Allowed: titles can change text size; content can change padding.
// Error: you are not allowed to change the title’s font weight.
// Error: you are not allowed to change the content’s typography.
Allow spacing changes. Require theme values.
Opening up spacing doesn’t havTop issues
#63Angular template support2 comments · 2026-09-29#132no-unknown-classes flags Tailwind v4 @utility classes1 comments · 2026-10-21#19Support a configurable suppression comment for approved one-off overrides1 comments · 2026-09-16#2Expose the rule engine through a programmatic API or CLI for Biome projects1 comments · 2026-09-14#182cva axes written with `satisfies` (or `as`) are not read, so no-restyle lists no variants or sizes0 comments · 2026-11-14#181`no-raw-colors` reports Tailwind's legacy `bg-gradient-to-*` utilities as undeclared theme colors when the project uses cn 0.5.20 comments · 2026-11-10#179Follow-up to #75: resolve Effect Option constructors by import binding, not dotted name0 comments · 2026-11-03#178no-restyle and require-static-classes: an imported `buttonVariants()` on a `<Link>` is not judged as `<Button>`0 comments · 2026-11-03
Latest release
@shadcn/[email protected] @shadcn/[email protected] 2026-11-02Patch Changes - 177 c4cf640 Thanks @shadcn! - Follow a call to a cva or tv result defined in the same file, so no-restyle checks every variant it can produce and require-static-classes no longer reports it as dynamic. - 172 19eee07 Thanks @shadcn! - Leave a plain element alone when it is the render target of a component that adds no classes, such as a PopoverTrigger that only spreads its props onto Base UI, so no-restyle and require-static-classes no longer judge it by that component. - 164 f0586bf Thanks @shadcn! - Stop warning about a contract entry the theme's Tailwind build generates, s