O que são tokens de design e por que são importantes

Tokens de projeto visual são as decisões fundamentais de um sistema visual, expressas como valores nomeados e reutilizáveis. Em vez de codificar #3b82f6 diretamente em uma folha de estilos, você define color-primary-500: #3b82f6 e faz referência a esse nome em todos os lugares. O nome transmite significado; o valor pode mudar sem que seja necessário atualizar cada referência.

Os tokens abrangem todas as propriedades visuais: tokens de cor (color-primary-500: #3b82f6), tokens de espaçamento (spacing-4: 16px), tokens de tipografia (font-size-lg: 18px, font-weight-bold: 700), tokens de raio de borda (radius-md: 8px), tokens de sombra e tokens de duração de animação. Juntos, eles codificam a linguagem visual completa.

Os tokens criam uma fonte única da verdade, compartilhada entre a criação visual e a engenharia. Profissionais de criação definem os valores no Figma, e engenheiros os utilizam no código. Quando a cor da marca muda, você atualiza o valor de um único token, e cada componente que usa esse token reflete automaticamente a mudança — sem fazer uma busca e substituição em milhares de arquivos.

Sem tokens, os valores de cor e espaçamento ficam codificados diretamente nas folhas de estilo, nos arquivos de componentes e nas classes utilitárias. Uma cor azul pode aparecer como #3b82f6, rgb(59, 130, 246) e blue-500 em arquivos diferentes. Alterar a cor da marca exige localizar e substituir cada ocorrência, com alto risco de deixar alguma passar.

Os tokens de projeto são a base dos sistemas com vários temas. No modo escuro, tokens semânticos como color-background e color-text apontam para valores primitivos diferentes, dependendo do tema ativo. Altera-se um único mapeamento, não cada componente. Os temas claro e escuro compartilham o código dos componentes e diferem apenas nos valores dos tokens.

Para uma plataforma SaaS que atende a várias marcas, os tokens permitem personalizar cada marca sem duplicar código. A marca A usa azul como cor primária, e a marca B usa verde — apenas os mapeamentos dos tokens semânticos diferem. O código do componente de botão é idêntico: ele lê color-action-primary, que é resolvido para uma cor diferente por marca.

Os tokens são organizados em camadas. Tokens primitivos são valores brutos: color-blue-500: #3b82f6. Tokens semânticos expressam significado: color-action-primary: {color-blue-500}. Tokens de componente são os mais específicos: button-primary-background: {color-action-primary}. Essa hierarquia separa o "o quê" do "onde é usado".

Os tokens semânticos são essenciais para oferecer suporte a vários temas. No tema claro, color-background: {color-white}. No tema escuro, color-background: {color-gray-900}. Os componentes referenciam color-background, não uma cor específica. Ao alterar o tema, os mapeamentos dos tokens semânticos são trocados — os componentes não precisam de alterações.

As Variáveis do Figma (introduzidas em 2023) são tokens de projeto dentro do Figma. Os designers definem no Figma a mesma hierarquia de tokens que os engenheiros implementam no código. Ferramentas como Tokens Studio for Figma ou o plug-in oficial Figma Tokens exportam as variáveis do Figma para JSON, que o Style Dictionary compila em variáveis CSS ou objetos JS.

O Grupo da Comunidade de Tokens de Projeto do W3C está desenvolvendo um formato JSON padrão para tokens de projeto. O objetivo é a interoperabilidade: um arquivo de tokens que funcione com qualquer ferramenta de projeto (Figma, Sketch) e qualquer ferramenta de compilação (Style Dictionary, Theo, Panda CSS). Adotar o formato da especificação prepara o sistema de tokens para o futuro.

Os tokens de projeto exigem decisões de governança: quem pode adicionar novos tokens (projeto, engenharia ou ambos), como os tokens são versionados, como os tokens descontinuados são retirados e como as alterações nos tokens são comunicadas às equipes consumidoras. Sem governança, os sistemas de tokens perdem coerência — novos valores codificados diretamente aparecem ao lado do sistema de tokens, anulando sua finalidade.

Na hierarquia de camadas dos tokens de projeto, o que os tokens semânticos representam?

Os tokens de projeto são valores atômicos nomeados (cores, espaçamento e tipografia) que formam o vocabulário de um sistema de projeto. Eles criam uma fonte única de verdade entre o projeto e o código. A hierarquia de três camadas — primitiva (valores brutos), semântica (significado) e de componente (uso específico) — permite oferecer suporte a vários temas e marcas. As Variáveis do Figma e a especificação de tokens de projeto do W3C impulsionam a sincronização entre projeto e engenharia. A governança dos tokens garante que o sistema permaneça consistente ao longo do tempo.