shadcn lança linter para design systems Tailwind pensado para agentes

O que é o @shadcn/lint

A equipe shadcn lançou o @shadcn/lint, um linter "agent-first" para sistemas de design em Tailwind, descrito como uma forma de escrever regras de design system que agentes de código podem verificar. Quando um agente quebra uma regra, o erro explica o que está errado e sugere uma correção com base nos componentes, variantes e tema do projeto. A ferramenta funciona com Tailwind v4, não exige shadcn/ui e está disponível para ESLint (9.30+) e Oxlint (1.80+), requerendo Node.js 20.19 ou mais recente.

Diferença em relação ao TypeScript

O README compara a abordagem com a validação por tipos. É possível restringir a prop style de um botão com tipos (por exemplo, Pick<React.CSSProperties, "margin" | "width">), e o erro TS2353 informa que padding não é permitido - mas não diz ao agente como dimensionar o botão. Com o @shadcn/lint, o mesmo erro inclui orientação do design system: indica que o botão controla o próprio espaçamento, sugere usar tamanhos como sm ou lg, ou margin e gap no elemento pai, e aponta onde adicionar um novo tamanho, se necessário.

Como a configuração funciona

As políticas são configuradas sem alterar a API dos componentes, por meio de regras e contratos. Exemplos do README: permitir mt-*, mb-* e w-full no Button enquanto se nega mudar padding, forma ou altura fixa; permitir que CardTitle mude tipografia mas não família e peso da fonte; permitir que CardContent mude espaçamento mas não tipografia. Também é possível combinar no-restyle com no-arbitrary-values para exigir que padding use a escala do tema (aceitar p-6 md:p-8, rejeitar md:p-[13px]).

Recursos de mensagens e contratos

O linter é programável: mensagens de erro customizadas podem instruir agentes diretamente ("Use o size prop em vez de padding"), e placeholders como {{sizes}} e {{file}} inserem dinamicamente tamanhos disponíveis e caminhos de tema nas mensagens. Configurações compartilhadas (settings.shadcn) permitem reconhecer imports de componentes, funções de classe customizadas (além das embutidas como cn, clsx, cva, tv), funções de variante e anexar uma nota a todos os erros. Há suporte a monorepos, com reconhecimento de pacotes de UI compartilhados e overrides por diretório.

Resultados com agentes

A equipe testou as regras com agentes em mais de 150 execuções de tarefas e relata que quase todas chegaram a zero violações em uma rodada de correção. Em uma execução por modelo: Sonnet 5 (8/8 tarefas, 69 erros antes, 0 depois), Haiku 4.5 (8/8, 66 → 0), Opus 5 (8/8, 42 → 0), GPT 5.6 Terra (8/8, 117 → 0) e GPT 5.6 Sol (6/8, 98 → 0). Nas execuções de controle com Claude, corrigir violações com feedback do linter custou de 10% a 48% menos do que com regras sozinhas.

Regras e por que um linter

As regras incluem: no-restyle (restilização via className), no-raw-colors (cores cruas como bg-pink-500), no-arbitrary-values, no-inline-styles, no-unknown-classes (classes que o Tailwind não gera) e require-static-classes (classes que o linter não consegue ler, como bg-${color}). As regras foram desenvolvidas estudando design systems de produção e testadas com agentes.

Os argumentos para usar um linter: ele é programável, permite definir regras sem mudar componentes; o mesmo componente pode ser distribuído com contratos diferentes por projeto; é possível aplicar regras a componentes de terceiros sem forks ou wrappers; regras podem ser compartilhadas entre projetos. O README orienta adicionar ao AGENTS.md a instrução de rodar npm run lint e corrigir todos os erros após mudanças.

Conclusão

O @shadcn/lint se apresenta como camada de governança de design systems verificável por agentes, com regras orientadas a Tailwind, mensagens que ensinam a correção e resultados de testes próprios mostrando correção completa em uma rodada na maioria dos casos e custo reduzido em execuções com Claude. O projeto é open source sob licença MIT, com 1.7 mil estrelas no GitHub no momento da publicação.