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.
- 1Dar nome
Dê nome a cada decisão pelo propósito, com o valor bruto por baixo.
color.status.error, não #D32F2F - 2Guardar uma vez
Mantenha uma única fonte da verdade no design system, num formato padrão.
Um arquivo de tokens, um dono - 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 - 4Conferir
Cite tokens nas especificações e nos arquivos de contexto, e use lint para valores soltos.
"Nunca coloque cores fixas"
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
- 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.
- 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.
- 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.
- 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.mdouDESIGN.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. - 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.