Design tokens no formato do W3C: o que a versão 2025.10 define

Design system · Artigo

Design tokens no formato do W3C: o que a versão 2025.10 define

Falar no WhatsApp
Resposta direta

O formato de design tokens 2025.10 é um relatório estável do grupo comunitário de design tokens hospedado pelo W3C, publicado em 28 de outubro de 2025. Ele define o token como objeto JSON com $value, prevê 7 tipos simples e 6 compostos, liga tokens por apelidos entre chaves e por grupos, marca descontinuação com $deprecated e descreve temas no módulo Resolver.

Abra um arquivo de tokens de um design system e você verá nomes, chaves e valores: uma cor de destaque, um espaçamento de 16 pixels, uma duração de 200 milissegundos. Até pouco tempo, cada ferramenta escrevia esse arquivo de um jeito. Desde 28 de outubro de 2025, existe uma descrição comum, estável e aberta para ele.

O formato de design tokens do W3C, na versão 2025.10, foi publicado pelo grupo comunitário de design tokens hospedado pelo W3C. Ele define como um token é escrito, quais tipos de valor existem, como um token aponta para outro, como os grupos funcionam e como marcar uma peça descontinuada. Este artigo explica cada uma dessas partes e o que elas mudam para quem contrata ou mantém um design system.

O assunto pertence à frente de design system, na seção de interfaces digitais do hub de design da Trilion. A página da frente apresenta o formato em poucas linhas. Aqui ele é lido por dentro.

O que é o formato 2025.10 e quem o publicou

O formato 2025.10 é um relatório final de grupo comunitário, considerado estável pelos autores, que descreve um arquivo JSON comum para guardar e trocar decisões de design.

Um grupo comunitário, e não um comitê de normas

O Design Tokens Community Group reúne fabricantes de ferramentas e equipes de design systems. O W3C hospeda as discussões, mas a página do grupo deixa claro que ele não fala em nome dos membros nem da equipe do W3C. O documento não é uma norma do W3C e não está no caminho de normas oficiais.

Estável, com 3 módulos

Mesmo sem ser norma, o texto se declara estável, e mudanças futuras virão em especificações novas que substituem a anterior. A página de relatórios do grupo lista 3 módulos com a mesma data: Format, que descreve o arquivo; Color, que trata dos valores de cor; e Resolver, que trata de temas e contextos. O anúncio da versão menciona mais de 10 ferramentas e projetos abertos que já a adotam ou estão em implementação.

Por que um formato comum importa

Um design system vive em pelo menos 2 lugares: o arquivo de desenho e o código. Sem formato comum, cada passagem entre ferramentas pede um conversor próprio, e cada conversor pode interpretar o mesmo valor de um jeito. Com um formato público, o arquivo de tokens vira a fonte única que as outras ferramentas leem.

Como um token é escrito no formato?

Um token é um objeto JSON com a propriedade $value; o nome é a chave desse objeto, e as outras propriedades dizem o tipo, a descrição e dados extras.

Nome e valor

O nome e o valor são as 2 partes obrigatórias. Qualquer objeto com $value é um token. Um objeto sem $value é um grupo, que pode conter tokens e outros grupos. Essa regra simples permite organizar os tokens em árvores, como cor, depois destaque, depois o tom de cada uso.

Tipo, herdado ou declarado

A propriedade $type diz que tipo de valor o token guarda. Ela é opcional, mas o tipo precisa ser descobrível: vem do próprio token, do token para o qual ele aponta ou do grupo mais próximo que declara um tipo. Se nada disso existir, o token é inválido. As ferramentas não podem adivinhar o tipo pelo formato do valor.

Descrição e extensões

A propriedade $description guarda um texto simples, que as ferramentas de tradução podem transformar em comentário no código. A propriedade $extensions guarda dados próprios de uma ferramenta, de preferência com nome no estilo de domínio invertido. O formato pede que as ferramentas preservem os dados que não entendem, para que nada se perca na passagem.

Regras de nome

Os nomes diferenciam maiúsculas de minúsculas. Não podem começar com o cifrão, reservado às propriedades do formato, nem conter chaves ou ponto, usados nas referências. Essas restrições parecem detalhe, mas são elas que permitem a qualquer ferramenta ler o caminho de um token sem ambiguidade.

Um token bem nomeado diz para que serve, e não como é. "Cor de alerta" sobrevive a uma troca de paleta; "vermelho 500" não.

Quais tipos de valor o formato prevê?

O formato prevê 7 tipos simples e 6 compostos, e cada um tem uma estrutura de valor definida, com unidade explícita quando a medida depende dela.

Os tipos simples

  • color: a cor, com espaço de cor e componentes, detalhada no módulo próprio.
  • dimension: uma medida com número e unidade, que pode ser px ou rem.
  • fontFamily: o nome de uma família de letras ou uma lista em ordem de preferência.
  • fontWeight: o peso da letra, em número de 1 a 1000 ou por nome, como bold.
  • duration: um tempo com número e unidade, em ms ou s.
  • cubicBezier: a curva de aceleração de um movimento, com 4 números.
  • number: um número sem unidade, útil para proporções.

Os tipos compostos

Os compostos reúnem vários valores em um só token: estilo de traço, borda, transição, sombra, gradiente e tipografia. Um token de borda, por exemplo, junta cor, largura e estilo de traço. Um token de sombra pode ser uma sombra única ou uma lista de sombras sobrepostas.

Unidade sempre explícita

Em uma medida, o valor é um objeto com o número e a unidade separados, e a unidade é obrigatória mesmo quando o número é zero. A exigência evita a dúvida clássica entre pixels e outra unidade qualquer. As ferramentas de tradução convertem px para as unidades de cada plataforma, como dp ou pt, e o documento avisa que a conversão de rem pode perder precisão.

Cor em espaços de cor modernos

O módulo de cor descreve o valor como um objeto com o espaço de cor, os componentes e, se for o caso, a transparência e um código hexadecimal de reserva. A lista de espaços inclui srgb, display-p3, oklch, lab e outros. Para quem desenha, a consequência é prática: uma cor pensada para telas de gama ampla pode ser registrada sem ser achatada para o sRGB.

Apelidos, grupos e herança: como os tokens se ligam

Os tokens se ligam por apelidos, que apontam de um token para outro, e por grupos, que organizam a árvore e passam tipo e descontinuação aos filhos.

O apelido com chaves

Um apelido é um token cujo valor é o caminho de outro token entre chaves, como "{color.blue}". Ele sempre resolve para o valor inteiro do token apontado. Apelidos podem formar cadeias, em que um aponta para outro que aponta para um terceiro. Referências circulares são erro e devem ser relatadas pela ferramenta.

A referência por ponteiro

Para chegar a uma parte de um valor, como um componente de cor dentro de um objeto, o formato prevê a referência $ref no padrão JSON Pointer. As ferramentas compatíveis precisam aceitar as 2 formas. Na prática, o apelido com chaves cobre a maioria dos casos de um design system.

Grupos e o token raiz

Um grupo pode declarar $type, que vale para os filhos que não declaram o próprio. Também pode ter um token base com o nome reservado $root, útil quando uma família de cores tem um tom principal e variações. O caminho fica "{color.accent.$root}", e as variações ficam ao lado, no mesmo grupo.

Estender um grupo

Com $extends, um grupo recebe toda a árvore de outro grupo e redefine apenas os caminhos que precisam mudar. Definições locais prevalecem sobre as herdadas no mesmo caminho, e cadeias circulares são erro. É esse recurso que torna viável manter variações sem copiar a árvore inteira, como mostra o artigo sobre design system com temas para várias marcas.

Descontinuação: como o formato marca o que vai sair

O formato tem um campo próprio, $deprecated, que marca um token ou um grupo como descontinuado e pode explicar o motivo e o substituto.

Os valores possíveis

O campo aceita verdadeiro, falso ou um texto. O texto é a forma mais útil, porque diz o que fazer: por exemplo, que o token deve ser trocado por outro, com o caminho do novo. As ferramentas podem mostrar esse aviso a quem desenha e a quem programa no momento em que o token é usado.

Herança no grupo

Quando um grupo inteiro é marcado, os tokens dentro dele herdam a marcação, a menos que declarem o contrário. Isso permite descontinuar uma família antiga de uma só vez e manter vivo um token que continua válido.

Ligação com a política de versões

A marcação no arquivo é metade do trabalho. A outra metade é o rito: anunciar a descontinuação em uma versão, manter o token por um período e remover só em uma versão que admite mudança incompatível. O artigo sobre governança de design system descreve esse caminho.

Temas e contextos: o que o módulo Resolver acrescenta

O módulo Resolver descreve, em um arquivo separado, como combinar conjuntos de tokens para gerar contextos como tema claro, tema escuro ou alto contraste.

Conjuntos e modificadores

O arquivo do Resolver trabalha com conjuntos, que reúnem arquivos ou tokens, e modificadores, que têm contextos com nome. Um modificador chamado tema pode ter os contextos claro e escuro, cada um apontando para os tokens que valem naquele caso. Um contexto pode ser marcado como padrão.

A ordem de resolução

A propriedade resolutionOrder lista conjuntos e modificadores na ordem em que são aplicados, e os itens posteriores prevalecem nos conflitos. A ferramenta recebe as escolhas, como tema escuro, e achata tudo em uma única árvore de tokens. O documento recomenda a extensão .resolver.json para esse arquivo.

O exemplo do próprio documento

O exemplo de tema do Resolver tem 4 contextos: claro, claro com alto contraste, escuro e escuro com alto contraste. Os de alto contraste somam um arquivo próprio ao tema base. A estrutura mostra a intenção do módulo: evitar a multiplicação de arquivos quando os contextos se cruzam.

O que o formato muda na troca entre ferramentas e na contratação

O formato muda a pergunta da contratação: em vez de perguntar em qual ferramenta os tokens estão, pergunta-se se o arquivo entregue segue a especificação pública.

As ferramentas de tradução

O documento chama de ferramentas de tradução as que convertem os tokens de um formato para outro, como variáveis de CSS ou arquivos de recursos de aplicativo. Ele pede que elas usem o caminho completo do token, e não só o nome, porque nomes podem se repetir em grupos diferentes.

O que conferir no arquivo entregue

  1. Abra o arquivo e veja se ele termina em .tokens ou .tokens.json, as extensões recomendadas.
  2. Confira se cada token tem tipo próprio ou herdado de um grupo.
  3. Veja se as medidas trazem a unidade separada do número.
  4. Procure apelidos entre chaves ligando os tokens de uso aos tokens de base.
  5. Verifique se os tokens que vão sair estão marcados com $deprecated e um texto.
  6. Peça a descrição de cada token, em texto simples, para virar comentário no código.

O que o formato não resolve

O formato padroniza o arquivo, e não as decisões. Ele não diz quantas cores uma marca deve ter, nem qual contraste é suficiente: essa avaliação é tratada na seção de UX e UI. Também não garante que o arquivo de desenho e o código estejam sincronizados. Isso continua sendo trabalho de rotina da equipe.

O formato aberto não decide por você qual é a cor da marca. Ele garante que, decidida, ela chegue igual a todas as ferramentas.

O que pedir na entrega dos tokens

Peça um arquivo no formato 2025.10, com tipos, unidades, descrições, apelidos e marcação de descontinuação, e um arquivo do Resolver quando houver temas.

O essencial deste artigo

O formato 2025.10 é um relatório estável de grupo comunitário, não uma norma oficial. Ele define o token como objeto com $value, prevê 13 tipos de valor, liga tokens por apelidos e grupos, marca o que vai sair com $deprecated e, com o módulo Resolver, descreve temas e contextos. Para o contratante, isso significa um arquivo que pode ser lido por várias ferramentas.

O próximo passo

Para revisar os tokens que a sua empresa já tem, descreva onde eles estão hoje no briefing da página de design system. Fundada em 1995 e com escritório em Moema, a Trilion recebe clientes no escritório ou a distância, e uma só equipe responde pela estratégia, pelo desenho e pela aplicação digital. A proposta vem por escrito, depois do briefing. A chegada dos tokens ao código é tratada em design UX e usabilidade, no hub Desenvolvimento.

Sobre este texto

Escrevemos este artigo para o hub de Design da Trilion lendo os documentos originais listados abaixo, abertos em 17/11/2026. As recomendações de conferência do arquivo e de nome dos tokens são leitura editorial sobre as fontes.

O texto não trata das ferramentas que implementam o formato, que mudam com frequência, nem de detalhes de programação.

  • Design Tokens Community Group, Design Tokens Format Module 2025.10: designtokens.org
  • Design Tokens Community Group, Design Tokens Color Module 2025.10: designtokens.org
  • Design Tokens Community Group, Design Tokens Resolver Module 2025.10: w3.org
  • W3C, página do Design Tokens Community Group: w3.org

Fontes consultadas

Perguntas frequentes

O formato de design tokens 2025.10 é uma norma do W3C?

Não. É um relatório final de grupo comunitário. O W3C hospeda as discussões do grupo, mas o documento não é norma oficial nem está no caminho de normas. Os autores o consideram estável, e mudanças futuras virão em especificações novas que substituem a atual.

Qual extensão de arquivo o formato recomenda?

Para os tokens, o formato recomenda as extensões .tokens e .tokens.json, e o tipo de mídia application/design-tokens+json. Para o arquivo que descreve temas e contextos, o módulo Resolver recomenda a extensão .resolver.json.

O que é um apelido de token?

É um token cujo valor é o caminho de outro token escrito entre chaves, como {color.blue}. O apelido sempre resolve para o valor inteiro do token apontado. Ele permite que tokens de uso, como cor de alerta, apontem para tokens de base, e que uma troca de paleta não mexa nos componentes.

Como o formato trata o tema escuro?

O tema escuro é descrito pelo módulo Resolver, em um arquivo separado. Um modificador chamado tema pode ter contextos como claro e escuro, cada um com os seus tokens. A ferramenta recebe a escolha e gera uma única árvore de tokens para aquele contexto.

Posso registrar cores fora do sRGB no formato?

Pode. O módulo de cor descreve o valor com o espaço de cor, os componentes e, se for o caso, a transparência e um código hexadecimal de reserva. A lista de espaços inclui display-p3, oklch, lab e outros, além do srgb.

Método

Como a Trilion conduz um projeto de interface

Do briefing à entrega dos arquivos finais, em etapas e com tudo por escrito. A proposta vem depois do briefing.

  1. Briefing em 3 passos

    Você conta o momento da marca; nós devolvemos perguntas e um caminho possível.

  2. Diagnóstico e estratégia por escrito

    Telas, fluxos, componentes existentes e marca, levantados antes do desenho.

  3. Desenho em etapas

    Telas e componentes entregues em sistema, prontos para quem programa.

  4. Testes em uso

    A marca aplicada em peças concretas, na tela e no papel, antes de fechar.

  5. Manual e acompanhamento

    Regras registradas, arquivos organizados e a rotina que mantém a marca coerente.

Vamos desenhar a sua interface

Conte o seu projeto. A Trilion responde com uma proposta escrita, depois do briefing, e cuida da estratégia, do desenho e da aplicação.

Falar no WhatsApp
Blog da Trilion · Marketing de luxo

Continue aprendendo sobre marketing de luxo

Artigos do blog da Trilion que aprofundam os temas deste texto. Arraste, use as setas ou o teclado.

WhatsApp
WhatsApp

Converse com a Trilion

Diga-nos o seu nome, e a conversa abre em seguida