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

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

Uma cor de marca que vive em quarenta ficheiros acaba por divergir. Um token vive num só sítio e todas as plataformas leem a partir dele. Aqui fica como estruturar design tokens, nomeá-los para durarem e entregá-los ao código e às ferramentas de design.

## The short version

- Os design tokens são valores com nome, neutros quanto à plataforma, para decisões de design como cores, famílias de letra, tamanhos, espaçamentos, raios, sombras e tempos de movimento.
- A maioria dos sistemas de tokens usa três níveis: os tokens primitivos guardam valores em bruto, os semânticos descrevem uma função e os de componente aplicam funções a partes específicas.
- O formato do W3C Design Tokens Community Group guarda os tokens como JSON com as propriedades $value e $type e refere outros tokens com chavetas.
- Ferramentas como o Style Dictionary transformam um só ficheiro de tokens em propriedades personalizadas CSS, JavaScript e recursos de iOS e Android.
- O modo escuro e as várias marcas passam a ser uma questão de trocar os valores por trás dos tokens semânticos, enquanto os componentes ficam iguais.

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](https://www.w3.org/community/design-tokens/) escreve-os em JSON, com propriedades que começam por um 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 aninham-se livremente; o caminho, como color.violet.700, passa a ser 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 em bruto: nada diz ainda qual é um botão ou um título.

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

| Nível | 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 uma exceção |

As referências entre chavetas são aliases. Muda color.violet.700 e todos os tokens que apontam para ele acompanham.

```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 falar.

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.

### 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 o nome de uma pessoa

### Nomes que duram

- `color.action.primary`
- `color.text.default`
- `space.section` a apontar para `{space.16}`
- Uma escala numerada como `blue.100` a `blue.900`
- `gradient.hero` com as suas paragens como tokens

Escolhe um padrão, como categoria, depois papel, depois variante, depois estado, e escreve-o no teu [guia de estilo da marca](https://gradiently.design/pt-pt/guide/brand-style-guide). 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.

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

Resultado gerado. Os aliases passam a referências var(), por isso a camada semântica sobrevive até ao browser. Vê [variáveis CSS para temas](https://gradiently.design/pt-pt/guide/css-custom-properties-theming).

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

```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 substituições, nenhuma edição de componentes. Os gradientes também merecem os seus próprios valores escuros; [gradientes no modo escuro](https://gradiently.design/pt-pt/guide/dark-mode-gradients) explica como os afinar.

> **Tokens nas ferramentas de design** As Variables do Figma suportam coleções e modos, que correspondem bem aos tokens primitivos e semânticos e aos temas claro e escuro. Mantém o ficheiro de tokens como fonte e sincroniza para a ferramenta de design, não o contrário, ou os dois discordam em menos de um mês.

## Implementar design tokens

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. **Define os primitivos** Reduz-os a escalas claras. Construir rampas de cor em OKLCH mantém os passos uniformes; vê [OKLCH explicado](https://gradiently.design/pt-pt/guide/oklch-explained).
3. **Acrescenta a camada semântica** Nomeia papéis: texto, superfície, contorno, ação, feedback. Aponta cada um a um primitivo.
4. **Automatiza o build** Gera o CSS e os recursos das apps a partir do ficheiro no teu build, nunca à mão.
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](https://gradiently.design/pt-pt/guide/brand-consistency) trata do hábito mais amplo.

## FAQ

### O que são design tokens?

Valores com nome para decisões de design como cores, tipos de letra, espaçamento, raios e movimento, guardados num só ficheiro neutro quanto à plataforma e transformados em CSS, código de apps e variáveis de ferramentas de design.

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

Os tokens primitivos guardam valores em bruto, como `color.violet.700`. Os semânticos descrevem uma função, como `color.action.primary`, e apontam para um primitivo.

### Os design tokens são o mesmo que variáveis CSS?

Não. Os tokens são a fonte, guardada num formato neutro como JSON; as propriedades personalizadas CSS são um dos resultados gerados a partir deles, a par de resultados 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 com chavetas, que ferramentas como o Style Dictionary conseguem ler.

### Como tratam os design tokens o modo escuro?

Os componentes leem tokens semânticos, e um tema escuro fornece valores diferentes para esses tokens, por isso os componentes não precisam de alterações.