Cursor Rules vs DESIGN.md — O Que Vai Onde?

Você configura seu .cursorrules. O agente passa a seguir suas convenções de código, nomes corretos, patterns do jeito que você gosta. Aí alguém menciona DESIGN.md. Você abre o arquivo e pensa: “Peraí — isso não é o que meu cursor rules já faz?”

Não. Resolvem problemas diferentes. E a confusão entre os dois te custa inconsistência visual ou um arquivo de rules inchado tentando ser tudo ao mesmo tempo.

A divisão limpa é essa.

O Que .cursorrules Faz de Verdade

Seu .cursorrules (ou .cursor/rules/*.mdc) diz pro agente como se comportar. É comportamental. Pensa nele como a personalidade e hábitos de trabalho do agente.

O que pertence ali:

• Code style — “Use TypeScript strict mode,” “Prefira named exports,” “Nada de default exports”
• Patterns — “Use server actions para mutations,” “Toda chamada de API passa por /lib/api”
• Tom — “Commit messages curtas,” “Comentários explicam o porquê, não o quê”
• Guardrails — “Nunca modifique package.json sem perguntar,” “Não delete arquivos de teste”
• Arquitetura — “Siga feature-folder pattern,” “Cada rota é um diretório com page.tsx + layout.tsx”

Percebe o padrão? Tudo sobre comportamento. Como o agente escreve código. Que convenções segue. Onde coloca as coisas.

Um bom .cursorrules faz o agente codar igual a você. Ele não diz pro agente como são seus botões.

O Que DESIGN.md Faz

DESIGN.md diz pro agente o que desenhar. É um documento de referência. Pensa nele como o design system que o agente consulta antes de mexer em qualquer UI.

O que pertence ali:

• Color tokens — primary, surface, accent, cores semânticas com hex exato
• Tipografia — font families, escala de tamanhos, mapeamento de weights
• Spacing — seu grid system, valores de padding/margin
• Component specs — “Cards usam 1px border, 12px radius, 24px padding”
• Regras visuais — “Nunca misture cantos retos e arredondados,” “Máximo 3 font sizes por página”
• Do’s and Don’ts — restrições visuais específicas da sua marca

Percebe esse padrão? Tudo visual. Tudo sobre como o output deve parecer. Nada sobre como o agente chega lá.

Um bom DESIGN.md faz cada componente gerado parecer que pertence ao seu app. Independente de qual agente gerou.

A Divisão Arquitetural

O modelo mental que faz isso clicar:

	.cursorrules	DESIGN.md
Controla	Comportamento do agente	Output visual
Responde	”Como devo escrever código?"	"Como isso deve parecer?”
Muda quando	Seu workflow muda	Seu design muda
Escopo	Toda geração de código	Só geração de UI
Portável	Não (específico do Cursor)	Sim (qualquer agente lê)

Última linha é crucial. Seu .cursorrules é preso ao Cursor. Migra pro Claude Code amanhã e ele vira peso morto — você precisa de um CLAUDE.md. Mas DESIGN.md funciona em qualquer lugar. Claude Code, Kiro, Windsurf, Copilot — todos leem Markdown. Um arquivo, todo agente.

A separação também é sobre frequência de mudança. Suas cursor rules estabilizam rápido — uma vez que você acerta suas preferências, mal mudam. Seu design system evolui o tempo todo. Novos componentes, cores atualizadas, spacing ajustado. Separar significa que atualizar um não arrisca quebrar o outro.

O Setup Prático

Um projeto bem estruturado fica assim:

meu-projeto/
├── DESIGN.md                    ← Sistema visual (portável)
├── .cursor/
│   └── rules/
│       ├── general.mdc          ← Comportamento de código
│       └── design-system.mdc    ← Ponte (aponta pro DESIGN.md)
├── src/
└── ...

Seu design-system.mdc é a ponte entre os dois mundos:

---
description: Design system enforcement
globs: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.css"]
---

Antes de gerar qualquer componente visual, leia @DESIGN.md e siga exatamente.

- Use APENAS cores dos tokens do DESIGN.md
- Siga a escala tipográfica — nada de tamanhos inventados
- Aplique spacing do grid definido
- Siga os patterns de componentes da seção Components
- Nunca viole a seção Do's and Don'ts

Aquele @DESIGN.md é a chave. A cursor rule não contém decisões de design — ela delega pro arquivo de design system. A rule diz “siga o spec visual.” O spec diz qual é o spec visual.

Seu general.mdc fica limpo e focado em comportamento:

---
description: Convenções de código
globs: ["**/*.{ts,tsx}"]
---

- TypeScript strict mode, sem `any`
- Só named exports
- Server components por padrão, 'use client' só quando necessário
- Testes colocados junto: `coisa.test.ts` ao lado de `coisa.ts`

Zero cores. Zero font sizes. Zero tokens visuais poluindo suas rules de código.

Por Que Isso Importa

Já vi .cursorrules com 400 linhas. Metade é design system enfiado lá dentro: hex codes, valores de spacing, descrições de componentes. Funciona — tecnicamente. Mas é frágil.

Problemas de enfiar tudo nas cursor rules:

1. Não é portável. Troca de editor e perde todo o contexto visual.
2. Contexto inchado. Todo prompt carrega todas as rules. Sua rota de API backend não precisa saber o border-radius do botão.
3. Difícil de manter. Design tokens mudam frequentemente. Cavar por rules comportamentais pra achar um valor de cor é chato.
4. Não compartilha. Um .cursorrules é pessoal. Um DESIGN.md pode ser compartilhado entre repos, ferramentas e time inteiro.

O campo globs no .cursor/rules/ já te dá a solução. Rules de design só carregam pra arquivos de UI. Arquivos backend nunca veem elas. Mas o conteúdo do design mora no DESIGN.md onde qualquer ferramenta acessa.

Começando

Se você já usa .cursorrules e quer adicionar DESIGN.md:

1. Extraia as regras visuais das suas cursor rules pra um DESIGN.md. Cores, fontes, spacing, patterns de componentes — tira tudo de lá.
2. Pegue um DESIGN.md da library se tá começando do zero, ou crie o seu.
3. Adicione uma rule ponte que diz pro Cursor ler o DESIGN.md pra trabalho de UI.
4. Siga o guia completo de setup pro Cursor pra glob patterns, patterns avançados e troubleshooting.

A migração leva 15 minutos. Suas cursor rules ficam menores e mais focadas. Seu design system vira portável. Todo componente de UI fica consistente.

A Versão de Uma Frase

.cursorrules define como seu agente pensa — DESIGN.md define o que ele enxerga.

Use os dois.