Design tokens: uma fonte única de verdade para cor e tipografia

Os design tokens são valores com nome para cada decisão de design que uma marca repete: cores, tipos de letra, tamanhos de texto, espaçamentos, raios de cantos, sombras e tempos de animação. Em vez de escreveres #5b21b6 numa folha de estilos, num ficheiro do Figma e numa app iOS, defines color.brand.700 uma vez, num só ficheiro, e geras a partir dele o formato de cada plataforma. Muda o token e todos os produtos se atualizam em conjunto. Essa fonte única de verdade é o ponto central.

Como é um design token

Um token tem um nome, um valor e um tipo. O formato publicado pelo W3C Design Tokens Community Group escreve-os em JSON, com propriedades que começam por um cifrão para não colidirem com nomes de grupos.

{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}

Tokens primitivos, semânticos e de componente

Uma lista plana de cores é uma paleta, não um sistema. A estrutura que aguenta anos tem três níveis, cada um a referir o de baixo. Os componentes nunca tocam em valores em bruto; pedem uma função.

{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}

Muitas equipas ficam por dois níveis, primitivo e semântico, e só acrescentam tokens de componente onde um componente realmente difere. Isso mantém o ficheiro pequeno o bastante para se perceber.

Nomear design tokens para durarem

Os nomes duram mais do que os valores. Um token chamado color.purple quebra no dia em que a marca passar a verde-azulado; um chamado color.action.primary sobrevive. Nomeia os tokens semânticos pelo papel e mantém os nomes primitivos descritivos do valor.

Escolhe um padrão, como categoria, depois papel, depois variante, depois estado, e escreve-o no teu guia de estilo da marca. A consistência na nomenclatura importa mais do que o padrão que escolhes.

Do ficheiro de tokens ao CSS e às apps

O ficheiro de tokens não é entregue tal como está. Um passo de build transforma-o no que cada plataforma precisa. O Style Dictionary é a ferramenta open source mais usada para isto, e outras leem o mesmo formato. Na web, o resultado costuma ser propriedades personalizadas CSS.

:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}

Se usas Tailwind v4, o bloco @theme é em si uma camada de tokens: cada variável --color-* transforma-se em utilitários. Cores do Tailwind mostra como ligar uma rampa de tokens a ele. O mesmo ficheiro também pode produzir constantes Swift e recursos Android, que é onde os tokens se pagam nas equipas multiplataforma.

Modo escuro e várias marcas

Como os componentes só leem tokens semânticos, um tema é apenas um conjunto diferente de valores dessa camada. O modo escuro redefine color.text.default e color.surface.page; uma segunda marca redefine color.action.primary. Nada muda nos componentes.

@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}

Implementar design tokens

1. 1

   Audita o que existe

   Reúne todas as cores, tamanhos de texto e valores de espaçamento em uso. Espera duplicados que diferem num dígito hexadecimal.

2. 2

   Define os primitivos

   Reduz-os a escalas claras. Construir rampas de cor em OKLCH mantém os passos uniformes; vê OKLCH explicado.

3. 3

   Acrescenta a camada semântica

   Nomeia papéis: texto, superfície, contorno, ação, feedback. Aponta cada um a um primitivo.

4. 4

   Automatiza o build

   Gera o CSS e os recursos das apps a partir do ficheiro no teu build, nunca à mão.

5. 5

   Protege-o

   Faz lint de valores hex em bruto nos componentes, para o código novo usar tokens desde o primeiro dia.

Os tokens mantêm o produto consistente, mas as marcas também divergem nos gráficos feitos fora dele: publicações, diapositivos, banners. Um kit de marca do Gradiently guarda as mesmas decisões, as tuas paletas de cores, tipos de letra de títulos e de texto, logótipos e voz, para os designs feitos no Estúdio combinarem. E como o Gradiently funciona dentro do ChatGPT, do Claude e de outros assistentes que suportam servidores MCP remotos, um assistente com uma chave de API limitada pode criar designs fiéis à marca a partir do mesmo espaço de trabalho. Consistência de marca trata do hábito mais amplo.