Skill /design-md pro Claude Code

O problema

Rode isto no seu projeto:

grep -rhoE "#[0-9a-fA-F]{3,6}" --include="*.css" --include="*.tsx" . | sort -u | wc -l

Se voltar um número acima de vinte, você não tem um design system. Tem um histórico de
decisões tomadas às pressas, uma por tela, cada uma por uma pessoa ou por um agente diferente.

É assim que acontece: você pede uma tela, o agente olha o código, encontra três padrões, e
escolhe um. Amanhã escolhe outro. Ninguém pega na revisão, porque cada diff isolado parece
razoável. Seis meses depois existem onze azuis, quatro escalas de espaçamento e três jeitos de
arredondar um canto, e "deixar a interface consistente" virou um projeto de duas semanas que
ninguém quer pegar.

O agente não é desatento. É que a identidade visual do seu projeto não está escrita em lugar
nenhum que ele leia.

O que a skill faz

Ela produz o arquivo que o agente lê antes de escrever qualquer interface, e o coloca no lugar
certo pra que ele seja de fato lido.

O caminho, do jeito que ela conduz:

• Descobre antes de perguntar. Varre o repositório e te mostra quantos valores de cor você
  tem de verdade. É esse número que costuma justificar o trabalho.
• Extrai de onde a identidade já existe, seja o CSS do seu site no ar, a referência que
  você admira ou os tokens que já estão no código.
• Pergunta só o que não deu pra descobrir. São quatro perguntas, não um questionário.
• Escreve o arquivo e o valida, inclusive contraste de texto.
• Amarra no contexto do agente. É o passo que quase todo mundo pula, e sem ele nada muda:
  arquivo que o agente não lê é documento bonito e inútil.

E cobre a manutenção, que é onde esse tipo de arquivo costuma morrer: auditar o que já existe,
achar o token que ninguém usa e comparar versões antes de aprovar mudança grande.

O que vem no pacote

Dois arquivos em Markdown:

1. SKILL.md — a skill. Copia pra dentro do projeto e roda; não tem nada pra preencher.
2. LEIA-ME — instalação em 3 passos, requisitos, e um exemplo de ponta a ponta.

Nenhuma dependência de framework: serve a Tailwind, CSS puro, styled-components ou o que você
usar.

Sobre o formato

O arquivo que a skill escreve segue o DESIGN.md, especificação aberta do Google Labs
sob licença Apache 2.0. Ela tem validador próprio, e a skill usa: contraste abaixo do mínimo,
referência quebrada e token órfão são apontados antes de você considerar o arquivo pronto.

O que você recebe aqui é a skill, não o formato. O formato é público e de terceiro; nenhum
código dele é redistribuído. O que a especificação não faz por você é justamente o trabalho:
descobrir qual é a sua identidade, decidir o que vira token, escrever as proibições que mudam
o comportamento do agente, e fazer o arquivo ser lido. É isso que está aqui.

O que ela NÃO faz

Não desenha a sua marca. Se não existe identidade nenhuma e nenhuma referência, ela para e
pergunta: inventar paleta é decisão de negócio, não de código.

Não escreve o CSS das suas telas nem migra o código atual para os tokens novos. Ela produz
o contrato; aplicar é trabalho seguinte.

Não é garantia de consistência. Reduz a variação e dá onde apoiar a revisão; não substitui
o julgamento de quem revisa.

E a especificação está em versão alpha: ela muda, e a skill diz explicitamente que o
repositório oficial é quem manda quando houver divergência.

Pra quem é

Quem tem um projeto com interface e usa agente pra escrever tela. Se você está começando, é o
jeito mais barato de já nascer com um sistema em vez de arrumar depois. Se o projeto já é
grande e inconsistente, é o caminho pra parar de crescer errado, sem precisar refatorar tudo
antes.

Se o seu projeto não tem interface, ou se você já mantém um design system com tokens
versionados e um processo que funciona, isto não vai te acrescentar.

É de graça: pega, usa, e se prestar você volta.