Design tokens: uma fonte da verdade para cor e tipografia

Design tokens são valores nomeados para cada decisão de design que uma marca repete: cores, tipografias, tamanhos de texto, espaçamentos, raios de canto, sombras e tempos de animação. Em vez de digitar #5b21b6 em uma folha de estilo, em um arquivo do Figma e em um app iOS, você define color.brand.700 uma vez, em um arquivo, e gera o formato de cada plataforma a partir dele. Mude o token e todos os produtos se atualizam juntos. Essa fonte única da verdade é o ponto central.

Como é um design token

Um token tem nome, valor e tipo. O formato publicado pelo W3C Design Tokens Community Group os escreve em JSON, com propriedades que começam com 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 simples de cores é uma paleta, não um sistema. A estrutura que se sustenta por anos tem três camadas, cada uma referindo-se à de baixo. Os componentes nunca tocam valores brutos; pedem uma finalidade.

{
  "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 equipes param em duas camadas, primitiva e semântica, e adicionam tokens de componente só onde um componente realmente difere. Isso mantém o arquivo pequeno o bastante para ser compreendido.

Nomeando design tokens para durar

Os nomes sobrevivem aos valores. Um token chamado color.purple quebra no dia em que a marca vira azul-petróleo; um chamado color.action.primary sobrevive. Nomeie os tokens semânticos pelo papel e deixe os nomes primitivos descreverem o valor.

Escolha um padrão, como categoria, depois papel, depois variação, depois estado, e registre-o no seu guia de estilo da marca. A consistência na nomenclatura importa mais que o padrão escolhido.

Do arquivo de tokens ao CSS e aos apps

O arquivo de tokens não é entregue como está. Uma etapa de build o transforma no que cada plataforma precisa. O Style Dictionary é a ferramenta open source mais usada para isso, e outras leem o mesmo formato. Na web, a saída costuma ser propriedades personalizadas do 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 você usa o Tailwind v4, o bloco @theme é em si uma camada de tokens: cada variável --color-* vira utilitários. Cores do Tailwind mostra como ligar uma rampa de tokens a ele. O mesmo arquivo também pode gerar constantes Swift e recursos Android, e é aí que os tokens se pagam em equipes multiplataforma.

Modo escuro e várias marcas

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

@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;
}

Implantando design tokens

1. 1

   Faça um levantamento do que existe

   Reúna toda cor, tamanho de fonte e espaçamento em uso. Espere duplicatas que diferem por um dígito hex.

2. 2

   Defina os primitivos

   Reduza-os a escalas claras. Montar rampas de cor em OKLCH mantém os passos uniformes; veja OKLCH explicado.

3. 3

   Acrescente a camada semântica

   Nomeie papéis: texto, superfície, borda, ação, feedback. Aponte cada um para um primitivo.

4. 4

   Automatize o build

   Gere CSS e recursos de app a partir do arquivo no seu build, nunca à mão.

5. 5

   Proteja

   Faça lint de valores hex brutos em componentes, para que o código novo use tokens desde o primeiro dia.

Os tokens mantêm o produto consistente, mas as marcas também se desviam nos gráficos feitos fora dele: posts, slides, banners. Um brand kit do Gradiently guarda as mesmas decisões, suas paletas de cores, fontes de título e de texto, logos e voz, para que os designs feitos no Studio combinem. E como o Gradiently funciona dentro do ChatGPT, do Claude e de outros assistentes que aceitam servidores MCP remotos, um assistente com uma chave de API restrita pode criar designs na marca a partir do mesmo workspace. Consistência de marca trata do hábito mais amplo.