Tokens de cor: nomear para não se perder

Um token de cor é um nome dado a uma cor, guardado num lugar só, para que todo o site ou toda a marca use esse nome em vez de repetir o código HEX. Em vez de escrever #18453B em trinta lugares, você escreve cor-principal e define o valor uma vez. Quando a cor mudar, você muda em um ponto só e o resto acompanha.

O que é um token de cor, em palavras simples

A especificação em rascunho do Design Tokens Community Group, um grupo comunitário ligado ao W3C, define um token como “informação associada a um nome legível por humanos, no mínimo um par nome/valor”. O mesmo documento avisa que ainda é um rascunho e não um padrão final, então trate o formato como uma convenção em evolução. A ideia de nomear cores, no entanto, é antiga e usada em todo tipo de projeto.

Pense numa cozinha com potes etiquetados. Você não pergunta “onde está o pó branco que adoça?”. Você procura o pote “açúcar”. O token é a etiqueta. O HEX é o conteúdo.

Dois níveis de nome

O jeito mais útil de organizar é separar em dois níveis.

Nível 1: a paleta bruta

São as cores que existem, com nomes que descrevem o tom, não o uso.

:root {
  --verde-900: #18453B;
  --verde-500: #3FA37A;
  --creme-100: #F5F2EA;
  --vermelho-600: #C0392B;
}

Nível 2: o papel da cor

São nomes que dizem para que a cor serve. Eles apontam para a paleta bruta.

:root {
  --cor-texto: var(--verde-900);
  --cor-fundo: var(--creme-100);
  --cor-botao: var(--verde-900);
  --cor-erro: var(--vermelho-600);
}

O MDN explica como isso funciona em CSS: uma propriedade personalizada começa com dois traços, como --cor-texto, e é usada com var(). Declarada em :root, ela fica disponível na página inteira. O var() aceita ainda um valor reserva, usado se a variável não existir: var(--cor-texto, black).

Na especificação de tokens, a mesma ideia se chama alias (apelido): um token aponta para outro com chaves, como {cor.marca}, e assim os dois compartilham o valor. O documento mostra, por exemplo, um token button.primary que aponta para color.brand.

Por que o nível 2 é o que importa

Imagine que o seu site tem botões, links e avisos, todos usando #18453B direto. Um dia você decide escurecer o verde. Você precisa achar cada ocorrência e ainda decidir quais eram “o verde da marca” e quais eram só “um verde parecido”.

Com os dois níveis, a decisão fica clara. Para escurecer só o botão, você troca o que --cor-botao aponta. Para trocar a marca inteira, você muda a paleta bruta. E se amanhã o site ganhar um modo escuro, basta redefinir --cor-fundo e --cor-texto para outros valores, sem mexer em cada página.

Nome pelo papel, não pelo tom

Evite nomes como --azul-bonito ou --vermelho-aviso para o nível 2. Se o aviso um dia for laranja, o nome mente. Prefira papéis estáveis:

cor-texto, cor-texto-suave
cor-fundo, cor-superficie (cartões e caixas sobre o fundo)
cor-botao, cor-botao-texto
cor-link
cor-erro, cor-sucesso, cor-atencao
cor-borda

Na paleta bruta, o número (100, 500, 900) indica o brilho: quanto maior, mais escuro. Essa convenção é comum, mas não é obrigatória. O que importa é seguir a mesma regra em todo o projeto.

Seis passos para criar os tokens do seu site

Liste as cores da sua paleta com o HEX (use o editor do Tom a Tom).
Dê um nome de tom a cada uma e escreva a paleta bruta.
Liste os papéis que o seu site tem: fundo, texto, botão, link, borda, erro e sucesso.
Aponte cada papel para uma cor da paleta bruta.
Meça o contraste entre cada texto e cada fundo. A WCAG, conjunto de regras de acessibilidade do W3C, pede 4,5 para 1 em texto normal e 3 para 1 em texto grande (a versão 2.2, de outubro de 2023, manteve esses valores). Na paleta de exemplo, o verde #18453B sobre o creme #F5F2EA dá 9,61 para 1, e o branco #FFFFFF sobre o verde médio #3FA37A dá 3,12 para 1: serve para texto grande, mas não para texto pequeno.
Troque os HEX soltos do CSS pelos tokens de papel.

Registre os pares de texto e fundo aprovados

Uma dica que poupa dor de cabeça: guarde os pares aprovados. Por exemplo, “cor-texto sobre cor-fundo: 9,61 para 1, aprovado para texto normal”. Se alguém quiser usar outro par, verifica na lista. Veja a medição de contraste WCAG para saber como calcular.

Tokens em arquivo JSON

Em equipes com designer e programador, os tokens são guardados num arquivo JSON, que as duas pontas leem. O rascunho do grupo usa campos com cifrão, como $value e $type. Um exemplo de forma, adaptado do próprio documento:

{
  "color": {
    "brand": {
      "$type": "color",
      "$value": { "colorSpace": "srgb", "components": [0.09, 0.27, 0.23], "hex": "#18453B" }
    }
  },
  "button": {
    "primary": { "$value": "{color.brand}" }
  }
}

Para um negócio pequeno, isso é exagero. As variáveis de CSS já resolvem. Mas é bom saber que o formato existe, caso você contrate alguém ou use uma ferramenta de design que exporte tokens.

Cinco erros ao nomear as cores do site

Nomear pelo tom no nível 2. --verde-botao vira mentira quando o botão muda de cor.
Criar token demais. Não precisa de 80 nomes para um site de cinco páginas. Dez a quinze bastam.
Misturar HEX solto com tokens. Basta um HEX esquecido para o site ficar inconsistente.
Esquecer dos estados. Hover, foco e desativado também precisam de cor. Veja contraste em botões, ícones e campos.
Não anotar. Um token sem descrição ninguém sabe quando usar.

Quando vale a pena adotar tokens

Se você tem uma só página e três cores, anote os HEX numa lista e pronto. A partir de duas páginas, ou de duas pessoas mexendo no visual, os tokens se pagam rápido. Eles também ajudam na identidade visual básica, porque transformam a lista de cores em algo que o código entende. Para começar, crie só três papéis, fundo, texto e botão, e troque os HEX soltos por eles.