A versão de arquivo único e onde ela falha
O conselho inicial é sólido. O Cursor lê arquivos .cursor/rules/*.mdc, cada um com um frontmatter que controla quando é carregado — alwaysApply para regras que estão sempre no contexto, globs para regras que são ativadas quando arquivos correspondentes estão em uso. Um único design.mdc com alwaysApply: true resolve boa parte dos problemas.
Então, três coisas acontecem, nesta ordem.
- 1
O arquivo cresce
Toda vez que o agente faz algo errado, alguém adiciona uma linha. Seis meses depois, são quatrocentas linhas cobrindo cor, tipografia, espaçamento, animação, acessibilidade, padrões de formulário, estados vazios e um parágrafo sobre tom de voz. Ele está sempre no contexto, competindo com a tarefa real pela atenção, e a adesão a qualquer linha individual caiu.
- 2
As regras começam a se contradizer
"Use espaçamento generoso" foi escrito para o site de marketing. "Mantenha as tabelas densas" foi escrito para o dashboard. Ambos estão no mesmo arquivo sempre ativo, portanto, ambos são verdadeiros em todos os lugares, o que significa que nenhum dos dois é, de fato, uma regra.
- 3
Alguém define um escopo para corrigir isso, e a regra para de disparar
A correção óbvia é
globs: components/**. Então, o agente escreve um novo layout de página emapp/, nenhuma regra de design é ativada e o resultado é genérico. Novos layouts são exatamente onde as orientações de design mais importam e exatamente o que um glob de componentes ignora.
O passo três é a autolesão mais comum em configurações de design no Cursor. Uma regra de design que se anexa apenas a arquivos de componentes fica desligada durante a criação de páginas, que é onde as decisões de composição, hierarquia e espaçamento realmente acontecem.
Divida por quando é verdade, não sobre o que se trata
O instinto é dividir por tópico — colors.mdc, typography.mdc, spacing.mdc. Esse é o eixo errado. Esses três são verdadeiros ao mesmo tempo, então dividi-los não muda nada, exceto a quantidade de arquivos que você precisa manter.
Divida pelo escopo de verdade. A pergunta para cada regra é: quando isso é falso? Se a resposta for "nunca", pertence ao arquivo sempre ativo. Se a resposta for "no dashboard", pertence a uma regra com escopo definido, e sua contraparte pertence a outra.
| Dividir por tópico | Dividir por escopo de verdade | |
|---|---|---|
| Arquivos | cores, tipografia, espaçamento, movimento | design (sempre), superfícies de marketing, superfícies densas |
| Quando são carregados | Tudo de uma vez — compartilham o mesmo escopo | Apenas onde se aplicam |
| Contradições | Ainda juntos no contexto, ainda se anulando | Nunca copresentes, permitindo que cada um seja absoluto |
| Peso 'always-on' | Tudo, sempre | Apenas os inegociáveis |
Esta é a mesma estrutura que grandes design systems alcançam independentemente — o Encore do Spotify é uma fundação com subsistemas especializados acima dela; o Carbon é um núcleo com camadas de domínio. Um diretório de regras é uma versão reduzida da mesma ideia, e falha da mesma forma quando a fundação absorve coisas que deveriam ser locais.
O que colocar na regra always-on
Mantenha-a em apenas uma tela. O papel dela não é conter o design system — o design system vive no DESIGN.md e no seu arquivo de tokens. O papel dela é fazer com que o agente leia esses arquivos e manter o punhado de restrições que nunca devem ser violadas em lugar nenhum.
---
description: Design system policy for all UI work
alwaysApply: true
---
Before writing or editing any UI, read DESIGN.md at the repo root.
## Non-negotiable
- Never write a literal colour value. No hex, no rgb(), no named
CSS colours. Use the semantic tokens in DESIGN.md.
- Never introduce a font family that is not in DESIGN.md.
- Every spacing value comes from the scale. Any other value is a bug.
- Every interactive element has a visible focus state.
- Anything with a light-mode colour has a dark-mode counterpart.
## When unsure
Match the nearest existing component in this repo rather than
inventing a new pattern. If no similar component exists, say so
before writing one.Cada linha ali é uma restrição que pode ser violada e verificada. Nenhuma delas descreve uma estética. Isso é deliberado, e é a maior diferença entre um arquivo de regras que altera o resultado e um que não altera.
A última seção é subestimada. "Corresponda ao componente existente mais próximo e, se nenhum existir, informe isso antes de criar um" converte a falha mais comum do agente — inventar silenciosamente um novo padrão — em uma pergunta. Esse único parágrafo evita mais desvios do que uma página de descrição visual.
Por que proibições, especificamente
Analisamos 299 arquivos DESIGN.md públicos — o mesmo gênero de artefato que um arquivo de regras de design, escrito para a mesma finalidade — e medimos o que eles contêm, em vez do que alegam conter.
| Proporção de arquivos | |
|---|---|
| Nenhuma proibição de qualquer tipo | 76% |
| Cores como hex puro, sem papel semântico | 86% |
| Nenhuma definição de dark mode | 69% |
| Nenhum motivo distintivo | 57% |
| Pelo menos um adjetivo vago fazendo o trabalho | 54% |
| Nenhum valor de tamanho concreto em lugar nenhum | 44% |
O número de proibições é o ponto importante. Três quartos desses arquivos dizem ao modelo apenas o que é permitido, o que deixa todo o resto permitido por padrão — e todo o resto é a maior parte de uma interface.
Considere a diferença concretamente. "Use --color-primary para ações primárias" é satisfeito por uma página que também usa a cor primária para cabeçalhos, links, preenchimentos de ícones, bordas e gradientes. Adicione "nunca use a cor de destaque para texto, bordas, fundos ou gradientes" e a mesma frase agora produz uma interface contida. A permissão não mudou. A proibição fez todo o trabalho.
Uma regra que diz apenas o que é permitido deixa todo o resto permitido. E todo o resto é a maior parte da interface.
O dado sobre adjetivos vagos agrava a situação. "Clean" aparece em 39% desses arquivos e "modern" em 36%. Um modelo a quem se pede algo clean e modern produz o centro estatístico de seus dados de treinamento, que é precisamente por que interfaces geradas por IA convergem para o mesmo visual. Nenhuma das palavras exclui nada.
As regras com escopo
Uma vez que a regra always-on contenha apenas os universais, as regras específicas de superfície podem ser absolutas em vez de cautelosas. Dois exemplos, mostrando a estrutura:
---
description: Marketing and landing surfaces
globs: app/(marketing)/**, app/page.tsx, components/marketing/**
---
Spacing runs one step above the app scale. Sections breathe.
Display type (48px+) is allowed here and nowhere else.
Cards may use shadow elevation.
One primary call to action per section. Never two competing buttons.---
description: Dense application surfaces — tables, dashboards, settings
globs: app/(app)/**, components/table/**, components/dashboard/**
---
Compact spacing: controls 8-12px padding, table rows 32px.
Elevation is a surface step plus a 1px border. Never a shadow.
Type stays at body scale and below. No display type.
Status colours (success, warning, danger) are reserved for status.
Nothing decorative uses them.Nenhuma delas contém ressalvas, porque nenhuma delas está no contexto junto com a outra. Esse é todo o benefício da divisão.
Verifique seus globs contra a realidade antes de confiar neles. Grupos de rotas, prefixos src/ e diretórios de componentes colocalizados quebram padrões ingênuos, e um glob que não corresponde a nada falha silenciosamente — você recebe um resultado genérico e nenhuma indicação do porquê. Abra um arquivo na superfície e confirme que a regra foi anexada.
O que as regras não devem conter
Três coisas são colocadas em arquivos de regras que pertencem a outro lugar, e cada uma tem um custo.
| Por que falha ali | Onde pertence | |
|---|---|---|
| A lista completa de tokens | Duplica o arquivo de tokens. Os dois divergem e agora o agente tem duas fontes conflitantes | Seu arquivo CSS ou de tema, referenciado a partir do DESIGN.md |
| Documentação da API de componentes | Grande demais para o contexto sempre ativo e desatualizado na próxima versão | Um servidor MCP, consultado sob demanda |
| Descrição estética | "Sofisticado, minimalista, premium" não impõe restrição alguma e consome contexto | Em lugar nenhum. Substitua pelas restrições que produzem essa impressão |
O problema da duplicação na primeira linha merece atenção. Assim que um valor hex aparece tanto no arquivo de regras quanto no arquivo de tokens, um deles será atualizado e o outro não, e o agente usará confiantemente a versão desatualizada. As regras devem apontar para a fonte da verdade, nunca reafirmá-la.
A camada abaixo das regras
Tudo isso assume que existe algo que valha a pena referenciar. Um arquivo de regras que diz "leia o DESIGN.md" é tão bom quanto o próprio DESIGN.md, e os dados do corpus mostram que a maioria desses arquivos é apenas uma paleta com adjetivos anexados.
O que faz a diferença é a mesma lista de sempre: cores como papéis semânticos em vez de valores hex, uma escala tipográfica com números reais, uma escala de espaçamento, um modo escuro definido em vez de derivado, motivos que declaram o que o design faz e uma lista explícita do que é proibido. Documente isso e o arquivo de regras se tornará curto, pois a maior parte dele será apenas um ponteiro.
Os design kits do Identity Forge entregam exatamente essa estrutura e a serializam em um DESIGN.md. Instale um em um projeto Cursor com npx --yes identityforge@latest install --client cursor ou navegue pelos kits primeiro. O guia de design system para Cursor explica como configurar o servidor MCP junto com ele.
Um conjunto funcional
Para a maioria dos projetos, quatro arquivos é o número ideal; mais do que isso é um sinal de alerta:
design.mdc—alwaysApply: true. Uma tela. Aponta para oDESIGN.md, contém as proibições que valem para tudo e instrui o agente a perguntar antes de inventar um padrão.surface-marketing.mdc— escopo de glob. As regras que só valem onde o leitor faz uma varredura rápida de segundos.surface-app.mdc— escopo de glob. As regras que só valem onde o usuário passa o dia todo.a11y.mdc—alwaysApply: truese sua equipe precisar que isso seja declarado separadamente. Estados de foco, contrastes mínimos, elementos semânticos, requisitos de labels.
Se você sentir vontade de criar um quinto arquivo, verifique se ele é realmente um novo escopo de verdade ou um tópico que pertence a um já existente. Tópicos se multiplicam infinitamente; escopos não.
Onde ficam as regras do Cursor?
Em .cursor/rules/ como arquivos .mdc, cada um com um frontmatter que controla quando é carregado. alwaysApply: true mantém uma regra no contexto de cada requisição; globs anexa uma regra quando arquivos correspondentes estão envolvidos. Uma regra de design que deve ser aplicada durante a autoria de páginas precisa estar sempre ativa, e não com escopo de glob para componentes.
Meu design system deve ficar em uma regra do Cursor ou no DESIGN.md?
No DESIGN.md, com a regra apontando para ele. Manter o sistema em um arquivo versionável e agnóstico a ferramentas significa que a mesma definição serve para o Cursor, Claude Code, um servidor MCP e qualquer humano que leia o repo. Duplicar valores de tokens no arquivo de regras garante que as duas cópias diverjam.
Qual deve ser o tamanho de uma regra de design do Cursor?
Uma regra sempre ativa deve caber em uma tela. Além disso, ela competirá com a tarefa real pela atenção do modelo, e a adesão a qualquer linha individual cairá. Se ela estiver crescendo, isso é um sinal para mover o conteúdo para o DESIGN.md ou para uma regra com escopo, não um sinal para continuar adicionando.
Por que o agente ignora minhas regras de design?
Três causas comuns: a regra tem escopo de glob e não está sendo anexada (verifique os caminhos reais dos arquivos), a regra descreve uma estética em vez de declarar restrições que podem ser violadas, ou o arquivo sempre ativo cresceu tanto que nenhuma linha se destaca. Proibições em um arquivo curto são seguidas com muito mais confiabilidade do que descrições em um arquivo longo.
Posso usar .cursorrules em vez disso?
A abordagem de arquivo único .cursorrules ainda funciona, mas não oferece carregamento condicional, então cada regra está sempre ativa e o problema das contradições surge mais rápido. O diretório .cursor/rules/ existe precisamente para permitir que diferentes regras sejam aplicadas em diferentes lugares, que é a estrutura de que um design system precisa.