Repolode
Submit
shadcn-ui

shadcn-ui/lint

An agent-first linter for Tailwind design systems that lets you define allowed styling rules and gives agents fixes drawn from your own components and theme.

View on GitHub
Stars
3,239
Forks
69
Open issues
13
Last commit
2 days ago

What is it?

@shadcn/lint is a linter for Tailwind v4 projects that enforces design system rules on UI code. You define what styling is allowed, such as restricting className overrides on a Button, blocking arbitrary values like p-[13px], or rejecting raw colors. When a rule is broken, the error explains what went wrong and suggests an alternative based on the components, variants, and theme in your project.

It runs as a plugin for ESLint or Oxlint and supports React, Vue, and Svelte. shadcn/ui is not required; it works with custom Tailwind components and themes, and can read component imports from prefixes, regex patterns, or a components.json file.

Rules can be scoped per component through contracts, and custom messages with placeholders such as {{sizes}} let you tell agents exactly which size, variant, or theme file to use. Agents run the lint command after making changes to check their work.

Key features

  • 01Restricts className overrides on components with per-component contracts.
  • 02Blocks arbitrary values and raw colors in favor of theme tokens.
  • 03Suggests fixes using sizes, variants, and theme files from your project.
  • 04Works with ESLint and Oxlint for React, Vue, and Svelte.
  • 05Does not require shadcn/ui and can read custom component imports.

Use cases

  • Keeping AI coding agents from restyling shared UI components in a Tailwind codebase.
  • Enforcing theme-based spacing and colors across a team's design system.
  • Applying design rules to third-party or monorepo component packages without forking them.

Quick start

  1. 1

    Install the package and ESLint with npm

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

    Create eslint.config.mjs with the plugin and rule (see README)

  3. 3

    Run the linter

    npx eslint .

Things to know

  • Only works with Tailwind v4 projects.
  • Oxlint reads only the script blocks of Vue and Svelte files, not the markup.
  • Requires Node.js 20.19 or later.

Topics

#linter#tailwindcss#design-system#ai-agents#eslint#oxlint#react#vue#agents#ai

FAQ

What is lint?
An agent-first linter for Tailwind design systems that lets you define allowed styling rules and gives agents fixes drawn from your own components and theme. @shadcn/lint is a linter for Tailwind v4 projects that enforces design system rules on UI code. You define what styling is allowed, such as restricting className overrides on a Button, blocking arbitrary values like p-[13px], or rejecting raw colors. When a rule is broken, the error explains what went wrong and suggests an alternative based on the components, variants, and theme in your project.
Is lint free to use? What license does it have?
lint is open source under the MIT license. Check the license terms before using it in commercial products.
Is lint still maintained?
Actively maintained. The last commit to lint was on Oct 19, 2026.
What can I use lint for?
Keeping AI coding agents from restyling shared UI components in a Tailwind codebase. Enforcing theme-based spacing and colors across a team's design system. Applying design rules to third-party or monorepo component packages without forking them.
How do I install lint?
Install the package and ESLint with npm: npm install -D @shadcn/lint eslint @typescript-eslint/parser Create eslint.config.mjs with the plugin and rule (see README) Run the linter: npx eslint .
Where can I get lint?
The source code and installation instructions are on GitHub: https://github.com/shadcn-ui/lint

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects