Início / Tokens / Tokens

Tokens

Tokens são variáveis que armazenam valores de design. A separação chave é entre significado e valor:

O que são tokens

Um token é uma variável que armazena um valor de design. A separação chave é entre significado e valor:

  • Significado: --color-surface — o que o token representa
  • Valor: #f4f4f5 — a cor real que aparece na tela

Por que isso importa? Se você decide que a cor de superfície precisa ser um tom mais claro, muda um valor e todo o sistema atualiza. Sem tokens, você precisaria encontrar e substituir cada uso de #f4f4f5 no código.

Três camadas

Tokens seguem uma hierarquia. Do mais abstrato ao mais concreto:

1. Primitivo

Valores brutos da paleta. Cor, número, fonte. Não têm significado semântico.

:root {
  /* Cores */
  --color-zinc-50: #fafafa;
  --color-zinc-100: #f4f4f5;
  --color-zinc-200: #e4e4e7;
  --color-zinc-300: #d4d4d8;
  --color-zinc-400: #a1a1aa;
  --color-zinc-500: #71717a;
  
  /* Espaçamento */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-4: 1rem;
}

2. Semântico

Conecta intenção a valor. O primitivo ganha significado.

:root {
  /* Significado mapeado para primitivo */
  --background: var(--color-zinc-50);
  --surface: var(--color-zinc-100);
  --surface-highlight: var(--color-zinc-200);
  --foreground: var(--color-zinc-900);
  --foreground-muted: var(--color-zinc-500);
  --border: var(--color-zinc-300);
  --border-highlight: var(--color-zinc-400);
}

3. Componente

Onde o token é aplicado. O componente usa o token semântico.

.button {
  background: var(--primary);
  color: var(--primary-foreground);
  border: 1px solid var(--border);
}

.card {
  background: var(--surface);
  border: 1px solid var(--border);
}

Nomenclatura

Formato recomendado: [propriedade]-[contexto]-[estado]

  • --color-background — cor de fundo base
  • --color-surface-highlight — cor de superfície em destaque
  • --color-foreground-muted — texto secundário
  • --color-border — cor de borda

Evitar primitivo no nome: --blue-500, --gray-200. Esses são valores, não significados.

Escala de tokens

Cada categoria tem uma escala definida. Não inventar valores — seguir a escala.

Cores (zinc)

Do design ao código

Fluxo completo: Figma → Tokens → Componente

No Figma

  • Cores nomeadas semanticamente em variáveis locais
  • Typography styles para cada nível
  • Auto layout com spacing consistente

No código (CSS)

  • Definir variáveis em globals.css
  • Mapear primitivo para semântico
  • Dark mode: trocar valor da variável, não do componente

No React

  • Componente usa token, não valor hardcoded
  • Exemplo: className="bg-[var(--surface)]"
  • Dark mode funciona automatico
/* Light mode */
:root {
  --background: #ffffff;
  --foreground: #09090b;
}

/* Dark mode */
.dark {
  --background: #09090b;
  --foreground: #fafafa;
}

/* Componente usa o token — não sabe qual modo está ativo */
.card {
  background: var(--background);
  color: var(--foreground);
}

A decisão

Neste guia, tokens semânticos são a base. Nunca use primitivo diretamente em componente. Sempre passe pelo token semântico. Isso garante:

  • Consistência visual
  • Manutenção simplificada
  • Dark mode sem variantes de componente
  • Designer e dev conseguem se comunicar na mesma língua
Anterior

Tabs