Design Systems Escaláveis — Do Figma ao Código com Design Tokens

Design systems falham quando crescem. Não por falta de documentação, mas por falta de uma estrutura que permita evolução sem regressão. Tokens de design são a camada que separa design systems que escalam daqueles que viram dívida técnica. Este artigo examina como estruturar tokens de forma semântica, sincronizar Figma com código e estabelecer um processo que mantém consistência mesmo em times distribuídos.

Por que tokens e não apenas variáveis

Variáveis de CSS e variáveis do Figma resolvem o problema superficial: centralizar um valor para reutilizá-lo. Tokens de design resolvem um problema mais profundo: expressar a intenção semântica por trás de um valor, não apenas o valor em si.

A diferença prática: `--color-blue-500: #3B82F6` é uma variável primitiva. `--color-action-primary: var(--color-blue-500)` é um token semântico. O segundo carrega significado. Quando o produto decide mudar a cor primária de ações para verde, você altera a referência em um único lugar — sem caçar usos de `#3B82F6` espalhados pela codebase.

Tokens semânticos também são a base para theming. Dark mode, temas de marca para clientes diferentes, modos de alto contraste para acessibilidade — todos se tornam configurações de tokens, não refatorações de componentes.

Hierarquia de tokens: o modelo de três camadas

A estrutura mais robusta que encontramos em projetos complexos usa três camadas distintas:

Tokens primitivos (ou de referência): valores brutos sem semântica. `color.blue.500 = #3B82F6`, `spacing.4 = 16px`, `font-size.lg = 18px`. Estes tokens nunca devem ser usados diretamente em componentes — eles existem para serem referenciados pelos tokens semânticos.

Tokens semânticos (ou de decisão): expressam intenção de uso. `color.action.default = {color.blue.500}`, `color.action.hover = {color.blue.600}`, `color.feedback.error = {color.red.500}`. São estes que os componentes consomem.

Tokens de componente (opcionais): quando um componente tem variações complexas demais para serem expressas pelos tokens semânticos, tokens específicos de componente evitam que alterações globais causem efeitos colaterais indesejados. `button.primary.background = {color.action.default}`.

Estruturar tokens no Figma com Variables

O Figma Variables (disponível desde 2023) permite mapear essa hierarquia diretamente na ferramenta de design. A configuração correta usa coleções separadas por camada:

Crie uma coleção Primitives com todos os valores brutos organizados por categoria (color, spacing, typography, radius, shadow). Crie uma segunda coleção Semantic onde cada variável referencia uma variável da coleção Primitives. Nos componentes, use apenas variáveis da coleção Semantic.

Modos do Figma (anteriormente chamados de themes) funcionam na camada semântica: você cria um modo "dark" que mapeia os mesmos tokens semânticos para valores primitivos diferentes. Um componente que usa `color.surface.default` automaticamente se adapta entre temas sem precisar de variantes duplicadas.

Sincronização Figma ↔ Código

A sincronização é onde a maioria dos design systems enfrenta atrito. O fluxo manual — designer atualiza Figma, desenvolvedor atualiza CSS manualmente — é fonte garantida de inconsistências.

A solução é automatizar a sincronização usando ferramentas como Tokens Studio for Figma (plugin) em conjunto com Style Dictionary (biblioteca de build). O fluxo funciona assim:

Os tokens são armazenados como JSON em um repositório Git. O Tokens Studio lê e escreve nesse JSON diretamente do Figma. O Style Dictionary lê o mesmo JSON e transforma os tokens em outputs para qualquer plataforma — CSS custom properties, SCSS variables, TypeScript constants, Swift, Kotlin, ou qualquer outro formato necessário.

Com esse setup, o repositório de tokens é a fonte única de verdade. Mudanças feitas no Figma geram um pull request no repositório, que passa por review e, ao ser mergeado, dispara o build que atualiza os tokens em todas as plataformas simultaneamente.

Versionamento e breaking changes

Tokens são uma API. Assim como qualquer API pública, eles precisam de semver e de um processo de depreciação para mudanças que quebram compatibilidade.

Quando um token precisa ser renomeado ou removido, o fluxo correto é: manter o token antigo como alias temporário para o novo, comunicar a mudança com prazo de depreciação, e depois remover o alias após o prazo. Tokens removidos abruptamente quebram componentes silenciosamente — o browser simplesmente ignora uma custom property não definida.

Documentação que se mantém atualizada

Documentação de design system desatualizada é quase pior do que ausência de documentação. A única documentação que se mantém viva é a gerada automaticamente a partir da fonte de verdade.

Storybook integrado com o repositório de tokens exibe os componentes com os valores reais de produção. Ferramentas como Supernova ou Zeroheight podem gerar sites de documentação diretamente a partir do Figma e do repositório. O objetivo é que qualquer atualização de token se reflita automaticamente na documentação — sem passos manuais.

O processo é mais importante que a ferramenta

Qualquer stack de tokens funciona se o time tiver disciplina para segui-la. Os design systems que falham geralmente não falham por escolha errada de ferramenta — falham porque designers e desenvolvedores trabalham com fontes de verdade diferentes, ou porque não existe um processo claro para propor, revisar e aprovar mudanças nos tokens.

Estabelecer um "token RFC process" — mesmo que simples, como uma issue template no GitHub — cria o ritual necessário para que mudanças sejam discutidas antes de serem implementadas, evitando que um ajuste de cor em um componente quebre a identidade visual de uma plataforma inteira.