Como criar uma skill de design quando o projeto não tem design system?

Fala aí, beleza? Todo projeto que "não tem design system" já tem um, só que ninguém escreveu ele ainda 😀

Ele está espalhado no CSS: as três cores que aparecem em toda tela, o espaçamento que se repete sem ninguém ter decidido, o card que virou padrão na marra

O problema aparece quando você pede uma tela nova pro agente sem nenhuma regra escrita

Aí ele preenche o vazio com o default dele

A própria skill oficial frontend-design, da Anthropic, descreve três visuais que se repetem em design gerado por IA: fundo creme com serifada de alto contraste e acento terracota, fundo quase preto com acento verde ácido ou vermelhão, e layout tipo jornal com fios finos e colunas densas

E o ponto dela é justamente esse: isso aparece como padrão automático, não como decisão de projeto

A saída não é inventar um sistema do zero e empurrar goela abaixo do repositório

A saída é extrair o que já existe e escrever isso como regra

Neste post eu monto uma skill de design partindo do código atual do projeto, com o critério pra decidir o que vira regra e o que fica de fora

O que você precisa antes de começar

• Claude Code instalado e um projeto com CSS e componentes reais pra ler (skill de design em projeto vazio não tem de onde tirar regra nenhuma)
• Uma decisão de escopo: ~/.claude/skills/ é pessoal e vale em todos os projetos da máquina, e .claude/skills/ fica dentro do repositório, versionado junto com o código
• Node e npm, caso você queira medir o CSS com o wallace-cli (npm install wallace-cli)
• Noção do frontmatter: o SKILL.md exige name (até 64 caracteres, só letras minúsculas, números e hífens, sem começar nem terminar com hífen) e description (até 1024 caracteres, não vazia, dizendo o que a skill faz e quando usar)

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

E o CLAUDE.md, entra onde nisso?

Ele é o arquivo de contexto do projeto, documentado pela própria Anthropic como jeito de customizar o comportamento do agente pra base de código

Papel diferente do da skill: o corpo da skill só carrega quando ela é usada, então dá pra ser bem mais detalhista ali dentro

Se você ainda está na dúvida entre deixar as regras de design no CLAUDE.md ou isolar tudo numa skill, vale resolver isso antes de escrever a primeira linha

Passo a passo: da leitura do código à skill de design pronta

1. Inventariar o que já existe no CSS

Antes de opinar qualquer coisa, mede

O wallace-cli, do Project Wallace, roda análise de CSS direto na linha de comando:

npm install wallace-cli
wallace path/to/styles.css
wallace path/to/styles.css --json

O --json te dá saída estruturada, que é o que interessa pra jogar no agente depois

O mesmo Project Wallace publica o css-design-tokens, que percorre o CSS procurando cores, font-sizes e gradientes e transforma isso em formato compatível com a spec de Design Tokens

O erro comum deste passo: confiar na contagem de cores únicas sem normalizar antes

No analisador do Project Wallace, cores únicas são contadas pela representação em texto, ou seja, Red, red e #f00 contam como valores diferentes

Se você não normalizar, o relatório vira um monstro de dezenas de cores que na real são meia dúzia 😛

2. Separar repetição de acidente

Agora vem a parte que ninguém faz: olhar a lista e perguntar o que é padrão e o que é sobra

Valor que aparece em várias telas, escrito por gente diferente, em momentos diferentes? Isso é padrão de fato, mesmo sem ninguém ter documentado

Valor que aparece uma vez só, numa tela antiga que ninguém abre? Isso é resto

Eu uso um corte simples: se o valor sobrevive em pelo menos três telas independentes, ele entra na conversa

Tome cuidado aqui: esse número é critério editorial meu, não é regra oficial de lugar nenhum, e você pode calibrar pro tamanho do seu projeto

O erro comum deste passo: pegar a exceção legada e promover ela a regra

Uma vez documentado, aquele hack vira lei e o agente vai replicar ele pra sempre

3. Listar os componentes de fato usados

Não vale listar o que existe na pasta de componentes

Vale listar o que é importado e renderizado de verdade

Grep de import resolve boa parte disso, e o que sobrar você confere na mão

O erro comum deste passo: documentar componente morto

Aí a skill de design manda o agente usar um Button antigo que ninguém mais toca, e você acabou de ressuscitar dívida técnica com ajuda de IA haha

4. Criar o diretório da skill

No Claude Code, cada skill é um diretório que tem o SKILL.md como entrypoint, mais arquivos de apoio opcionais: templates, exemplos, scripts e documentação de referência

.claude/skills/
└── designing-ui/
    ├── SKILL.md
    ├── referencia/
    │   ├── cores.md
    │   └── espacamento.md
    └── exemplos/
        └── card.tsx

O erro comum deste passo: jogar tudo dentro do SKILL.md e transformar o arquivo num calhamaço

5. Escrever o frontmatter

As boas práticas oficiais de autoria pedem nome específico e em gerúndio em inglês, no estilo processing-pdfs, analyzing-spreadsheets e testing-code

E desaconselham nome vago tipo helper, utils, tools, ou genérico tipo documents, data, files

---
name: designing-ui
description: Aplica as regras visuais deste repositório (cores, espaçamento, tipografia e componentes já em uso) ao criar ou alterar telas. Use quando for construir uma tela nova, mexer em layout ou revisar UI deste projeto.
---

A description merece carinho porque ela é o gatilho: as descrições das skills carregam no início da sessão, então é ali que o modelo decide se aquilo é relevante ou não

A especificação de Agent Skills também aceita campos opcionais no frontmatter: allowed-tools (experimental), compatibility, license e metadata

O erro comum deste passo: escrever description só com o que a skill faz, esquecendo o quando usar

6. Calibrar o grau de liberdade regra a regra

Essa é a sacada que muda a qualidade da skill

A documentação oficial orienta calibrar o grau de liberdade: baixa liberdade quer dizer guardrails e instruções exatas, como migrações de banco que precisam rodar em sequência, e alta liberdade quer dizer direção geral, como em code review, onde o contexto define o melhor caminho

Traduzindo pro design: paleta e escala de espaçamento são baixa liberdade (valor exato, sem margem pra criatividade)

Hierarquia visual e densidade de uma tela específica são alta liberdade (direção geral, o agente decide olhando o contexto)

O erro comum deste passo: escrever a skill inteira em baixa liberdade

Aí ela vira uma camisa de força e o resultado fica pior que o default

7. Aplicar progressive disclosure

Por padrão, name e description ficam sempre no contexto, e o conteúdo completo só carrega quando a skill é usada

Pra skills complexas dá pra ir além e usar progressive disclosure: SKILL.md enxuto, com o detalhe morando nos arquivos de apoio

O motivo é bem prático e a doc oficial fala isso na lata: depois de carregado, cada token do SKILL.md compete com o histórico da conversa e com o resto do contexto

Então o SKILL.md fica com as regras inegociáveis e os ponteiros, e a tabela gigante de tokens vai pro referencia/cores.md

O erro comum deste passo: transformar a skill numa enciclopédia do design system que come contexto em toda tarefa

8. Testar acionando dos dois jeitos

O Claude aciona a skill sozinho quando ela é relevante, e você também pode invocar direto com /nome-da-skill

Teste os dois:

• Peça "cria uma tela de listagem de usuários" sem citar a skill, e veja se ela é acionada
• Depois rode /designing-ui na mão e compare o resultado

Se ela não acionou sozinha, o problema quase sempre está na description, não no corpo

O erro comum deste passo: testar só na invocação manual e achar que está tudo certo

No dia a dia, o acionamento automático é o que mais vai valer

9. Aplicar o critério de corte

Chegou a hora de cortar, e é aqui que a skill de design fica boa ou vira opinião disfarçada de regra

O teste final de cada linha: se você não consegue apontar onde no código aquilo já acontece, aquilo não é regra, é gosto

Passou pela tabela, a skill está pronta pra rodar: SKILL.md curto com as regras que sobreviveram, arquivos de apoio com o detalhe, e o teste do passo 8 pra confirmar que ela aciona sozinha

O que ficou de fora não some, vira lista de proposta de mudança pra discutir com o time depois 😀

O que aprendi construindo essa skill na prática

No vídeo abaixo eu faço exatamente esse exercício com o Impeccable, e a montagem do teste foi de propósito

Eu criei antes uma landing page pra um SaaS fictício de gestão de tarefas SEM nada disso instalado, pra depois instalar por cima e comparar antes e depois no MESMO projeto

E olha, a instalação foi num projeto já rodando, sem começar do zero: dava pra trocar o pneu com o carro andando

Na hora de instalar eu escolhi o nível de projeto pro Claude Code, e preferi a opção que copia os agentes em vez da que cria link, porque já tive problema com a segunda 😅

Fiz no Claude Code por ser a ferramenta que eu mais uso no dia a dia, mas dá pra registrar que aquilo não estava preso a ele

O detalhe que mais me marcou: antes de qualquer análise de design, o primeiro passo faz uma ENTREVISTA sobre o projeto

Ele me perguntou se o repositório era só uma landing page ou se ia crescer, qual era o público (empreendedores individuais chegando por anúncio) e se o estilo de copy atual estava correto

Detalhe engraçado: ele começou perguntando em inglês, e passou a responder em português depois que eu respondi em português haha

O resultado da entrevista foi um arquivo de produto, e é esse arquivo que vira referência pras etapas seguintes

Ou seja: o agente não sai chutando visual, ele primeiro entende o que aquele projeto é

Em vez de adivinhar a ordem, eu perguntei pro próprio agente qual seria a sequência pra primeiro achar as falhas e depois polir

Ele respondeu com 4 etapas: gerar a documentação de design, fazer a crítica, auditar as mudanças e por fim polir a versão final

Segui exatamente nessa ordem

Rodei a documentação, peguei o documento de design do projeto, e só aí parti pra crítica

A crítica eu entendi como uma revisão heurística: ela usa a lista do que NÃO pode acontecer como referência pra julgar o projeto

E aqui vem a parte que dói: antes de rodar, eu tinha olhado aquela landing gerada sem nada por cima e achei bem boa

Pra mim estava excelente, eu seguiria com aquilo do jeito que estava

Depois da crítica, veio uma lista de vários problemas

O que me convenceu não foi "trocar um layout por outro"

Foi ele analisar frentes separadas: tipografia, cores e contraste, design espacial, responsividade, interação, motion e escrita

Cada skill cuida de uma frente, então dá pra atacar só uma delas se for o caso

E isso conversa direto com os três visuais que a skill oficial frontend-design descreve: quando ninguém escreve a regra, o default entra sozinho

Na página do projeto tem os exemplos de antes e depois com os problemas citados: degradê roxo, fonte Inter, copy genérica e cards dentro de cards

Se você for usar, leia a página antes, porque ela explica como o fluxo funciona

Quando essa abordagem se aplica (e quando usar outro caminho)

Projeto legado sem padrão nenhum: é o caso mais óbvio

Não tem o que documentar a não ser o que está no CSS, então roda a análise, normaliza os valores e escreve a skill em cima do que sobrou

Projeto pequeno que quer congelar o padrão antes de crescer: aqui a skill vai em .claude/skills/, versionada junto com o código, pra todo mundo puxar no git pull

Se a dúvida for entre isso e deixar a skill valendo em todos os projetos da sua máquina, o critério é se as regras são do repositório ou suas

Quando a skill amadurece e precisa ser distribuída: no Claude Code, plugins empacotam skills (além de agentes, hooks e servidores MCP)

A documentação oficial descreve exatamente esse caminho: começa com configuração autônoma em .claude/ pra iterar, e converte em plugin com manifesto na hora de compartilhar

Conclusão

O recado do post é um só: regra é padrão medido e repetido, não é gosto pessoal e muito menos default de IA

Projeto sem design system não precisa de um sistema inventado do zero, precisa de alguém que leia o que já está lá e escreva

Próximo passo prático pra hoje: roda a análise no CSS do teu projeto, normaliza as cores na mão, e escreve uma primeira versão CURTA do SKILL.md com três a cinco regras que sobrevivem ao teste da repetição

Se travar na estrutura, a Anthropic mantém a skill oficial skill-creator no repositório público de skills, e ela te guia na definição do caso de uso, no frontmatter e na validação

Depois é iterar: cada tela nova mostra qual regra faltou

até o próximo post! 😀