Marcus Andrey Estudo
Read in English Biblioteca

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
O conjunto de tokens que você vai montar: um arquivo de primitivos e dois eixos independentes, modo e densidade. Dois modos vezes duas densidades dão quatro combinações a partir de cinco arquivos pequenos, sem escrever nenhuma das quatro à mão. Esse é o trabalho do resolver do DTCG.Diagrama: Marcus Andrey, CC BY 4.0. A organização dos arquivos segue os módulos de formato e de resolver do Design Tokens Community Group, 2025.10.

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 $type pode 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 colorSpace e components de 0 a 1; o hex é 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, px ou rem.

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:

  1. Uma coleção Primitives, com um modo, com a paleta e o espaçamento.
  2. Uma coleção Mode com dois modos, Light e Dark, em que cada variável semântica é um alias para um primitivo.
  3. Uma coleção Density com Comfortable e Compact.
  4. Esconda os primitivos da publicação, para que as pessoas só escolham variáveis semânticas.
  5. 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

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar