Design tokens explicados, com um conversor de JSON para CSS ao vivo
Design tokens explicados
Design tokens explicados com exemplos (JSON, CSS, Tailwind) | We.Inc
O que são design tokens, como o formato JSON do grupo comunitário da W3C os escreve e um conversor ao vivo que transforma JSON de tokens em variáveis CSS e em um bloco @theme do Tailwind v4.
Design tokens são decisões de design com nome, como color.primary ou space.md, guardadas como dados para que todas as plataformas leiam os mesmos valores. O formato do Design Tokens Community Group escreve os tokens em JSON com $value e $type, e permite que um token aponte para outro usando chaves. Depois, ferramentas transformam esse JSON em variáveis CSS, temas do Tailwind ou código de app.
Níveis de tokens que a maioria das equipes usa
Nível
Exemplo de nome
Contém
Base (primitivo)
Um valor bruto: uma cor, um tamanho ou uma fonte
Semântico (alias)
Uma função que aponta para um token base
Componente
Uma função restrita a um único componente
A maioria das explicações para na definição. Cole ou edite abaixo um JSON de tokens no formato do grupo comunitário e veja, enquanto digita, as propriedades personalizadas de CSS e o tema do Tailwind v4 gerados, com os aliases resolvidos como referências var().
Edite o JSON à esquerda. Os grupos podem definir $type uma única vez para todos os tokens dentro deles.
Faça referência a outro token colocando o caminho com pontos entre chaves, por exemplo {color.blue-500}.
Leia a aba CSS para ver as variáveis em :root, ou a aba Tailwind para ver um bloco @theme.
Copie o resultado para a sua folha de estilos. Antes, corrija qualquer mensagem de erro exibida abaixo do editor.
Dê aos tokens semânticos nomes que digam a função deles (text, surface, danger), e não a aparência (red, dark), para que um rebranding mude só o nível base.
Mantenha os tokens base fora dos componentes. Os componentes devem ler nomes semânticos para que o modo escuro e os temas possam trocar os valores por baixo.
Guarde os tokens em um único arquivo sob controle de versão e gere a partir dele o resultado de cada plataforma.
Use a extensão recomendada .tokens ou .tokens.json para que as ferramentas reconheçam os arquivos.
Perguntas frequentes
O que é um design token?
Um design token é um nome associado a um valor de design, por exemplo color.text guardando uma cor quase preta. O código e os arquivos de design usam o nome, então mudar o valor em um só lugar atualiza todos os botões, páginas e apps que fazem referência a ele.
Existe um formato padrão para design tokens?
Sim. O Design Tokens Community Group da W3C publicou o Format Module 2025.10 como relatório final do grupo comunitário em 28 de outubro de 2025 e o descreve como estável. Ele é um relatório de grupo comunitário, não uma Recomendação da W3C.
Qual é a diferença entre design tokens e variáveis CSS?
Os tokens são os dados de origem, independentes de qualquer plataforma. As propriedades personalizadas de CSS são apenas um dos resultados. O mesmo arquivo de tokens também pode gerar constantes em Swift, Android ou JavaScript, algo que as variáveis CSS sozinhas não oferecem.
Como os design tokens funcionam com o Tailwind CSS?
No Tailwind v4, você declara variáveis de tema dentro de @theme, como --color-primary. O Tailwind cria utilitários como bg-primary a partir delas e também as emite como variáveis CSS normais em :root, então tokens e utilitários ficam sincronizados.
Como as cores são escritas no formato de tokens?
No formato 2025.10, um valor de cor é um objeto com um colorSpace, como srgb, e um array de componentes de 0 a 1, com alpha opcional. O conversor desta página também aceita strings simples, para que você possa colar arquivos de tokens mais antigos.
Por que as equipes adotam tokens
Sem tokens, o azul da marca vive como um código hex colado em centenas de lugares, entre CSS, apps mobile e arquivos de design. Mudá-lo exige um localizar e substituir que sempre deixa algum para trás.
Com tokens, esse azul tem um nome e um único lugar. Designers e desenvolvedores falam de color.primary, e uma etapa de build escreve o valor no formato próprio de cada plataforma.
Como ler o formato JSON
Qualquer objeto com $value é um token; qualquer outro objeto é um grupo. As propriedades que começam com cifrão são reservadas pelo formato: $value, $type, $description, $deprecated e $extensions.
A especificação define tipos simples como color, dimension, fontFamily, fontWeight, duration, cubicBezier e number, além de tipos compostos como shadow, border, transition, typography, strokeStyle e gradient. Dimensões e durações são objetos com um valor numérico e uma unidade.
Dos tokens a um tema funcionando
Um site pequeno pode manter os tokens direto no CSS como propriedades personalizadas. Quando você publica em mais de uma plataforma, ou desenha em uma ferramenta que exporta tokens, gere o CSS a partir do JSON para ter uma única fonte.
O modo escuro vira um segundo conjunto de valores semânticos. As cores base continuam as mesmas, e a camada semântica troca para qual base cada função aponta dentro de uma media query de esquema escuro ou de um atributo data.
Tokens semânticos com um tema escuro
Troque os valores semânticos, mantenha os valores base
O card só lê --surface e --text. O bloco escuro redefine esses dois nomes, e o card acompanha sem nenhuma mudança nas próprias regras.
Um token composto
Token de sombra no formato do grupo comunitário
Tokens compostos agrupam vários valores. Aqui a cor é ela mesma um alias, e os deslocamentos usam objetos de dimensão.
Nenhum token encontrado. Um token é um objeto com a propriedade $value.
Isso ainda não é um JSON válido: {message}
Conversor de JSON de tokens para CSS
Edite o arquivo de tokens e as variáveis CSS e o tema do Tailwind são atualizados enquanto você digita. O arquivo inicial é convertido em: