Marcus Andrey Estudo
Read in English Biblioteca

Framework · IA e design · 4 min de leitura

Design tokens

Decisões de design com nome (cor, espaçamento, tipografia, raio) guardadas como dados num só lugar, para que ferramentas de design, código e agentes de IA usem os mesmos valores e você consiga conferir que usam.

  1. 1Dar nome

    Dê nome a cada decisão pelo propósito, com o valor bruto por baixo.

    color.status.error, não #D32F2F
  2. 2Guardar uma vez

    Mantenha uma única fonte da verdade no design system, num formato padrão.

    Um arquivo de tokens, um dono
  3. 3Sincronizar

    Gere as variáveis do Figma, as variáveis do código e o contexto do agente a partir dessa fonte.

    O mesmo valor em toda ferramenta
  4. 4Conferir

    Cite tokens nas especificações e nos arquivos de contexto, e use lint para valores soltos.

    "Nunca coloque cores fixas"
Os tokens saem de uma fonte com nome para as ferramentas de design, o código e os agentes de IA, e uma verificação mantém todo mundo nela.

Use quando

  • Telas ou protótipos gerados por IA usam cores e espaçamentos "quase" iguais aos do seu design system.
  • Design e código se afastam: o valor no Figma e o valor no código já não são os mesmos.
  • Você está tornando o design system legível por máquina para que os agentes construam interfaces dentro do sistema.

Como usar

  1. Dê nome às decisões pelo propósito. Dê a cada valor um nome que diga para que serve (por exemplo "surface", "text-muted", "status-error", "space-md"), não como ele parece. Mantenha os valores brutos por baixo e aponte os tokens com nome para eles. Resultado: uma lista de tokens com nomes por propósito.
  2. Mantenha uma única fonte da verdade. Guarde os tokens num lugar só, cujo dono é o design system, num formato padrão como o formato do W3C Design Tokens Community Group (DTCG). Todo o resto é gerado a partir dele. Resultado: um arquivo ou repositório de tokens com dono.
  3. Sincronize com tudo que consome os tokens. Gere as variáveis do Figma, as variáveis do código e o arquivo de contexto de design a partir dessa fonte, para que ninguém copie valores à mão. Resultado: os mesmos tokens no Figma, no código e no contexto do agente.
  4. Cite tokens nas especificações e nos arquivos de contexto. Escreva nomes de tokens, não valores, nas especificações de recurso e no CLAUDE.md ou DESIGN.md, com uma regra explícita como "nunca coloque cores, espaçamentos ou tamanhos de fonte fixos". Veja Arquivos de contexto. Resultado: especificações e arquivos de contexto que citam tokens.
  5. Use lint para valores soltos. Acrescente uma verificação na revisão de código ou no QA de design que aponte cores, espaçamentos e tamanhos de fonte fixos, inclusive em código gerado por IA. Acompanhe a fatia de valores soltos ao longo do tempo como um sinal de saúde do design system. Resultado: uma verificação automática e um número que você consegue acompanhar.

Exemplo prático

Uma plataforma interna de operações com 6 times de produto. Os designers geram protótipos em código com um agente, e a revisão encontra quatro vermelhos diferentes para estados de erro.

Antes Depois
O vermelho de erro está colado como hex no Figma, no código e num modelo de prompt, e os valores são diferentes Um token, color.status.error, no arquivo de tokens do design system
O agente escolhe "um vermelho que parece certo" O CLAUDE.md diz "use os tokens var(--ds-*); nunca coloque cores fixas"
Os revisores pegam cores fora da paleta no olho Um linter aponta toda cor solta no repositório de protótipos
Mudar a cor de erro exige uma busca em vários arquivos Mudar o token atualiza as variáveis do Figma e o código a partir de um lugar só

Na revisão de design seguinte, os achados de "desvio do sistema" caem de problema número um para algo ocasional, e os casos que sobram são necessidades novas que vão para o processo de contribuição.

Cuidado com

  • Nomes que descrevem a aparência. "red-500" usado para erros quebra quando a marca muda. Dê nome pelo propósito e mantenha a escala visual por baixo.
  • Duas fontes da verdade. Se Figma e código são editados separadamente, vão se afastar. Escolha uma fonte e gere o resto.
  • Tokens que ninguém confere. Sem lint ou etapa de revisão, agentes e pessoas vão continuar usando valores soltos. Torne a verificação automática.
  • Tokens demais. Centenas de tokens quase iguais são tão difíceis de usar quanto valores soltos. Acrescente um token só quando ele representa uma decisão real.

Modelo

Copie isto para a documentação do design system para descrever um token, e para o seu arquivo de contexto como regra.

Token:            color.status.error
Propósito:        Texto e ícones para erros que bloqueiam o usuário
Valor (fonte):    -> palette.red.600      (definido só no arquivo de tokens)
Usado em:         variável do Figma · variável do código · DESIGN.md
Use:              Mensagens de erro, bordas de campo inválido, status de falha
Não use:          Decoração, gráficos, botões de "excluir" que não são erros
Dono:             Time do design system

Regra do arquivo de contexto:
- Use design tokens (<prefixo>-*). Nunca coloque cores, espaçamentos ou tamanhos de fonte fixos.
- Se nenhum token servir, pare e liste como questão em aberto.
Fonte
W3C Design Tokens Community Group
Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar