Claude Code CLAUDE.md

DESIGN.md + Claude Code

Referência de configuração: Siga as regras visuais de @DESIGN.md

Pré-requisitos

  • Claude Code instalado (VS Code ou terminal)
  • Projeto com repositório Git inicializado
  • Um arquivo DESIGN.md — copie da biblioteca ou gere com a skill design-md

Configuração

1. Posicionar o DESIGN.md

Coloque o arquivo na raiz do projeto:

meu-projeto/
├── DESIGN.md
├── CLAUDE.md
├── src/
└── ...

2. Criar ou editar o CLAUDE.md

O CLAUDE.md é o arquivo de configuração que o Claude Code lê automaticamente. Adicione a referência ao DESIGN.md:

# CLAUDE.md

## Regras visuais
Siga estritamente as regras definidas em @DESIGN.md para toda geração de UI.
Não invente cores, fontes ou espaçamentos fora do design system.
Antes de gerar qualquer componente visual, leia @DESIGN.md por completo.

O prefixo @ indica ao Claude Code que deve ler o conteúdo do arquivo referenciado.

3. Verificar a configuração

Peça ao Claude Code para gerar um componente simples:

Crie um botão primário e um card seguindo o DESIGN.md

Confira se as cores, fontes e espaçamentos correspondem ao que está definido no DESIGN.md. Se o agente usou valores diferentes, revise o passo 2.

4. Refinar as instruções

Para resultados mais consistentes, seja específico no CLAUDE.md:

## Regras visuais
- Siga @DESIGN.md para toda geração de UI
- Use APENAS as cores definidas na seção Colors
- Respeite a escala de espaçamento da seção Spacing
- Aplique os padrões de componentes da seção Components
- Nunca viole as restrições da seção Do's and Don'ts

Troubleshooting

  • Agente ignorou o DESIGN.md — verifique se o arquivo está na raiz do projeto e se o CLAUDE.md usa @DESIGN.md (com o prefixo @). Sem o @, o Claude Code não lê o conteúdo do arquivo.
  • Cores parcialmente corretas — a seção Colors do DESIGN.md pode estar sem nomes semânticos ou regras de uso. Adicione contexto: brand-primary (#1A73E8): apenas para CTAs e links.
  • Componentes inconsistentes — adicione a seção Components no DESIGN.md com estados explícitos (hover, disabled, focus). Sem isso, o agente inventa estados diferentes a cada geração.
  • Agente esquece entre prompts — o Claude Code relê o CLAUDE.md a cada sessão, mas pode perder contexto em conversas longas. Reforce com “siga o DESIGN.md” quando necessário.

Combinações úteis

  • DESIGN.md + AGENTS.md — regras visuais + convenções de código. O AGENTS.md define padrões de código (naming, estrutura de pastas, linting), enquanto o DESIGN.md define padrões visuais. Juntos, cobrem toda a geração.
  • DESIGN.md + Do’s and Don’ts — a seção de restrições é o que mais impacta a consistência. LLMs respondem bem a instruções negativas — dizer o que não fazer é tão importante quanto dizer o que fazer.
  • Múltiplos DESIGN.md — para projetos com sub-apps ou temas, crie DESIGN.md separados e referencie o correto no CLAUDE.md por contexto.

Links úteis