Já uso shadcn ou Tailwind: minha skill de design precisa repetir o que a biblioteca já define?

Fala aí, beleza? Você abriu o SKILL.md pra escrever as regras visuais do projeto e travou na primeira linha

porque o shadcn já tem componente pronto, o Tailwind já tem token, e escrever "use Button com a variante outline" começa a soar como copiar a documentação com outra fonte

A sensação é legítima: se a skill vira uma segunda documentação, ela desatualiza a cada release e ainda gasta contexto pra dizer o que o agente descobriria sozinho

Só que tem um pedaço que a lib NUNCA vai saber: quando usar cada coisa dentro do SEU produto

Bora traçar essa fronteira?

O que shadcn e Tailwind já entregam ao agente sem você escrever nada

Antes de decidir o que escrever, vale ver o que já está coberto por fora

O shadcn/ui mantém uma skill oficial pra agentes de código, documentada em ui.shadcn.com/docs/skills e versionada em skills/shadcn/SKILL.md dentro do repositório shadcn-ui/ui

A instalação sai pelo CLI do skills.sh:

npx skills add shadcn-ui/ui --skill shadcn

E aqui mora a parte massa: ela não assume nada do seu projeto

A ativação acontece quando encontra um components.json, e aí ela roda o comando de inspeção pra ler a configuração REAL:

shadcn info --json

O retorno traz framework, versão do Tailwind, aliases, base library (base, radix ou aria), biblioteca de ícones, componentes já instalados e os caminhos de arquivo resolvidos, tudo injetado no contexto do assistente

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

De onde ela veio:

Essa skill não apareceu do nada: ela é o shadcn/skills, introduzido pelo shadcn/cli v4, lançado em março de 2026

O shadcn/skills é justamente isso que você acabou de instalar: contexto pros agentes sobre componentes e registry, cobrindo primitivas Radix e Base UI, APIs atualizadas, padrões de componente e fluxos de registry

A mesma v4 trouxe mais coisa junto: registries passaram a distribuir um design system completo como payload único via registry:base (componentes, dependências, CSS vars, fontes e config em uma instalação), fontes viraram tipo de registry de primeira classe, e presets empacotam a config do design system (cores, tema, biblioteca de ícones, fontes e radius) em um código curto

Tem até como espiar antes de gravar arquivo, com as flags –dry-run, –diff e –view

O escopo que ela já cobre:

• referência dos comandos do CLI (init, add, search, view, docs, diff, info e build) com flags, dry-run, smart merge, presets e templates
• como funcionam CSS variables, cores OKLCH, dark mode, cores customizadas, border radius e variantes de componente, com orientação pra Tailwind v3 e v4
• como construir e publicar registries próprios (formato registry.json, tipos de item, dependências, CSS variables, build e hospedagem)
• o setup do servidor MCP do shadcn

E o Tailwind não fica atrás: no v4 a configuração é CSS-first

Os design tokens são declarados na diretiva @theme, ficam disponíveis como CSS variables por padrão e ainda instruem o Tailwind a gerar novas classes utilitárias

Ou seja: o agente já consegue descobrir sozinho quais componentes existem, quais tokens o seu tema declara e qual comando adiciona o que

Isso tudo é conhecimento de BIBLIOTECA

Nada disso é decisão de produto 🙂

A fronteira: o que a biblioteca resolve x o que só a sua skill pode dizer

A régua de corte é simples, e cabe em uma frase: se a informação está no site da lib ou sai de um comando do CLI, ela não entra na skill

O que entra é o que nenhuma doc pública tem como saber, porque depende do seu produto

Repara no padrão: a coluna da esquerda muda a cada release da biblioteca

A coluna da direita só muda quando o SEU produto muda

Por isso duplicar a esquerda é desperdício duplo: você gasta linha pra dizer o óbvio e ainda cria uma fonte que envelhece sozinha

O que escrever na skill de design quando a lib já está no projeto

Beleza, mas o que sobra pra escrever, na prática?

Sobra bastante, se você parar de descrever componente e começar a responder pergunta de decisão

1. Decisões de uso (o "quando", não o "como"):

A lib te conta que Dialog, Drawer e Sheet existem

Ela não tem como saber qual dos três é o certo pro seu fluxo de checkout

## Sobreposições
- Confirmação destrutiva: Dialog, sempre com o botão de confirmar à direita
- Formulário de edição em mobile: Drawer
- Painel de filtros: Sheet lateral, nunca Dialog

Três linhas, e o agente para de sortear

2. Lista fechada de variantes:

A doc lista tudo que o componente ACEITA

A sua skill lista o que é PERMITIDO, que quase nunca é a mesma coisa

## Botões permitidos
- default: ação primária, no máximo um por tela
- outline: ação secundária
- ghost: ação dentro de tabela ou card
- destructive: só no botão de confirmar de uma ação destrutiva
Qualquer outra variante precisa de aprovação de design

3. Proibições explícitas (com o porquê):

Essa é a parte que mais salva review

Proibição sem motivo o agente contorna, proibição com motivo ele respeita

## Proibido
- cor hexadecimal solta no JSX: quebra o dark mode, use os tokens do tema
- componente novo instalado no meio de uma feature: entra em PR separado

4. Vocabulário dos seus tokens:

O Tailwind v4 gera as variables a partir do @theme, então o agente enxerga os nomes

O que ele não enxerga é a INTENÇÃO por trás de cada nome, e é isso que você escreve: onde o token de acento é permitido, qual é a superfície padrão de card, qual token responde por texto secundário

5. Padrões de composição que se repetem:

Toda tela de listagem do seu produto tem cabeçalho, filtro, tabela e estado vazio na mesma ordem?

Isso é padrão de casa, não é doc de componente

Escreva a composição uma vez e o agente para de reinventar o layout a cada feature

Se você está na dúvida entre colocar essa parte aqui ou no arquivo de instruções do repositório, vale entender a diferença entre regras de design no CLAUDE.md e uma skill dedicada

6. Critério estético assumido:

Esse é o item que quase todo mundo esquece, e é o que separa interface com identidade de interface genérica

O repositório público anthropics/skills traz a skill frontend-design, em skills/frontend-design/SKILL.md, e o ponto dela é justamente esse: comprometer-se com uma direção estética específica ANTES de escrever código, em vez de cair no padrão genérico

A biblioteca te dá os blocos

A direção estética é escolha sua, e ela precisa estar escrita em algum lugar

Sinais de que sua skill virou cópia da documentação (e como cortar)

Dá pra diagnosticar isso sem filosofar muito, é tudo observável

Os sintomas:

• o corpo do SKILL.md passou de 500 linhas (a documentação oficial recomenda manter abaixo disso e dividir o excedente em arquivos separados, usando progressive disclosure)
• existem seções listando props e comandos do CLI
• a description é genérica e não diz QUANDO a skill se aplica
• a skill precisa de manutenção toda vez que a biblioteca lança versão

A causa:

Confundir referência com decisão

Referência é o que a lib publica e o CLI responde

Decisão é o que o seu time combinou e ninguém escreveu

A solução:

Primeiro, corte

O que era referência ou vira arquivo de apoio (a skill aceita arquivos opcionais em /scripts, /references e /assets) ou simplesmente some do texto

Depois, arrume a description, porque é ela que decide o acionamento

A description é injetada no system prompt e é contra ela que o pedido do usuário é comparado, então ela precisa ser escrita em terceira pessoa e conter o que a skill faz E quando usá-la

Os limites são validados: name até 64 caracteres (só letras minúsculas, números e hífens) e description até 1.024 caracteres, não vazia

---
name: design-produto
description: Define quando usar cada componente da interface, quais variantes sao permitidas e o que e proibido no produto. Use ao criar ou alterar telas, componentes e estilos.
---

Tome cuidado com uma coisa: essa economia não é decorativa

Só os metadados ficam sempre no contexto do agente, pra ele saber quando a skill se aplica

As instruções completas só são lidas quando a tarefa bate com a description, então cada skill custa apenas os metadados até ser usada

Skill inchada não é problema só de organização, é problema de leitura desnecessária na hora que ela dispara

Como prevenir daqui pra frente:

Revise frase por frase perguntando: isso sobreviveria a um update da biblioteca?

Se a resposta for não, a frase é referência e não deveria estar ali

Se a resposta for sim, é decisão, e é exatamente por isso que a skill existe

Como isso funciona nos meus projetos com Claude Code

No vídeo abaixo eu mostro as skills que rodo em todos os projetos, e a de design é uma das que eu mais gosto

O caso foi esse: depois de gerar o app inteiro com as skills de planejamento e execução, a interface saiu no visual padrão, genérico, sem identidade nenhuma

Projeto sem alma, como eu chamo lá

Pra corrigir, eu ativei uma skill de frontend design em vez de instalar um pacote de terceiros

E o prompt que eu escrevi não citava componente nenhum: era sensação e contexto

Visual clean e moderno que passasse confiança financeira, modo escuro, e o usuário sentindo controle das finanças sem sobrecarga

Ao final da execução, a própria ferramenta listou o que tinha mudado: modo escuro, tipografia, cor de acento, cards, barra de navegação e animações

Comparando as telas antes e depois, a tipografia mudou MUITO, os estilos ficaram mais sofisticados e os elementos ficaram bem mais consistentes

Aviso honesto: isso pode ocorrer ou não, porque depende bastante do prompt

Boa parte das reclamações de resultado ruim com IA nasce de prompt mal escrito, e nada disso aqui é bala de prata, é só o que funciona no meu uso diário

Existe outra skill de design bem usada na comunidade, inclusive, mas eu prefiro a que considero oficial por já resolver muitos dos casos

Onde cada camada mora:

O Claude Code carrega skills de quatro níveis: enterprise, pessoal, projeto e plugin

O critério estético que eu levo comigo fica na skill pessoal, em ~/.claude/skills/<nome-da-skill>/SKILL.md, que vale pra todos os projetos

As regras que só valem naquele produto (componente padrão, variantes permitidas, proibições) ficam na skill de projeto, em .claude/skills/<nome-da-skill>/SKILL.md, que só existe naquele repositório

E quando os nomes colidem, tem ordem: enterprise sobrescreve pessoal, e pessoal sobrescreve projeto

Skill de plugin não entra nessa briga porque usa namespace: uma skill em <plugin>/skills/deploy/SKILL.md vira /my-plugin:deploy e convive numa boa com uma skill deploy do projeto

Se essa divisão entre o que é seu e o que é do repositório ainda está nebulosa, eu destrinchei o critério de skill pessoal ou por repositório em outro post

E tem um detalhe de bastidor que ajuda a dimensionar a coisa: no projeto de exemplo do vídeo, o plano de implementação gerou 14 tarefas antes de qualquer linha de código sair

Com esse volume, deixar decisão visual no achismo é pedir pra ter 14 interpretações diferentes do mesmo design 😀

Ah, e vale lembrar: as skills do Claude Code seguem o padrão aberto Agent Skills, que funciona em várias ferramentas de IA

A descoberta é automática pelas pastas, sem registro via API e sem habilitação por requisição

Repara ali principalmente na divisão entre o que fica na skill pessoal e o que fica na skill do projeto, é o que evita reescrever tudo a cada repositório novo

Conclusão

A resposta pra pergunta do título é não: sua skill de design não precisa repetir o que a biblioteca já define

A régua cabe em uma frase: referência fica na lib, decisão fica na skill

A lib te diz o que existe e o CLI te diz o que está instalado

A skill diz o que o seu produto escolheu

O próximo passo é bem concreto, e leva uns dez minutos:

1. abra o seu SKILL.md atual
2. risque tudo que sai de um comando do CLI ou de uma página da documentação da biblioteca
3. olhe o que sobrou e cheque se ele responde três perguntas: quando usar cada componente, quais variantes valem e o que é proibido

Se o que sobrou responde as três, tá no ponto

Se sobrou pouca coisa, ótimo sinal: skill enxuta dispara melhor e não envelhece junto com a biblioteca

E se não sobrou nada, é porque a decisão de design ainda não foi tomada, e aí o problema nunca foi o arquivo… 🙂

até o próximo post!