DESIGN.md vs .cursorrules — Design system portável ou regras presas a uma ferramenta?

Comparação entre DESIGN.md e .cursorrules. Escopo, portabilidade entre ferramentas AI, e por que design tokens não pertencem a arquivo de configuração de IDE.

DESIGN.md.cursorrules

Veredito Rápido

.cursorrules é o arquivo de configuração de uma ferramenta específica (Cursor). DESIGN.md é um formato universal que qualquer AI coding agent lê. Colocar seu design system dentro do .cursorrules é como tatuar o endereço no braço porque funciona — até você se mudar. Se usa só Cursor e nunca vai trocar, tudo bem. Se quer portabilidade (e você vai querer — o mercado de AI editors muda todo mês), DESIGN.md é a resposta certa.

Tabela Comparativa

Dimensão DESIGN.md .cursorrules
Escopo Design system — tokens + rationale Tudo — código, estilo, preferências, design, workflow
Portabilidade Universal — funciona em qualquer AI tool Só Cursor (e forks que copiam o formato)
Formato YAML tokens + Markdown estruturado Markdown livre (texto puro sem schema)
Foco Especializado em design visual Generalista — cobre qualquer instrução
Parsabilidade Alta — YAML é machine-readable Média — texto livre, LLM interpreta livremente
Comunidade 24K stars, 461 design systems catalogados Milhares de exemplos, mas sem padronização
Manutenção Atualiza quando design muda Atualiza quando qualquer preferência muda
Tamanho típico 200-500 linhas (focado) 50-2000 linhas (tudo misturado)

O Problema com .cursorrules como Design System

O arquivo-valise

.cursorrules virou o lugar onde devs jogam tudo que querem que o Cursor saiba. O resultado típico:

# .cursorrules

## Stack
- Next.js 14 com App Router
- TypeScript strict
- Tailwind CSS v4
- Drizzle ORM com PostgreSQL

## Convenções de Código
- Use named exports
- Prefira composição sobre herança
- Componentes em PascalCase
- Utilities em camelCase

## Design System
- Cores: primary #1a1a2e, accent #e94560
- Fonte: Inter para body, Cal Sans para display
- Spacing: múltiplos de 4px
- Cards: rounded-xl, shadow-sm, border border-border
- Botões: rounded-lg, font-medium

## Estilo de Resposta
- Seja conciso
- Não explique o que é óbvio
- Use português nos comentários

## Regras de Git
- Commits convencionais: feat, fix, docs
- Branch naming: feature/xxx, fix/xxx

Parece organizado. Mas tem problemas estruturais:

  1. Tudo junto — design tokens, convenções de código, git, idioma, stack. Quando só o design muda, precisa editar o arquivo que contém tudo mais.

  2. Sem schema — “Cores: primary #1a1a2e” é texto que o LLM interpreta. Não é um valor estruturado. Um agente diferente pode parsear diferente.

  3. Preso ao Cursor — mudou pro Claude Code? Pro Windsurf? Pro Kiro? Leva o .cursorrules junto e… não funciona. Precisa adaptar pra .claude/settings, .windsurfrules, etc.

  4. Sem rationale — por quê múltiplos de 4px? Quando usar accent vs primary? Qual o contraste mínimo? Silêncio.

DESIGN.md em Detalhe

Especializado e estruturado

DESIGN.md tem um job claro: comunicar o design system em formato que máquinas parsam perfeitamente e humanos leem naturalmente.

---
name: "MeuProjeto Design System"
version: "2.1"
last-updated: "2026-06-15"
---

colors:
  brand:
    primary:
      value: "#1a1a2e"
      usage: "CTAs, links primários, textos de destaque"
      contrast-pair: "white ou primary-foreground"
    accent:
      value: "#e94560"
      usage: "Badges, notificações, elementos que pedem atenção imediata"
      constraint: "Nunca como background de áreas grandes — só pontos focais"

  neutral:
    50: { value: "#fafafa", usage: "Background de page" }
    100: { value: "#f4f4f5", usage: "Background de cards" }
    900: { value: "#18181b", usage: "Texto principal" }

typography:
  system:
    display:
      family: "Cal Sans"
      weights: [600, 700]
      usage: "Headers h1-h3, hero text"
      constraint: "Nunca em body text, nunca abaixo de 20px"
    body:
      family: "Inter"
      weights: [400, 500, 600]
      usage: "Parágrafos, labels, captions, UI text"

  scale:
    hero: { size: "3.5rem", line-height: 1.1, weight: 700 }
    h1: { size: "2.5rem", line-height: 1.2, weight: 700 }
    h2: { size: "2rem", line-height: 1.3, weight: 600 }
    body: { size: "1rem", line-height: 1.6, weight: 400 }
    small: { size: "0.875rem", line-height: 1.5, weight: 400 }

spacing:
  base-unit: "4px"
  component-internal: "8px–16px (2–4 units)"
  component-gap: "16px–24px (4–6 units)"
  section-gap: "64px–96px (16–24 units)"
  philosophy: "Espaço generoso. Na dúvida, mais espaço."

components:
  card:
    border-radius: "12px (rounded-xl)"
    shadow: "0 1px 3px rgba(0,0,0,0.05)"
    border: "1px solid var(--border)"
    padding: "24px"
  button:
    border-radius: "8px (rounded-lg)"
    padding: "12px 24px"
    font-weight: 500
    variants: [primary, secondary, ghost, destructive]

O que esse formato entrega que .cursorrules não entrega

  1. Schema implícito — YAML é parseável programaticamente. Tools podem validar, extrair, transformar.
  2. Constraints explícitas — “Nunca como background de áreas grandes” evita erros antes de acontecerem.
  3. Relações documentadas — contrast-pair diz com o que combinar.
  4. Versionado — sabe quando mudou e por quê.
  5. Portável — qualquer LLM lê YAML. Qualquer ferramenta de AI coding ingere.

.cursorrules em Detalhe

O que faz bem

É rápido de criar, sem cerimônia. Abre o arquivo, escreve instruções em texto livre, salva. Cursor lê automaticamente. Zero setup, zero schema pra seguir.

Para projetos pequenos com um dev usando exclusivamente Cursor, funciona perfeitamente. O investimento é mínimo e o retorno é imediato.

Quando basta

  • Projeto pessoal, 1 dev, só usa Cursor
  • Instruções simples: “use TypeScript strict, named exports”
  • Design system é o default do framework (sem customização pesada)
  • Não precisa de portabilidade entre ferramentas

Problemas em escala

Cenário: Time de 4 devs, cada um com ferramenta diferente

Dev 1 usa Cursor → .cursorrules Dev 2 usa Claude Code → CLAUDE.md Dev 3 usa Windsurf → .windsurfrules Dev 4 usa Copilot → .github/copilot-instructions.md

Se o design system está no .cursorrules, 3 dos 4 devs não recebem a informação. Resultado: inconsistência visual.

Com DESIGN.md: todos os 4 agentes leem o mesmo arquivo (cada ferramenta lê Markdown do repo como contexto). Design system unificado independente da ferramenta.

Cenário: Troca de ferramenta

Janeiro: time inteiro no Cursor. .cursorrules com 800 linhas incluindo design system completo. Março: metade migra pro Claude Code por causa do agentic mode. Resultado: precisa reescrever as instruções de design em outro formato, ou aceitar inconsistência.

Com DESIGN.md: troca de ferramenta não afeta o design system. Ele mora no repo, não na config da IDE.

A Separação Correta de Preocupações

Projeto/
├── DESIGN.md              ← Design system (portável, universal)
├── AGENTS.md              ← Comportamento geral do agente (portável)
│
├── .cursorrules           ← Preferências ESPECÍFICAS do Cursor
│   └── "Prefira respostas curtas. Use DESIGN.md para visual."
│
├── .claude/settings.json  ← Config ESPECÍFICA do Claude Code
├── .github/copilot-instructions.md  ← Config ESPECÍFICA do Copilot
│
└── src/

O padrão: DESIGN.md e AGENTS.md são universais. .cursorrules contém apenas o que é específico do Cursor como ferramenta — estilo de resposta, formato de output, atalhos.

Quando Usar Qual

Use .cursorrules sozinho quando:

  • Projeto pessoal, você é o único dev
  • Usa exclusivamente Cursor sem planos de mudar
  • Design system é trivial (5 cores, tipografia padrão)
  • Não precisa que outros devs ou ferramentas entendam o design

Use DESIGN.md (com ou sem .cursorrules) quando:

  • Time com múltiplas ferramentas AI — cada dev pode usar o que preferir
  • Portabilidade importa — não quer vendor lock-in em nenhuma IDE
  • Design system complexo — muitos tokens, regras, constraints
  • Projeto open-source — contribuidores usam ferramentas diversas
  • Projeto com longevidade — ferramentas vão mudar, design system persiste

Use ambos quando:

  • Maioria do time usa Cursor mas quer portabilidade
  • .cursorrules referencia DESIGN.md: “Para tokens e design, consulte DESIGN.md”
  • .cursorrules mantém apenas preferências tool-specific: formato de resposta, verbosidade

Migração: De .cursorrules para DESIGN.md

Se você já tem design tokens dentro do .cursorrules, a migração é simples:

Passo 1: Extraia tokens

Pegue tudo que é visual do .cursorrules: cores, fontes, espaçamento, componentes, constraints de design.

Passo 2: Estruture em YAML

Converta de texto livre pra YAML estruturado. Adicione usage e constraint pra cada token — o valor real que .cursorrules não tinha.

Passo 3: Adicione rationale

Por que essas cores? Por que esse espaçamento? O contexto que explica decisões é o que transforma config em design system.

Passo 4: Aponte .cursorrules pro DESIGN.md

# .cursorrules

## Design System
Consulte `DESIGN.md` para todos os tokens visuais, cores, tipografia e componentes.

## Preferências de Resposta
- Respostas concisas
- Código sem comentários óbvios
- TypeScript strict sempre

Resultado: .cursorrules fica leve e focado. DESIGN.md concentra design. Portabilidade garantida.

FAQ

Se eu uso só Cursor, qual a vantagem de ter DESIGN.md separado?

Três: (1) Organização — design tokens num arquivo focado vs misturado com tudo mais. (2) Parsabilidade — YAML é mais preciso que texto livre pro agente extrair valores. (3) Futuro-proof — quando (não se) mudar de ferramenta, o design system vem junto sem retrabalho.

.cursorrules é lido por outros AI agents?

Não nativamente. Claude Code lê CLAUDE.md. Windsurf lê .windsurfrules. Copilot lê .github/copilot-instructions.md. Cada ferramenta tem seu formato. DESIGN.md, por ser Markdown genérico no repo, é ingerido por todas como contexto do projeto.

Posso ter .cursorrules que include/referencia DESIGN.md?

Sim, e é o padrão recomendado. .cursorrules contém uma linha: “Para design visual, siga DESIGN.md”. O Cursor inclui DESIGN.md no contexto automaticamente quando referenciado (ou via @file).

DESIGN.md é reconhecido nativamente pelo Cursor?

Cursor lê qualquer arquivo Markdown do projeto como contexto quando referenciado. Não tem tratamento especial nativo como .cursorrules, mas funciona igual quando incluído no contexto (via @ mention ou rules que apontam pra ele). A vantagem é que também funciona em todas as outras ferramentas.

Existe ferramenta pra converter .cursorrules em DESIGN.md?

O designmd.app gera DESIGN.md a partir de projetos existentes — incluindo extração de tokens de configs e arquivos de regras. Mas o valor principal é adicionar semântica (usage, constraints, rationale) que nenhuma conversão automática captura sozinha.

Conclusão

.cursorrules é uma mala de mão. Prática, rápida de empacotar, boa pra viagens curtas. Mas se você muda de avião (ferramenta) no meio do caminho, precisa refazer a mala.

DESIGN.md é um container padronizado. Funciona em qualquer transporte. Qualquer ferramenta sabe como abrir e ler. O conteúdo chega intacto independente do veículo.

A escolha inteligente não é “um ou outro” — é separar preocupações. O design system pertence a um formato portável e universal. Preferências de ferramenta pertencem à config da ferramenta. Quando você separa essas camadas, trocar de editor ou adicionar uma ferramenta nova não requer reescrever o design system.

Em 2026, com novas ferramentas AI surgindo todo mês e nenhuma dominância clara de mercado, apostar toda sua documentação de design numa single tool é uma dívida técnica desnecessária. DESIGN.md é a apólice de seguro — e custa zero pra manter.

Os 461 design systems no designmd.app funcionam em Cursor, Claude Code, Copilot, Windsurf, Kiro, e qualquer ferramenta futura. Porque o formato é universal, não proprietário.