Design tokens: a ponte entre Figma e código

O que são design tokens

Você já sabe o que é um design system. Mas como ele viaja do Figma até o código do desenvolvedor sem se perder no caminho? A resposta são os design tokens.

Design tokens são as decisões de design traduzidas em valores reutilizáveis. Em vez de você dizer "a cor primária é aquele azul que eu usei no botão", você define um token: --color-primary: #1976D2. Esse mesmo token aparece como variável no Figma, como variável CSS no código, como recurso no Android. Muda em um lugar, muda em todos.

Os tokens não se limitam a cores. Eles cobrem tipografia (--font-size-body: 16px), espaçamento (--spacing-md: 16px), bordas, sombras, animações. É a linguagem compartilhada entre design e desenvolvimento. Em 2026, design tokens já fazem parte do vocabulário comum entre design e código, e dominar esse conceito coloca você na conversa onde as decisões acontecem.

CSS custom properties: tokens em ação

Na web, design tokens se materializam como CSS custom properties (variáveis CSS). Pense comigo: em vez de espalhar o valor #3b82f6 em 47 lugares diferentes do código, você define uma vez:

:root {
  --color-accent: #3b82f6;
  --spacing-md: 1.25rem;
  --font-heading: Georgia, serif;
}

E depois usa em qualquer lugar: color: var(--color-accent). O dia que a equipe decide mudar o azul para roxo, você muda um número. Um. E os 47 lugares se atualizam sozinhos. Isso é o poder dos tokens.

Tokens primitivos vs. tokens semânticos

Agora que você entende o que são tokens e como eles funcionam no CSS, vamos a uma distinção que separa design systems amadores dos profissionais: a diferença entre tokens primitivos e tokens semânticos.

Tokens primitivos são valores crus, diretos, sem contexto. Eles descrevem o que o valor é, não para que ele serve:

--blue-500: #3b82f6;
--blue-100: #e0e7ff;
--spacing-4: 16px;
--spacing-8: 32px;
--gray-700: #374151;

Tokens semânticos são valores com significado contextual. Eles descrevem o papel que aquele valor desempenha na interface, e referenciam tokens primitivos:

--color-primary: var(--blue-500);
--color-primary-light: var(--blue-100);
--spacing-card: var(--spacing-4);
--spacing-section: var(--spacing-8);
--color-text-body: var(--gray-700);

A diferença parece sutil, mas o impacto é enorme. Imagine que sua equipe decide mudar a cor primária da marca de azul para roxo. Com tokens semânticos, você muda uma linha: --color-primary: var(--purple-500). Todos os botões, links, ícones de destaque e barras de progresso que usam --color-primary se atualizam automaticamente, em todas as telas, em todas as plataformas. Sem tokens semânticos, você precisaria buscar e substituir #3b82f6 em dezenas ou centenas de lugares, e inevitavelmente ia esquecer um.

A camada semântica também resolve outro problema: temas. Um token como --color-background pode apontar para --white no modo claro e --gray-900 no modo escuro. O componente não precisa saber em qual modo está, ele só referencia --color-background e o sistema resolve o resto.

{
  "color": {
    "primary": {
      "$value": "#1976D2",
      "$type": "color",
      "$description": "Cor principal da marca"
    }
  }
}

Figma Variables e design tokens

Se você usa o Figma (e provavelmente usa), você já deve ter notado as Variables. Tokens são como variáveis no Figma, se você já usou Figma Variables, você já está usando tokens sem saber. Introduzidas em 2023 e expandidas desde então, as Figma Variables são a versão visual dos design tokens. Elas permitem que você defina valores de cor, número, string e booleano e os reutilize em todo o seu arquivo.

A conexão direta entre Figma Variables e design tokens é o que torna esse recurso tão poderoso. Veja como funciona na prática:

• Você cria uma Variable chamada color/primary no Figma com o valor #1976D2.
• Essa Variable é aplicada ao fundo dos seus botões, aos links, aos ícones de destaque.
• Na hora do handoff, ferramentas como Tokens Studio exportam essa Variable como --color-primary: #1976D2 no CSS, R.color.primary no Android, Color.primary no SwiftUI.

O Figma também suporta modes (modos), que são perfeitos para lidar com temas. Uma mesma Variable color/background pode ter o valor #FFFFFF no modo Light e #111827 no modo Dark. O designer muda o modo no Figma e vê o layout se transformar instantaneamente. O desenvolvedor recebe os dois valores mapeados para media queries ou classes de tema.

E aqui vai um ponto que eu quero que você grave: quando Figma Variables e design tokens estão alinhados, o handoff entre design e desenvolvimento deixa de ser aquele PDF estático com anotações manuais. Ele vira um fluxo automatizado onde as decisões de design já chegam no código no formato certo. Menos atrito, menos erro, mais velocidade.

Interoperabilidade: tokens que funcionam em qualquer plataforma

Um dos maiores desafios dos times de produto modernos é a consistência entre plataformas. O seu app precisa ter a mesma cara no iPhone, no Android e no navegador. Mas cada plataforma fala uma "língua" diferente: CSS na web, XML no Android, Swift no iOS, Dart no Flutter.

É aqui que a interoperabilidade dos design tokens brilha. Com uma pipeline bem configurada, o fluxo funciona assim:

1. Definição: o designer define os tokens no Figma (via Variables) ou em um arquivo JSON seguindo a spec W3C.
2. Transformação: uma ferramenta como Style Dictionary pega esse arquivo e gera os formatos de cada plataforma automaticamente.
3. Consumo: cada time de desenvolvimento usa os tokens no formato nativo da sua plataforma, sem precisar traduzir manualmente.
4. Sincronização: quando um token muda (por exemplo, a cor primária é atualizada), a pipeline roda novamente e todas as plataformas recebem a atualização.

Para você como designer, isso significa uma coisa muito concreta: você muda um valor no Figma e essa mudança se propaga para todas as plataformas. Não é mágica, é infraestrutura. Mas precisa de alinhamento entre design e engenharia para funcionar. E o designer que entende esse fluxo vira a pessoa que conecta os dois mundos.

Quando tokens quebram

Tudo isso parece lindo na teoria. Mas e quando dá errado? Vou te contar dois cenários que acontecem com frequência em times reais, para que você entenda por que tokens sem governança são apenas variáveis com nomes bonitos.

Caso 1: a renomeação que ninguém avisou

Imagine o seguinte cenário: o time de design decide reorganizar a nomenclatura dos tokens. O que era --color-brand-primary vira --color-action-main. Faz sentido semanticamente, a nova nomenclatura é mais clara. O problema? A atualização foi feita no Figma e no código da web, mas o time de iOS não foi avisado. O app continuou referenciando o token antigo, que ainda existia no arquivo JSON como um legado. Resultado: durante duas semanas, o aplicativo iOS mostrou cores antigas, as do token que não tinha sido removido, porque ninguém percebeu a discrepância. Os usuários de iPhone viram um app com a identidade visual de dois meses atrás, enquanto web e Android já mostravam a nova paleta.

Esse tipo de problema é silencioso. Não gera erro, não quebra build, não aparece em nenhum teste automatizado. Só aparece quando alguém compara as plataformas lado a lado e percebe que as cores estão diferentes. E até lá, a marca ficou inconsistente para milhares de usuários.

Caso 2: token primitivo sem camada semântica

Outro cenário comum: o time usava tokens primitivos diretamente nos componentes. O botão primário usava --blue-500, o link usava --blue-500, mas o estado de erro também usava --blue-500 com uma variante mais escura, --blue-700. Um dia, a equipe de marca decidiu mudar o azul primário para um tom mais vibrante. Atualizaram --blue-500 e --blue-700. Resultado: os botões ficaram lindos, os links ficaram ótimos, mas os estados de erro, que deveriam ser vermelhos e distintos, também mudaram de tom, porque referenciavam tokens primitivos sem nenhuma camada semântica que os diferenciasse por função.

Se tivessem usado tokens semânticos, --color-action-primary e --color-feedback-error, mesmo que ambos apontassem para tons de azul inicialmente, a mudança teria sido isolada: atualizar a cor primária não teria arrastado os estados de erro junto.

A lição desses dois casos é direta: tokens sem governança são variáveis com nomes bonitos. A diferença entre um design system amador e um profissional não está na quantidade de tokens, está no processo que garante que eles sejam atualizados de forma coordenada, versionados de forma rastreável e consumidos de forma consistente em todas as plataformas. O token é a decisão. A governança é o que garante que a decisão seja respeitada.

IA e design systems: o que já está mudando

Agora vamos ao tema que está na boca de todo mundo. Como a inteligência artificial está se conectando com design systems? De várias formas, e algumas já são realidade no dia a dia.

A primeira e mais visível: geração automática de componentes. Ferramentas como o Figma AI e plugins baseados em modelos generativos já conseguem criar variações de componentes a partir de um design base. Você define um botão primário e a IA sugere o secundário, o terciário, o estado disabled, o estado de loading. Não substitui o designer, mas acelera o trabalho mecânico.

A segunda: sugestão de valores de tokens. Dado um token de cor primária, a IA pode sugerir a paleta completa de suporte (cores secundárias, tons de superfície, cores de texto com contraste adequado). Ela calcula ratios de contraste WCAG automaticamente e propõe alternativas acessíveis. É como ter um assistente que entende tanto de estética quanto de acessibilidade.

A terceira: auditoria automatizada. Modelos de IA já conseguem analisar um design system inteiro e identificar inconsistências: tokens definidos mas não utilizados, componentes que usam valores hardcoded em vez de tokens, cores que não atendem o contraste mínimo. Esse tipo de auditoria que um humano levaria dias para fazer, a IA faz em minutos. A pergunta que fica é: como você pode usar essas ferramentas a seu favor, gastando menos tempo no trabalho repetitivo e mais no que só um designer humano enxerga?