Design Tokens vs DESIGN.md — Complementam ou Competem?

Você já tem um tokens.json. Figma Variables configuradas. A spec do W3C Design Tokens finalmente estabilizou. Seu build pipeline transforma tokens em CSS custom properties, config do Tailwind, arquivos platform-specific. Tudo funciona.

Aí alguém menciona DESIGN.md e a primeira pergunta é sempre: “Mas eu já não tenho isso resolvido?”

Resposta curta: não. Design tokens e DESIGN.md resolvem problemas fundamentalmente diferentes. Um fala com máquinas que compilam código. O outro fala com máquinas que escrevem código. Essa distinção importa mais em 2026 do que importava há um ano.

O Que Design Tokens Realmente São

O W3C Design Tokens Community Group passou anos definindo um formato padrão de intercâmbio. O resultado: uma estrutura JSON que descreve decisões de design atômicas — cores, espaçamento, tipografia, sombras, bordas. Valores crus com nomes.

{
  "color": {
    "primary": {
      "$value": "#2563eb",
      "$type": "color"
    },
    "surface": {
      "$value": "#ffffff",
      "$type": "color"
    }
  },
  "spacing": {
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}

Figma Variables implementam esse conceito nativamente. Você define tokens no Figma, exporta via plugin ou API, e ferramentas como Style Dictionary, Tokens Studio ou a Figma REST API empurram tudo por um build pipeline até formatos platform-specific.

Isso é infraestrutura. Tokens são o quê — os valores crus que seu sistema usa. Não explicam por que esses valores existem, quando usar cada um, nem como eles se combinam.

O Que DESIGN.md Adiciona

DESIGN.md é um arquivo Markdown com YAML frontmatter que fica na raiz do seu repositório. Descreve seu design system num formato otimizado pra context window de LLMs. Não só valores — regras, semântica, constraints, padrões de componentes e do’s/don’ts explícitos.

Isso aqui tokens não conseguem expressar:

• “Cards nunca usam drop shadow, só 1px border”
• “Nunca combinar mais de 2 font weights na mesma página”
• “Botão primary é reservado pra ação mais importante da tela — uma só”
• “Usa surface pra background de cards, nunca background”
• “Spacing segue grid de 8px — sem exceção, sem hack de 12px”

São essas regras que fazem um design system parecer coerente. Um designer humano guarda na cabeça. Um AI agent precisa delas escritas explicitamente, toda vez, porque não tem memória entre prompts.

DESIGN.md empacota os valores dos tokens e as regras semânticas num arquivo só que cabe na context window junto com seu código. É a diferença entre dar uma caixa de LEGO pra alguém versus dar a caixa mais o manual de instruções.

Veja o que é DESIGN.md pro breakdown completo da spec.

A Comparação Que Importa

Aspecto	Design Tokens (W3C/Figma)	DESIGN.md
Formato	JSON (spec W3C)	Markdown + YAML frontmatter
Consumidor principal	Build tools (Style Dictionary, compilers)	AI agents (Claude, Cursor, Kiro)
Contém valores	✅ Todos os valores atômicos	✅ Valores-chave (subconjunto)
Contém regras	❌ Sem regras semânticas	✅ Do’s, don’ts, padrões de componentes
Build pipeline	✅ Transforma em CSS/Swift/Kotlin	❌ Não é compilado — lido no prompt
LLM-readable	⚠️ Parseável mas sem contexto	✅ Projetado pra context windows
Versionável	✅ JSON no Git	✅ Markdown no Git
Output multi-plataforma	✅ (é pra isso que existe)	❌ (não é o trabalho dele)
Explica intenção	❌ Só valores	✅ Por quê, quando, como
Padrões de componentes	❌ Nível de token só	✅ Specs completas de componentes
Cabe na context window	⚠️ Arquivos grandes estouram	✅ Projetado pra ser compacto

O que importa de verdade: design tokens alimentam seu build system. DESIGN.md alimenta seu AI collaborator. Um roda em compile time. O outro roda em generation time.

Quando Usar Cada Um (e Quando Usar os Dois)

Tokens sozinhos funcionam quando:

• Você tem uma component library madura já construída
• Devs copiam componentes existentes, sem geração via IA
• Seu pipeline precisa de output multi-plataforma (web + iOS + Android)
• O time é grande o suficiente pro Figma ser a single source of truth

DESIGN.md sozinho funciona quando:

• Você constrói rápido com AI agents como implementadores principais
• O projeto é pequeno o suficiente pra não precisar de pipelines Style Dictionary
• Você quer um arquivo que dá pro agente tudo que ele precisa
• Está prototipando ou construindo um MVP

Os dois juntos funcionam quando (a maioria dos times em 2026):

• Tokens cuidam do build pipeline — CSS variables, config do Tailwind, exports de plataforma
• DESIGN.md cuida da comunicação com IA — regras, semântica, padrões de componentes
• DESIGN.md referencia os valores dos tokens mas adiciona o contexto que tokens não carregam
• O sistema fica sincronizado porque DESIGN.md pode ser gerado a partir de tokens + regras manuais

Ninguém te conta isso: a maioria dos times que só usam tokens ainda recebem output inconsistente da IA. O agente lê seu tokens.json, vê 47 valores de cor e não faz ideia de qual usar pra background de card versus background de página. DESIGN.md elimina essa ambiguidade.

O Pipeline Real: tokens.json + DESIGN.md

Na prática, com as ferramentas oficiais:

# 1. Exporta tokens do Figma (via plugin ou API)
figma-export tokens --output ./tokens/tokens.json

# 2. Transforma tokens pras suas plataformas
npx style-dictionary build --config sd.config.js

# 3. Gera ou atualiza DESIGN.md a partir dos tokens + suas regras
npx @designmd/cli init --from-tokens ./tokens/tokens.json

# 4. Adiciona regras semânticas manualmente (o que tokens não expressam)
# Edita DESIGN.md — adiciona padrões de componentes, do's/don'ts, constraints

# 5. Valida estrutura do DESIGN.md
npx @designmd/cli lint ./DESIGN.md

# 6. Exporta pra outros formatos se necessário
npx @designmd/cli export --format yaml

O workflow se divide clean:

• Figma → tokens.json → Style Dictionary → CSS/código de plataforma (build pipeline)
• tokens.json → DESIGN.md → contexto do AI agent (generation pipeline)

Os dois pipelines podem viver no mesmo CI. Tokens mudam no Figma, o build pipeline atualiza seu CSS, e um step separado regenera a seção de valores do DESIGN.md. As regras semânticas que você escreveu na mão ficam intactas.

Quer DESIGN.md prontos pra começar? A biblioteca do designmd.app tem mais de 454 opções cobrindo todo estilo visual.

Exemplo de Integração no Pipeline

Num projeto real, seu package.json pode ficar assim:

{
  "scripts": {
    "tokens:build": "style-dictionary build",
    "tokens:sync-designmd": "npx @designmd/cli sync --from-tokens ./tokens/tokens.json",
    "designmd:lint": "npx @designmd/cli lint ./DESIGN.md",
    "prebuild": "npm run tokens:build && npm run tokens:sync-designmd"
  }
}

Todo build garante que os valores no seu DESIGN.md batem com o último export do Figma. A seção de regras — a parte que faz o output da IA ser consistente de verdade — continua curada manualmente. Nenhuma ferramenta consegue inferir “nunca use shadow em cards” a partir de um valor JSON.

Não Competem. Complementam.

Design tokens são infraestrutura. Resolvem o problema de consistência multi-plataforma desde que a Salesforce inventou o conceito uma década atrás. Não vão a lugar nenhum.

DESIGN.md é comunicação. Resolve o problema de consistência com AI agents que não existia até 2024. Conforme mais código é escrito por agentes, a necessidade de um arquivo de design system human-readable e LLM-optimized só cresce.

Usa tokens pro seu build pipeline. Usa DESIGN.md pro seu AI pipeline. Compartilham a mesma source of truth (Figma, geralmente), mas servem consumidores completamente diferentes.

Os times que entregam UI consistente gerada por IA em 2026 não estão escolhendo entre eles. Rodam os dois — tokens compilados no CSS, DESIGN.md carregado na context window do agente. Ferramentas diferentes, mesmo design system, zero conflito.

Se seu output de IA ainda fica inconsistente mesmo tendo tokens, o problema não são os valores. São as regras que faltam. É exatamente isso que o DESIGN.md adiciona.