Windsurf .windsurfrules

DESIGN.md + Windsurf

Referência de configuração: Referenciar DESIGN.md

Pré-requisitos

  • Windsurf instalado e configurado
  • 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
├── .windsurfrules
├── src/
└── ...

2. Criar o .windsurfrules

O .windsurfrules é o arquivo de configuração que o Windsurf lê automaticamente. Crie na raiz do projeto:

# .windsurfrules

## Regras visuais
Leia o arquivo DESIGN.md na raiz do projeto antes de gerar qualquer componente visual.
Siga estritamente as regras definidas no DESIGN.md para cores, tipografia, espaçamento e componentes.

Regras específicas:
- Use APENAS as cores da seção Colors do DESIGN.md
- Siga a escala tipográfica da seção Typography
- Respeite o espaçamento da seção Spacing
- Aplique os padrões de componentes com todos os estados (hover, disabled, focus)
- Nunca viole as restrições da seção Do's and Don'ts

3. Verificar a configuração

Peça ao Windsurf para gerar um componente:

Crie uma navbar responsiva seguindo o design system do projeto

O Windsurf deve ler o .windsurfrules, que aponta para o DESIGN.md, e aplicar as regras visuais definidas.

4. Refinar com contexto de framework

Adicione instruções específicas do framework no .windsurfrules:

## Framework
Este projeto usa React + Tailwind CSS.
Ao gerar componentes, use classes Tailwind que correspondam aos valores do DESIGN.md.
Exemplo: se o DESIGN.md define spacing base 4px, use classes como p-1, p-2, p-4.

Troubleshooting

  • Windsurf não lê o .windsurfrules — verifique se o arquivo está na raiz do projeto (não dentro de uma subpasta). O nome deve ser exatamente .windsurfrules (com ponto no início).
  • Regras visuais ignoradas — o Windsurf pode priorizar o contexto do prompt sobre o .windsurfrules. Reforce no prompt: “siga o DESIGN.md do projeto”.
  • Cores ou espaçamentos incorretos — verifique se o DESIGN.md tem valores concretos (hex, px, rem) e não apenas descrições vagas. O agente precisa de números, não de “fonte grande”.
  • Inconsistência entre sessões — o Windsurf relê o .windsurfrules a cada sessão. Se as regras mudam, a próxima sessão já usa a versão atualizada.

Combinações úteis

  • DESIGN.md + .windsurfrules detalhado — use o .windsurfrules para instruções gerais do projeto (framework, convenções, estrutura) e o DESIGN.md para regras visuais específicas. Separe responsabilidades.
  • Seção Do’s and Don’ts — esta é a seção mais impactante para o Windsurf. Restrições explícitas (“não use sombras em mais de 2 níveis”) previnem os padrões genéricos que o agente tende a gerar.
  • DESIGN.md + variáveis CSS — se o projeto usa CSS custom properties, alinhe os nomes do DESIGN.md com as variáveis: --color-primary no CSS corresponde a brand-primary no DESIGN.md. O agente faz a conexão automaticamente.

Links úteis