lint

An agent-first linter for Tailwind design systems. Write design system rules that agents can verify.

What is lint?

An agent-first linter for Tailwind design systems. Write design system rules that agents can verify.

Overview of lint

What it is

@shadcn/lint is an agent-first linter for Tailwind design systems. It allows developers to write design system rules that coding agents can verify. The tool works with Tailwind v4 projects and does not require shadcn/ui. It is available for both ESLint and Oxlint and supports React, Svelte, and Vue.

Key features

  • Define what is allowed in a design system; when an agent breaks a rule, the error explains what is wrong and suggests a fix based on components, variants, and the theme.
  • Works with existing design systems without requiring a rewrite.
  • Programmable: supports custom error messages with placeholders (e.g., {{sizes}}, {{component}}, {{file}}) that pull from the project’s components and theme.
  • Contracts allow per-component rules, letting different parts of a component have different allowances (e.g., layout, typography, spacing).
  • Includes rules such as shadcn/no-restyle and shadcn/no-arbitrary-values.
  • Built for agents: errors tell agents what broke, what to use instead, and where to find it.
  • Tested across more than 150 task runs; in one run per model, errors dropped to zero after lint feedback.
  • In Claude control runs, fixing violations with lint feedback cost 10% to 48% less than with rules alone.

Use cases

  • Enforcing design system rules in UI development, especially when coding agents generate code.
  • Allowing agents to write UI while ensuring they stay within design constraints (e.g., spacing, typography, colors).
  • Sharing lint rules across multiple projects while letting each project define its own contracts.
  • Applying rules to components from third-party packages without forking or wrapping them.

Getting started

Requires Node.js 20.19 or later (or Bun 1.3 or later) and a version supported by your linter. React with ESLint (requires ESLint 9.30 or later): bash npm install -D @shadcn/lint eslint @typescript-eslint/parser Create eslint.config.mjs: js 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', }, }, ]) bash npx eslint . React with Oxlint (requires Oxlint 1.80 or later): bash npm install -D @shadcn/lint oxlint See the repository README for full setup instructions.

License and pricing

The project is open source under the MIT license. Pricing is not stated beyond the open source license.

Based on the project's public README and repository metadata.

Add this badge to your README

Featured on YunoDB Badge styles & help

Maintain this project? Show that it is featured on YunoDB.

Markdown[![Featured on YunoDB](https://yunodb.com/badge/shadcn-uilint.svg)](https://yunodb.com/tools/shadcn-uilint?utm_source=github&utm_medium=badge)
HTML<a href="https://yunodb.com/tools/shadcn-uilint?utm_source=github&utm_medium=badge"><img src="https://yunodb.com/badge/shadcn-uilint.svg" alt="Featured on YunoDB" height="20"></a>