Por que o Copilot precisa do DESIGN.md

O Copilot funciona por contexto. Ele lê os arquivos abertos, os arquivos vizinhos e — no modo workspace — o projeto inteiro. Sem DESIGN.md, o modelo faz o melhor que pode com o que tem: copia padrões de outros arquivos do projeto, ou inventa baseado no treinamento genérico.

Com DESIGN.md na raiz, você dá ao Copilot:

Paleta de cores exata — em vez de bg-blue-500, ele usa bg-brand-primary ou o hex correto
Escala tipográfica — sabe que títulos usam Inter Bold 32px e corpo usa 16px/1.6
Regras de espaçamento — aplica 8px grid sem que você corrija depois
Padrões de componentes — estados de hover, focus e disabled documentados
Restrições — sabe o que NÃO fazer (gradientes proibidos, sombras limitadas, etc.)

O resultado: menos iterações de correção, menos “não era isso que eu queria”, menos tempo no code review ajustando visual.

Passo a Passo de Configuração

1. Coloque o DESIGN.md na raiz do projeto

O Copilot precisa encontrar o arquivo no workspace. A raiz é o lugar canônico:

meu-projeto/
├── DESIGN.md          ← aqui
├── .github/
│   └── copilot-instructions.md
├── src/
│   └── components/
├── package.json
└── ...

Se você ainda não tem um DESIGN.md, pegue um da biblioteca ou gere com a ferramenta de criação. O formato tem YAML front matter com tokens e prosa markdown com rationale:

colors:
  primary: "#1A73E8"
  secondary: "#34A853"
  surface: "#FFFFFF"
  background: "#F8F9FA"
  text-primary: "#202124"
  text-secondary: "#5F6368"
  error: "#D93025"
typography:
  font-family-heading: "Inter, sans-serif"
  font-family-body: "Inter, sans-serif"
  scale: [12, 14, 16, 20, 24, 32, 40, 48]
  line-height-body: 1.6
  line-height-heading: 1.2
spacing:
  base: 8
  scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]
border-radius:
  small: 4
  medium: 8
  large: 16
  pill: 9999

# Design System — MeuApp

## Filosofia

Interface limpa e funcional. Sem excesso de decoração. Hierarquia visual clara através de tamanho e peso tipográfico, não de cor. A cor é reservada para ações e estados.

## Componentes

### Botões

- **Primary**: fundo `primary`, texto branco, border-radius `medium`, padding 12px 24px
- **Secondary**: fundo transparente, borda 1px `primary`, texto `primary`
- **Ghost**: sem fundo, sem borda, texto `primary`, hover com background `background`

Estados: hover escurece 10%, disabled opacity 0.5, focus ring 2px offset.

### Cards

Fundo `surface`, border-radius `large`, padding 24px, shadow suave (0 1px 3px rgba(0,0,0,0.1)). Sem borda visível. Hover eleva shadow.

## Restrições

- Nunca usar gradientes em fundos
- Máximo 2 pesos tipográficos por página (regular + bold)
- Não usar outline em inputs — usar borda que muda de cor no focus
- Ícones: somente stroke, nunca filled

2. Criar o arquivo copilot-instructions.md

Este é o ponto chave. O GitHub Copilot lê automaticamente o arquivo .github/copilot-instructions.md como contexto adicional em toda interação. Crie o diretório se não existir:

mkdir -p .github

Conteúdo do .github/copilot-instructions.md:

# Instruções para o GitHub Copilot

## Design System

Este projeto usa DESIGN.md como source of truth para decisões visuais.

Antes de gerar qualquer componente de UI, formulário, página ou estilo:
1. Leia o arquivo DESIGN.md na raiz do projeto
2. Use exclusivamente as cores, tipografia e espaçamentos definidos lá
3. Siga os padrões de componentes documentados (botões, cards, inputs)
4. Respeite as restrições listadas na seção "Restrições"

### Regras obrigatórias

- Cores: usar apenas tokens do DESIGN.md, nunca valores hardcoded
- Tipografia: respeitar a escala definida, sem tamanhos inventados
- Espaçamento: usar múltiplos do base (8px)
- Componentes: seguir estados documentados (hover, focus, disabled)
- Nunca violar a seção de restrições

### Quando não houver definição

Se o DESIGN.md não cobrir um caso específico, perguntar antes de inventar.
Preferir consistência com os padrões existentes a decisões novas.

3. Usar o @workspace context no Chat

O Copilot Chat aceita referências explícitas com @workspace. Quando quiser gerar algo visual, use:

@workspace Crie um componente de navbar responsiva seguindo o DESIGN.md

O @workspace força o Copilot a indexar todo o projeto — incluindo o DESIGN.md — antes de responder. Sem ele, o Copilot pode ignorar arquivos que não estão abertos.

Para referências mais diretas:

@workspace #file:DESIGN.md Crie um formulário de contato com os tokens deste design system

O #file:DESIGN.md aponta explicitamente para o arquivo. Dupla garantia.

4. Fixar o DESIGN.md como contexto no Chat

No painel do Copilot Chat, você pode clicar no ícone de clip (anexar contexto) e adicionar o DESIGN.md como arquivo de referência. Ele permanece no contexto durante toda a conversa.

5. Usar no modo Copilot Edits (multi-file)

O Copilot Edits permite editar múltiplos arquivos simultaneamente. Ao iniciar uma sessão de edits, adicione o DESIGN.md como arquivo de contexto (read-only). Assim ele aplica os tokens em todos os arquivos que modificar:

Refatore todos os componentes em src/components/ para usar os tokens do DESIGN.md

Exemplo Concreto de Uso

Prompt no Copilot Chat:

@workspace #file:DESIGN.md

Crie um componente React de pricing card com:
- Plano nome e preço
- Lista de features com checkmarks
- Botão CTA primário
- Variante "popular" com destaque visual
- Responsive: stack em mobile, grid em desktop

O Copilot responde com código que referencia os tokens:

// src/components/PricingCard.tsx
interface PricingCardProps {
  name: string;
  price: string;
  period: string;
  features: string[];
  isPopular?: boolean;
  ctaText: string;
  onCtaClick: () => void;
}

export function PricingCard({
  name, price, period, features, isPopular, ctaText, onCtaClick
}: PricingCardProps) {
  return (
    <div
      className={`
        rounded-2xl p-6 bg-white
        shadow-sm hover:shadow-md transition-shadow
        ${isPopular ? 'ring-2 ring-[#1A73E8] scale-105' : ''}
      `}
    >
      {isPopular && (
        <span className="text-xs font-bold text-[#1A73E8] uppercase tracking-wide">
          Mais popular
        </span>
      )}
      <h3 className="text-2xl font-bold text-[#202124] mt-2">
        {name}
      </h3>
      <p className="mt-2">
        <span className="text-4xl font-bold text-[#202124]">{price}</span>
        <span className="text-sm text-[#5F6368]">/{period}</span>
      </p>
      <ul className="mt-6 space-y-3">
        {features.map((feature) => (
          <li key={feature} className="flex items-center gap-2 text-[#202124]">
            <CheckIcon className="w-5 h-5 text-[#34A853]" />
            <span className="text-sm">{feature}</span>
          </li>
        ))}
      </ul>
      <button
        onClick={onCtaClick}
        className="
          mt-8 w-full py-3 px-6
          bg-[#1A73E8] text-white font-medium
          rounded-lg hover:bg-[#1557B0]
          focus:ring-2 focus:ring-offset-2 focus:ring-[#1A73E8]
          disabled:opacity-50 transition-colors
        "
      >
        {ctaText}
      </button>
    </div>
  );
}

Repare: as cores #1A73E8, #34A853, #202124, #5F6368 vêm direto do DESIGN.md. O border-radius rounded-2xl corresponde ao large: 16. Os espaçamentos seguem múltiplos de 8. O botão tem os três estados (hover, focus, disabled) como documentado.

Dicas Específicas do GitHub Copilot

Use instruções no nível do workspace, não só no chat

O copilot-instructions.md é lido em TODA interação — inclusive nas sugestões inline (aquele fantasminha cinza). Se você tipifica um componente e começa a digitar, o Copilot já considera as instruções. Isso é mais poderoso que só usar no chat.

Prefira tokens semânticos no DESIGN.md

Em vez de:

colors:
  blue: "#1A73E8"

Use:

colors:
  primary: "#1A73E8"
  cta-background: "#1A73E8"

O Copilot entende melhor a intenção semântica. “Primary” e “cta-background” comunicam onde usar. “Blue” não diz nada sobre contexto.

Crie exemplos no DESIGN.md

A seção de componentes com exemplos concretos (código inline ou pseudo-código) ajuda o Copilot a gerar padrões consistentes. Quanto mais explícito, melhor:

### Input

```html
<input class="w-full px-4 py-3 border border-gray-300 rounded-lg 
       focus:border-primary focus:ring-1 focus:ring-primary
       text-sm text-text-primary placeholder:text-text-secondary" />


### Combine com .editorconfig e prettier

O DESIGN.md cuida do visual. Combine com ferramentas de formatação para garantir que o código gerado já sai no estilo do projeto. Menos ajustes manuais.

### VS Code settings para maximizar o contexto

No `.vscode/settings.json`:

```json
{
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": "DESIGN.md" }
  ]
}

Isso garante que o DESIGN.md é sempre incluído como instrução de geração de código no chat, mesmo sem @workspace.

Troubleshooting e Gotchas

O Copilot ignora o DESIGN.md nas sugestões inline

As sugestões inline (autocomplete) têm contexto limitado. O Copilot prioriza o arquivo aberto e vizinhos imediatos. Soluções:

Mantenha o DESIGN.md aberto em uma aba (mesmo que não visível)
Use o copilot-instructions.md — esse sempre é lido
Para componentes complexos, use o Chat em vez do autocomplete

Cores hardcoded em vez de variáveis CSS

O Copilot tende a usar hex direto se o DESIGN.md lista hex. Se preferir variáveis CSS, documente assim no DESIGN.md:

### Uso no código

Nunca usar hex direto. Usar variáveis CSS:
- `var(--color-primary)` em vez de `#1A73E8`
- `var(--color-surface)` em vez de `#FFFFFF`

O arquivo copilot-instructions.md não funciona

Verifique:

Está em .github/copilot-instructions.md (com o ponto antes de github)
O repositório está aberto como workspace (não como arquivo solto)
O Copilot Chat está na versão mais recente (Settings > Extensions > GitHub Copilot > Check for updates)

Conflito entre DESIGN.md e Tailwind config

Se você usa Tailwind e tem um tailwind.config.js com cores customizadas, o Copilot pode ficar confuso entre os dois. Resolva adicionando ao copilot-instructions.md:

## Framework CSS

Este projeto usa Tailwind CSS. Os tokens do DESIGN.md estão mapeados no tailwind.config.js.
Use as classes Tailwind customizadas (ex: `text-primary`, `bg-surface`) em vez de valores arbitrários.

Limites de contexto do workspace

Projetos muito grandes podem exceder o contexto do Copilot. Se o DESIGN.md não está sendo considerado:

Verifique se o arquivo tem menos de 5000 tokens (ideal: 1000-3000)
Mova detalhes granulares para arquivos separados e referencie no DESIGN.md
Mantenha o DESIGN.md conciso: tokens essenciais + rationale breve

Workspace Mode vs Inline: Quando Usar Cada

Cenário	Método
Criar componente novo	Chat com `@workspace #file:DESIGN.md`
Autocomplete dentro de componente existente	Inline (copilot-instructions.md cuida)
Refatorar visual de múltiplos arquivos	Copilot Edits com DESIGN.md como contexto
Revisar se código segue o design system	Chat: “este componente segue o DESIGN.md?”
Gerar testes visuais	Chat com referência ao DESIGN.md

Conclusão e Próximo Passo

O GitHub Copilot com DESIGN.md é a combinação mais acessível para times que já usam VS Code. Não exige ferramenta nova, não muda o workflow — só adiciona contexto onde antes não tinha.

Comece com o mínimo: um DESIGN.md na raiz e um copilot-instructions.md em .github/. Em duas horas de uso, você percebe a diferença. Os componentes saem mais consistentes, as correções diminuem, e o design system para de ser um PDF que ninguém consulta.

Próximos passos:

O que é DESIGN.md — especificação completa do formato
Biblioteca de DESIGN.md — 450+ design systems prontos
Guias de outros agentes: Cursor · Claude Code · Cline · Aider · Kiro

DESIGN.md + GitHub Copilot