# Design tokens: uma fonte da verdade para cor e tipografia

[Canonical HTML page](https://gradiently.design/pt-br/guide/design-tokens)

Uma cor da marca que vive em quarenta arquivos vai se desviar. Um token vive em um só lugar e toda plataforma lê dele. Veja como estruturar design tokens, nomeá-los para durar e levá-los ao código e às ferramentas de design.

## The short version

- Design tokens são valores nomeados e neutros quanto à plataforma para decisões de design, como cores, famílias de fonte, tamanhos, espaçamentos, raios, sombras e tempos de movimento.
- A maioria dos sistemas de tokens usa três camadas: tokens primitivos guardam valores brutos, tokens semânticos descrevem uma finalidade e tokens de componente aplicam finalidades a partes específicas.
- O formato do W3C Design Tokens Community Group guarda os tokens como JSON com as propriedades $value e $type e referencia outros tokens com chaves.
- Ferramentas como o Style Dictionary transformam um arquivo de tokens em propriedades personalizadas do CSS, JavaScript e recursos de iOS e Android.
- Modo escuro e várias marcas viram uma questão de trocar os valores por trás dos tokens semânticos, enquanto os componentes permanecem iguais.

**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](https://www.w3.org/community/design-tokens/) os escreve em JSON, com propriedades que começam com cifrão para não colidirem com nomes de grupos.

```json
{
  "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 no formato do community group. Os grupos se aninham livremente; o caminho, como color.violet.700, vira o nome do token.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

Os tokens de cor acima como amostras. São ingredientes brutos: nada ainda diz qual é um botão ou um título.

## 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.

| Camada | Nome de exemplo | Valor | Muda quando |
| --- | --- | --- | --- |
| Primitivo | `color.violet.700` | `#6d28d9` | A paleta é redesenhada |
| Semântico | `color.action.primary` | `{color.violet.700}` | Um papel passa para outra cor |
| Semântico | `color.text.default` | `{color.ink}` | Modo escuro, uma nova marca |
| Componente | `button.primary.background` | `{color.action.primary}` | Um componente precisa de exceção |

Referências entre chaves são aliases. Mude color.violet.700 e todo token que aponta para ele acompanha.

```json
{
  "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}" }
    }
  }
}
```

Os tokens semânticos descrevem para que serve uma cor. É a camada em que designers e engenheiros devem conversar.

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.

### Nomes que envelhecem mal

- `color.purple` usado em botões
- `text.dark`, que é claro no modo escuro
- `spacing.16` usado como regra de layout
- `blue2`, `blueNew`, `blueFinal`
- `hero.gradient.lisa`, com nome de uma pessoa

### Nomes que duram

- `color.action.primary`
- `color.text.default`
- `space.section` apontando para `{space.16}`
- Uma escala numerada como `blue.100` a `blue.900`
- `gradient.hero` com seus pontos como tokens

Escolha um padrão, como categoria, depois papel, depois variação, depois estado, e registre-o no seu [guia de estilo da marca](https://gradiently.design/pt-br/guide/brand-style-guide). 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.

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

Saída gerada. Os aliases viram referências var(), então a camada semântica sobrevive até o navegador. Veja [variáveis CSS para temas](https://gradiently.design/pt-br/guide/css-custom-properties-theming).

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](https://gradiently.design/pt-br/guide/tailwind-colors) 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.

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

Duas sobrescritas, nenhuma edição de componente. Gradientes também merecem seus valores escuros; [gradientes no modo escuro](https://gradiently.design/pt-br/guide/dark-mode-gradients) explica como ajustá-los.

> **Tokens nas ferramentas de design** As Variables do Figma aceitam coleções e modos, que correspondem bem a tokens primitivos e semânticos e a temas claro e escuro. Mantenha o arquivo de tokens como fonte e sincronize com a ferramenta de design, não o contrário, ou os dois divergirão em um mês.

## Implantando design tokens

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. **Defina os primitivos** Reduza-os a escalas claras. Montar rampas de cor em OKLCH mantém os passos uniformes; veja [OKLCH explicado](https://gradiently.design/pt-br/guide/oklch-explained).
3. **Acrescente a camada semântica** Nomeie papéis: texto, superfície, borda, ação, feedback. Aponte cada um para um primitivo.
4. **Automatize o build** Gere CSS e recursos de app a partir do arquivo no seu build, nunca à mão.
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](https://gradiently.design/pt-br/guide/brand-consistency) trata do hábito mais amplo.

## FAQ

### O que são design tokens?

Valores nomeados para decisões de design, como cores, fontes, espaçamento, raios e movimento, guardados em um arquivo neutro quanto à plataforma e transformados em CSS, código de app e variáveis de ferramentas de design.

### Qual a diferença entre tokens primitivos e semânticos?

Os primitivos guardam valores brutos, como `color.violet.700`. Os semânticos descrevem uma finalidade, como `color.action.primary`, e apontam para um primitivo.

### Design tokens são a mesma coisa que variáveis CSS?

Não. Os tokens são a fonte, guardados em um formato neutro como JSON; as propriedades personalizadas do CSS são uma das saídas geradas a partir deles, ao lado das saídas para outras plataformas.

### Existe um formato padrão para design tokens?

O W3C Design Tokens Community Group publica um formato JSON que usa $value, $type e aliases entre chaves, que ferramentas como o Style Dictionary conseguem ler.

### Como os design tokens lidam com o modo escuro?

Os componentes leem tokens semânticos, e um tema escuro fornece valores diferentes para esses tokens, então os componentes não precisam de mudanças.