Design systems · Laboratórios · 5 min de leitura
Monte um conjunto de tokens com modos
Um laboratório guiado: escreva um pequeno conjunto de tokens do Harbour no formato DTCG, com primitivos, tokens semânticos para claro e escuro, um eixo de densidade e um arquivo de resolver. Depois confira o contraste de cada par e espelhe tudo em variáveis do Figma. Cerca de duas horas, com um editor de texto e o Figma.
Trocar de modo é fácil. Manter os modos honestos é que é difícil. Criar um modo escuro parece trabalho de paleta. Na prática, é trabalho de nome: se os tokens descrevem papéis, e não cores, o segundo modo é só uma lista de valores novos. Você vai montar um conjunto pequeno de tokens que prova isso, no formato para o qual as ferramentas estão convergindo, e conferir se cada par continua passando nos dois modos.
O que você vai fazer:
- Escrever tokens primitivos no formato DTCG
- Escrever tokens semânticos para claro e escuro que apontam para eles
- Acrescentar a densidade como um segundo eixo, independente
- Descrever os eixos num arquivo de resolver
- Medir cada par de texto nos dois modos e espelhar o conjunto no Figma
Você vai precisar de: um editor de texto que valide JSON (VS Code ou qualquer editor de código), Figma (num plano com modos de variáveis), o verificador de contraste do WebAIM, cerca de duas horas.
1. O formato do que você vai montar
primitives.tokens.json
A paleta e as escalas. Iguais em todo modo. Ninguém usa direto.
color.blue. 600 - #1F5FAE
color.blue. 400 - #5B95DB
color.ink.900- #14202B
color.sand.50- #FBF8F2
space.3·space.4- 12 px · 16 px
light / dark.tokens.json
Os mesmos nomes semânticos em cada arquivo, apontando para primitivos diferentes.
color.action. primary - claro →
{color.blue. 600}
escuro →{color.blue. 400} color.text. default - claro →
{color.ink. 900}
escuro →{color.sand. 50} color.surface. default - claro →
{color.white}
escuro →{color.ink. 900}
comfortable / compact.tokens.json
Um segundo eixo, independente: a densidade, para o console da equipe.
space.inset. md - confortável →
{space.4}16 px
compacta →{space.3}12 px size.control. height - confortável → 44 px
compacta → 36 px
Cinco arquivos pequenos e um resolver. O Format Module do DTCG chegou à primeira versão estável, a 2025.10, em outubro de 2025, e recomenda a extensão .tokens.json (DTCG, Format Module 2025.10). As regras de que você precisa neste laboratório:
- Um token é um objeto com um
$value. O$typepode ficar no token ou no grupo dele. - Um alias aponta para outro token entre chaves:
"{color.blue.600}". - Um valor de cor é um objeto com
colorSpaceecomponentsde 0 a 1; ohexé um fallback opcional de 6 dígitos (DTCG, Color Module 2025.10). - Um valor de dimensão é um objeto com um número e uma unidade,
pxourem.
2. Escreva os primitivos
O primitives.tokens.json guarda a paleta e a escala brutas. Nenhum componente usa esses tokens direto.
{
"color": {
"$type": "color",
"blue": {
"400": { "$value": { "colorSpace": "srgb", "components": [0.3569, 0.5843, 0.8588], "hex": "#5b95db" } },
"600": { "$value": { "colorSpace": "srgb", "components": [0.1216, 0.3725, 0.6824], "hex": "#1f5fae" } }
},
"ink": {
"900": { "$value": { "colorSpace": "srgb", "components": [0.0784, 0.1255, 0.1686], "hex": "#14202b" } }
},
"sand": {
"50": { "$value": { "colorSpace": "srgb", "components": [0.9843, 0.9725, 0.949], "hex": "#fbf8f2" } }
},
"white": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } }
},
"space": {
"$type": "dimension",
"3": { "$value": { "value": 12, "unit": "px" } },
"4": { "$value": { "value": 16, "unit": "px" } },
"5": { "$value": { "value": 24, "unit": "px" } }
}
}
Para converter um hex em componentes, divida cada par por 255: 1F é 31, e 31 ÷ 255 dá 0,1216.
3. Escreva os tokens semânticos, uma vez por modo
O mode/light.tokens.json e o mode/dark.tokens.json têm exatamente os mesmos nomes. Só os aliases mudam.
{
"color": {
"$type": "color",
"action": { "primary": { "$value": "{color.blue.600}", "$description": "Main action: one per screen" } },
"text": {
"default": { "$value": "{color.ink.900}" },
"on-action": { "$value": "{color.white}" }
},
"surface": { "default": { "$value": "{color.white}" } }
}
}
E o arquivo escuro:
{
"color": {
"$type": "color",
"action": { "primary": { "$value": "{color.blue.400}", "$description": "Main action: one per screen" } },
"text": {
"default": { "$value": "{color.sand.50}" },
"on-action": { "$value": "{color.ink.900}" }
},
"surface": { "default": { "$value": "{color.ink.900}" } }
}
}
Repare no text.on-action: branco no claro, ink no escuro. Branco sobre blue.400 dá só 3,1:1, o que reprova para texto, então o modo escuro precisa de texto escuro no botão. Esse é o tipo de coisa que você só descobre medindo.
4. Acrescente a densidade como um eixo próprio
O density/comfortable.tokens.json e o density/compact.tokens.json, para o console da equipe:
{
"space": {
"$type": "dimension",
"inset": { "md": { "$value": "{space.4}" } }
}
}
No arquivo compacto, o space.inset.md aponta para {space.3}. A densidade não depende de claro ou escuro, então continua sendo um par de arquivos separado, e não quatro arquivos combinados.
5. Descreva os eixos num resolver
O harbour.resolver.json lista o conjunto que está sempre ligado e os dois modificadores. A ferramenta escolhe um contexto por modificador (DTCG, Resolver Module 2025.10):
{
"version": "2025.10",
"sets": {
"core": { "sources": [{ "$ref": "primitives.tokens.json" }] }
},
"modifiers": {
"mode": {
"contexts": {
"light": [{ "$ref": "mode/light.tokens.json" }],
"dark": [{ "$ref": "mode/dark.tokens.json" }]
},
"default": "light"
},
"density": {
"contexts": {
"comfortable": [{ "$ref": "density/comfortable.tokens.json" }],
"compact": [{ "$ref": "density/compact.tokens.json" }]
},
"default": "comfortable"
}
},
"resolutionOrder": [
{ "$ref": "#/sets/core" },
{ "$ref": "#/modifiers/mode" },
{ "$ref": "#/modifiers/density" }
]
}
As ferramentas ainda estão alcançando a especificação estável. O Style Dictionary suporta o formato DTCG desde a versão 4, mas avisa que o formato 2025.10 ainda não tem suporte completo (Style Dictionary, DTCG). Confira a sua ferramenta antes de depender dos objetos de cor ou do resolver; a estrutura dos seus arquivos está certa de qualquer jeito.
6. Meça cada par, nos dois modos
Faça uma tabela pequena e preencha com o verificador de contraste:
| Par | Claro | Escuro |
|---|---|---|
text.default sobre surface.default |
ink.900 sobre branco: 16,52:1 | sand.50 sobre ink.900: 15,58:1 |
text.on-action sobre action.primary |
branco sobre blue.600: 6,35:1 | ink.900 sobre blue.400: 5,32:1 |
action.primary contra surface.default (a borda de um controle, pede 3:1) |
6,35:1 | 5,32:1 |
Texto pede 4,5:1, e a borda de um controle, 3:1 (W3C, Understanding 1.4.3, Understanding 1.4.11). Todos os pares do Harbour aqui passam. Se algum dos seus não passar, troque o alias no arquivo daquele modo, não o componente.
7. Espelhe no Figma
No Figma, um modo é uma lista de valores para as variáveis de uma coleção, um valor por variável (Figma, Overview of variables, collections and modes). Monte do mesmo jeito que os arquivos:
- Uma coleção Primitives, com um modo, com a paleta e o espaçamento.
- Uma coleção Mode com dois modos, Light e Dark, em que cada variável semântica é um alias para um primitivo.
- Uma coleção Density com Comfortable e Compact.
- Esconda os primitivos da publicação, para que as pessoas só escolham variáveis semânticas.
- Faça um frame com um card e um botão, aplique as variáveis semânticas e troque os modos no frame.
Se alguma coisa mudar de cor do jeito errado ao trocar o modo, alguma camada está ligada a um primitivo. Corrija essa ligação.
8. Confira seu trabalho
Perguntas para refletir: Que token você teve que criar por causa do modo escuro, como o text.on-action? O que um terceiro eixo, como alto contraste, acrescentaria aos arquivos?
Relacionadas
Temas e modos · Níveis de tokens · Como nomear tokens · Tokens do Figma ao código · Sistemas multimarca e multiproduto · Escreva um conjunto de tokens de movimento