Como fazer o Claude Code respeitar o design system do projeto e parar de inventar componentes

Fala aí, beleza? Você pede um botão e vem um componente novo, com uma cor que não existe na paleta e um espaçamento que ninguém no time nunca usou

Aí você abre o arquivo e descobre um Button.tsx recém nascido morando do lado do Button que já existia há dois anos 😅

O problema aqui não é o modelo "não saber desenhar"

O problema é que o Claude Code não recebeu as convenções do seu repositório como instrução persistente

Ele não adivinha onde moram seus tokens, quais componentes já existem nem que criar peça nova é proibido sem conversa antes

Enquanto isso não estiver escrito em algum lugar que ele lê no começo da sessão, cada conversa começa do zero e o resultado vira sorte

Bora resolver isso?

O que você precisa antes de começar

Nada de PC da Nasa aqui, o setup é simples:

• Claude Code instalado e rodando no diretório do projeto
• um design system que exista de fato no código: tokens de cor, espaçamento e tipografia, mais uma biblioteca de componentes
• saber onde vive a pasta de UI, porque você vai escrever globs apontando pra ela

Esse terceiro item importa mais do que parece

O Claude Code procura os arquivos de memória subindo a árvore de diretórios a partir do diretório de trabalho atual, checando CLAUDE.md e CLAUDE.local.md em cada nível

Ou seja: abrir o terminal na raiz certa faz diferença

Se você abre o Claude Code dentro de apps/web/ e sua regra está na raiz do monorepo, tudo bem, ele sobe e acha

Agora se a regra está numa pasta irmã, fora do caminho que ele varre, ela simplesmente não entra na sessão e você fica achando que o modelo te ignorou

Se você ainda está montando o fluxo do primeiro projeto ao deploy, vale ajustar isso antes: memória bem posicionada resolve metade das dores de padrão

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo para o Claude Code respeitar seu design system

1. Rode /init uma vez no repositório

O /init faz o Claude ler a estrutura do projeto e escrever um CLAUDE.md com comandos de build, arquitetura e convenções

É o esqueleto, e você faz isso uma vez por repositório

O erro comum deste passo: rodar /init e achar que acabou

Ele mapeia o que consegue enxergar sozinho, mas a regra de "não invente componente" é decisão sua, não dedução dele

2. Escreva as regras de design no ./CLAUDE.md do projeto

Esse é o arquivo versionado no repo, então vale pra você e pra qualquer pessoa que clonar

Algo nessa linha já muda o jogo:

## Design system

- Tokens de cor, espaçamento e tipografia: `src/styles/tokens.ts`
- Componentes de UI existentes: `src/components/ui/`
- Antes de criar qualquer componente, procure o equivalente em `src/components/ui/` e reutilize
- Nunca escreva cor ou espaçamento na mão, sempre use o token
- Se realmente faltar uma peça, pare e pergunte antes de criar

Repare que não tem filosofia ali, só endereço e proibição

O erro comum deste passo: escrever um CLAUDE.md gigante

Os arquivos de memória são carregados por inteiro, não importa o tamanho, MAS arquivos mais curtos produzem melhor aderência às regras

Manifesto de design de 400 linhas não vira obediência, vira ruído

3. Separe o que é seu do que é do time

A memória tem escopos diferentes e cada um resolve uma coisa:

• ./CLAUDE.md: memória de projeto, versionada, vale pra quem clonar o repo
• ~/.claude/CLAUDE.md: memória de usuário, vale em todos os seus projetos
• e ainda existe o escopo gerenciado, de política da organização

Sua mania pessoal ("sempre me explique o diff antes") vai pro arquivo de usuário

A convenção de UI do produto vai pro arquivo do projeto

O erro comum deste passo: deixar a regra do time no arquivo pessoal e descobrir, semanas depois, que o resto da equipe nunca teve aquilo carregado

4. Mova a convenção pesada de UI pro .claude/rules/

Regras com escopo por caminho ficam em .claude/rules/

Uma regra sem o campo paths no frontmatter carrega no início da sessão, igualzinho ao CLAUDE.md

Já uma regra COM paths só carrega quando o Claude lê um arquivo que casa com o glob

---
paths: "src/components/**/*.tsx"
---

Nesta pasta:
- toda cor vem dos tokens, nada de hex escrito na mão
- todo espaçamento sai da escala definida, nada de valor solto
- componente novo só com aprovação explícita

O ganho é contexto: o carregamento condicional por glob só entra quando ele toca nos arquivos que casam com o padrão

Se você conhece aquele lint que só roda na pasta que importa, é a mesma ideia

O erro comum deste passo: glob errado

Se o padrão não casa com o arquivo que ele abriu, a regra não carrega e você jura que configurou tudo certo

5. Importe o doc de design com @caminho, se ele já existir

O CLAUDE.md pode importar outros arquivos com a sintaxe @caminho/do/arquivo

Útil quando o time já tem um documento de UI escrito e você não quer duplicar o conteúdo

As convenções visuais completas estão em @docs/ui-conventions.md

O erro comum deste passo: achar que importar economiza contexto

Não economiza

Os arquivos importados carregam no início da sessão do mesmo jeito, então importar um calhamaço tem o mesmo custo de colar o calhamaço

6. Empacote o fluxo repetido como skill

Quando "criar tela nova" sempre segue os mesmos passos, isso vira skill

Skills de projeto ficam em .claude/skills/<nome>/SKILL.md e são versionadas com o time

Skills pessoais ficam em ~/.claude/skills/<nome>/SKILL.md e valem em todos os projetos

Todo SKILL.md tem duas partes: frontmatter YAML entre os marcadores ---, com name e description dizendo QUANDO usar aquilo, e as instruções em Markdown

---
name: nova-tela
description: Use ao criar ou alterar telas e componentes de UI deste projeto
paths: "src/components/**"
---

1. Leia os tokens do projeto
2. Liste os componentes já existentes na pasta de UI
3. Monte a tela só com o que já existe
4. Se faltar peça, proponha alterar o componente existente antes de criar um novo

O campo paths também vale aqui: com ele, a skill carrega sozinha quando o Claude trabalha em arquivos que casam com o glob

O erro comum deste passo: description vaga

É ela que diz quando a skill deve entrar, então "regras de UI" ajuda menos do que "use ao criar ou alterar telas e componentes"

7. Confira com /memory o que entrou de verdade

Esse passo é o mais pulado e o mais útil

O /memory lista os arquivos de memória carregados na sessão (CLAUDE.md, CLAUDE.local.md e regras), deixa você abrir cada um e ainda liga ou desliga a auto memory

Antes de brigar com o modelo, olha ali e confirma que a sua regra está na lista

Já me ferrei uma vez por causa disso: regra linda, escrita no lugar errado, nunca carregada 🙂

8. Feche o ciclo com um hook depois das edições

O evento de hook PostToolUse com o matcher Edit|Write roda só depois das ferramentas que editam arquivo, e ele é configurado no .claude/settings.json

Aí você pluga o seu linter ali, aquele que já reclama de cor fora do token

Tome cuidado com a expectativa: um hook PostToolUse não desfaz a ação, porque a ferramenta já rodou

O que acontece é melhor do que parece: a saída do linter volta como texto que o Claude lê e pode corrigir

Ou seja, ele erra, o linter grita, ele conserta, tudo dentro do mesmo turno

Ele criou um componente novo sem necessidade: como reagir

Acontece

Sintoma: apareceu um Button.tsx novo em folha do lado do botão que já existia, com estilo próprio e nenhuma relação com os tokens

Causa provável: a instrução de reuso não estava carregada NAQUELE momento

Os suspeitos de sempre:

• regra com paths cujo glob não casou com o arquivo aberto
• CLAUDE.md longo demais, com a regra afogada no meio
• arquivo de memória fora da árvore que ele varre a partir do diretório atual

Solução imediata: aponte o componente existente pelo caminho e peça a troca, sem rodeio

Depois promova a correção a regra escrita

Correção que fica só no chat morre no fim da sessão, correção que vira linha no .claude/rules/ sobrevive

Como prevenir: modo plano

Ele é acionado com Shift+Tab, que cicla entre default, acceptEdits e plan, ou prefixando um único prompt com /plan

Nele o Claude lê arquivos, explora e escreve um plano sem editar o código fonte

E é justamente aí que a intenção de "vou criar um novo componente de botão" aparece escrita, enquanto ainda dá pra vetar

Isso vale ouro quando você está refatorando um projeto legado, onde inventar peça nova é o caminho mais fácil e o mais errado

A segunda camada é um subagente de revisão de UI

Subagentes customizados ficam em .claude/agents/ (projeto) e ~/.claude/agents/ (usuário), como arquivos Markdown com frontmatter

E tem a auto memory, que é o sistema complementar ao CLAUDE.md: são notas que o próprio Claude grava a partir das suas correções e preferências, carregadas no início da conversa

Então aquela bronca que você dá toda semana tende a virar nota

Se você prefere controlar isso na mão, o /memory liga ou desliga a auto memory

Design system fora do editor: o que vi no Claude Design

Tem um caminho diferente de "descrever o sistema em texto": levar o sistema pra uma canvas

O comando /design-sync é usado dentro do Claude Code pra importar o design system que vive no código (por exemplo uma biblioteca de componentes React) pro Claude Design, e também devolver o estado atual do código pra canvas

A sincronização vai nos dois sentidos, então não é só exportar e rezar

No Claude Design dá pra trazer o design system de um repositório GitHub, de arquivos de design, de uploads brutos ou do codebase local, e o Claude passa a construir com os componentes reais do sistema

A diferença conceitual é essa: em vez de você explicar o padrão por escrito, o padrão vira insumo

E fora do editor eu já testei um fluxo com essa mesma pegada de canvas, no Open Design

Clonei o repositório, entrei na pasta e segui os comandos que o próprio README indica, e digo com sinceridade: a documentação de lá explica bem o processo

Tomei um erro de permissão no terminal do VS Code durante a instalação, e o que funcionou na minha máquina foi abrir o terminal como administrador na pasta do projeto e repetir o comando

A instalação das dependências terminou com um warning, que eu avaliei como inofensivo pro uso da ferramenta

Depois de subir a versão web, a tela de setup detectou sozinha quais agentes eu já tinha instalados e ainda ofereceu a opção de usar API

Eu segui com o Claude Code mesmo

O que mais me chamou atenção: ao criar um projeto, dá pra escolher um design system inicial e o nível de fidelidade, de um frame simples até algo próximo da versão final, antes mesmo de escrever o prompt

Partir de um design system pronto evita ter que planejar tipografia e paleta do zero, e adianta MUITO o trabalho quando você quer se espelhar em uma marca de referência

Antes de gerar, a ferramenta fez uma entrevista curta comigo: superfície principal (desktop ou mobile), público, tom visual com limite de escolhas e direção visual

Na minha leitura é isso que reduz aquele resultado padronizado de IA que todo mundo já reconhece de longe

Detalhe prático: eu precisei escrever nas observações que o site deveria estar em português, porque na minha experiência essas ferramentas às vezes entregam em inglês

A tela mostra o consumo em tempo real, e como eu estava conectado pela assinatura o gasto saía da cota dela

ver esse número é bem mais útil quando você usa API

Durante a geração o agente continuou fazendo perguntas pontuais e foi anunciando as seções entregues até fechar a primeira versão

No fim eu abri o resultado no navegador: uma landing page funcional em HTML, com opção de ver o código, comentar e pedir alteração pontual

Dá pra exportar o código pra continuar o projeto na IDE ou publicar direto, e eu testei também a criação de uma apresentação, onde o fluxo de perguntas e a interface se repetem

No vídeo acima você vê o caminho inteiro rodando na minha máquina, do setup travado no erro de permissão até a página aberta no navegador

Onde cada mecanismo faz sentido

Não sai aplicando tudo de uma vez, beleza? Cada peça resolve um tipo de dor:

E agora a ressalva honesta, porque muita gente me pergunta isso

Existe o plugin frontend-design, instalado com /plugin install frontend-design@claude-plugins-official, do marketplace claude-plugins-official que é registrado automaticamente na primeira vez que você abre o Claude Code em modo interativo

O repositório oficial é o anthropics/claude-plugins-official

Só que a proposta declarada dele é gerar interfaces de frontend distintas e de nível de produção, pensando em tipografia, paleta e animação

Ou seja: ele é ótimo pra criar UI autoral, não pra impor o design system que JÁ existe no seu repositório

São problemas diferentes, e misturar os dois é receita de frustração

Conclusão

Aderência a design system no Claude Code é configuração, não sorte

O modelo não precisa de prompt mágico (dessas coisas toscas), ele precisa saber onde estão seus tokens, quais componentes existem e o que é proibido criar sem perguntar

Se você for fazer só uma coisa hoje, faça a menor delas:

1. rode /init no repositório
2. escreva cinco linhas de regra de design no ./CLAUDE.md
3. confira com /memory se elas entraram mesmo na sessão

Só depois disso evolua pras regras por paths, pra skill e pro hook

Começar pelo hook sem ter a convenção escrita é montar o alarme antes de ter a porta 😀

Faça o teste no seu projeto e compare a primeira tela que sair, a diferença aparece logo de cara

até o próximo post!