Tokens de design como fonte de verdade: cores, tipografia, espaçamentos e raio

Tokens de design são valores nomeados que representam decisões visuais do sistema (por exemplo, uma cor de texto, um tamanho de fonte, um espaçamento entre elementos). Eles funcionam como uma fonte de verdade porque substituem escolhas “soltas” (como “coloca um cinza aqui” ou “usa 16px”) por referências consistentes e rastreáveis. Em vez de repetir valores em dezenas de componentes, você referencia tokens; quando o token muda, todo o sistema pode ser atualizado de forma controlada.

Na prática, tokens conectam design e implementação: no Figma, eles aparecem como estilos e variáveis; no código, viram constantes (JSON, CSS variables, Swift/Android resources). O ponto central é que o token não é “o valor em si”, mas a decisão: “cor de texto padrão”, “espaçamento entre itens”, “raio de borda de cards”. O valor pode variar por tema (claro/escuro) ou por plataforma, mas o significado permanece.

O que torna tokens uma “fonte de verdade”

Uma fonte de verdade precisa ser: (1) única, (2) reutilizável, (3) versionável e (4) capaz de representar variações (temas, modos, densidades). Tokens atendem a esses critérios quando você evita duplicações e cria uma camada semântica entre o valor bruto e o uso final.

• Única: cada decisão tem um token correspondente, evitando múltiplos estilos para a mesma intenção.
• Reutilizável: componentes referenciam tokens em vez de valores diretos.
• Versionável: mudanças são feitas no token, com impacto previsível e auditável.
• Variável: o mesmo token semântico pode apontar para valores diferentes em temas (ex.: light/dark) sem alterar componentes.

Um erro comum é criar tokens apenas como “paleta de cores” ou “tabela de espaçamentos” e continuar aplicando valores manualmente nos componentes. Para ser fonte de verdade, o token precisa ser a referência aplicada no dia a dia.

Tipos de tokens: base, semânticos e de componente

Uma estrutura prática separa tokens em camadas, cada uma com um propósito claro. Isso reduz acoplamento e facilita mudanças.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

1) Tokens base (primitivos)

São valores brutos, geralmente ligados à identidade visual e à escala: cores da paleta, tamanhos de fonte, escala de espaçamento, raios. Eles não dizem “onde usar”, apenas “o que existe”. Exemplos: blue-500, gray-900, space-16, radius-8, font-size-14.

2) Tokens semânticos

Mapeiam intenção de uso. Em vez de “gray-900”, você usa “text-primary”. Em vez de “blue-600”, “action-primary”. Essa camada é a mais importante para manter consistência e permitir temas. Exemplos: text-primary, surface-default, border-subtle, spacing-content, radius-control.

3) Tokens de componente (quando necessário)

São específicos para um componente e devem ser usados com parcimônia. Eles existem quando o componente precisa de uma decisão própria que não deve “vazar” como regra global. Exemplo: button-padding-x, chip-radius. Se você perceber que vários componentes começam a usar o mesmo token de componente, ele provavelmente deveria virar um token semântico.

Cores como tokens: do valor ao significado

Cores são onde a diferença entre “paleta” e “sistema” fica mais evidente. Uma paleta descreve cores; tokens descrevem decisões de interface. O objetivo é que designers e devs conversem em termos de intenção: “texto secundário”, “fundo elevado”, “borda sutil”, “estado de erro”.

Passo a passo: criando tokens de cor no Figma com variáveis

O fluxo abaixo descreve um caminho prático usando variáveis (quando disponíveis) para suportar temas. Ajuste conforme sua versão do Figma e políticas do seu time.

• 1) Defina a escala base: crie uma coleção de variáveis para cores base (primitivas). Exemplo de grupos: Neutral, Brand, Success, Warning, Danger. Dentro de cada grupo, crie níveis (ex.: 50, 100, 200… 900).
• 2) Crie modos (temas): na mesma coleção, crie modos como Light e Dark. Para tokens base, você pode manter os mesmos valores nos dois modos (se a paleta for fixa) ou ajustar se sua paleta muda por tema.
• 3) Crie uma coleção semântica: crie outra coleção de variáveis para tokens semânticos (ex.: Semantic). Nela, crie variáveis como text/primary, text/secondary, surface/default, surface/raised, border/subtle, action/primary, action/primary-hover, feedback/error.
• 4) Faça o mapeamento: em cada modo (Light/Dark), aponte os tokens semânticos para os tokens base correspondentes. Exemplo: no Light, text/primary → Neutral/900; no Dark, text/primary → Neutral/50. Assim, componentes não precisam saber de paleta, apenas de semântica.
• 5) Aplique nos componentes: em vez de escolher uma cor manualmente, selecione o preenchimento/traço/texto e vincule à variável semântica. Faça isso em estados (default/hover/disabled) e em variantes.
• 6) Valide contraste: para cada par relevante (texto sobre superfície, ícone sobre botão, borda sobre fundo), verifique contraste. Se o contraste falhar, ajuste o mapeamento semântico (por exemplo, text/secondary pode precisar de um neutral diferente no modo escuro).

Exemplo de mapeamento (conceitual) entre base e semântico:

Base (primitivos)              Semântico (intenção) - Light           Semântico (intenção) - Dark Neutral/50  = #F8F9FB         text/primary  = Neutral/900           text/primary  = Neutral/50 Neutral/200 = #E3E6EA         text/secondary= Neutral/700           text/secondary= Neutral/200 Neutral/900 = #111418         surface/default = Neutral/50          surface/default = Neutral/900 Brand/600   = #2F6BFF         action/primary = Brand/600            action/primary = Brand/500 Danger/600  = #D92D20         feedback/error = Danger/600           feedback/error = Danger/500

Note que o token semântico pode apontar para níveis diferentes por tema. Isso é o que viabiliza “fonte de verdade” sem duplicar componentes.

Boas práticas para cores

• Evite tokens semânticos genéricos demais: primary sozinho é ambíguo. Prefira text/primary, action/primary, surface/primary.
• Modele estados: para ações, crie tokens para default, hover, pressed, disabled, focus. Isso evita “inventar” variações em cada componente.
• Separe superfície, texto e borda: a mesma cor raramente serve para tudo. Tokens diferentes ajudam a manter contraste e hierarquia.

Tipografia como tokens: consistência de leitura e hierarquia

Tipografia em tokens vai além de “tamanho de fonte”. Um estilo tipográfico é a combinação de família, peso, tamanho, altura de linha, espaçamento entre letras e, às vezes, transformação (uppercase) e decoração. Para ser fonte de verdade, você precisa definir uma escala e nomear intenções: títulos, corpo, legenda, etc.

Passo a passo: definindo tokens tipográficos

• 1) Defina a família (ou famílias): crie tokens base para família (ex.: font/family/sans, font/family/mono). Se houver fallback, documente a pilha.
• 2) Defina pesos disponíveis: tokens base para pesos (ex.: font/weight/regular, font/weight/medium, font/weight/semibold).
• 3) Crie uma escala de tamanhos: tokens base como font/size/12, font/size/14, font/size/16, font/size/20, font/size/24, etc. Evite muitos tamanhos próximos; uma escala enxuta facilita consistência.
• 4) Defina alturas de linha: tokens base para line-height (ex.: line/height/16, line/height/20, line/height/24, line/height/32). Uma regra prática é manter line-height proporcional ao tamanho, mas com exceções para títulos.
• 5) Crie tokens semânticos de texto: combine os base em estilos semânticos como type/heading/lg, type/heading/md, type/body/md, type/body/sm, type/caption.
• 6) Aplique via estilos/variáveis: no Figma, use estilos de texto ou variáveis (quando aplicável) para garantir que componentes e layouts usem sempre os mesmos estilos.

Exemplo de definição semântica (conceitual):

type/heading/lg: family=sans, weight=semibold, size=32, line-height=40, letter-spacing=-0.5% type/heading/md: family=sans, weight=semibold, size=24, line-height=32, letter-spacing=-0.25% type/body/md:    family=sans, weight=regular,  size=16, line-height=24, letter-spacing=0% type/body/sm:    family=sans, weight=regular,  size=14, line-height=20, letter-spacing=0% type/caption:    family=sans, weight=medium,   size=12, line-height=16, letter-spacing=0.2%

Cuidados comuns em tipografia

• Não crie um token por tela: tokens tipográficos devem representar padrões reutilizáveis, não exceções pontuais.
• Evite “quase iguais”: 15px e 16px coexistindo sem motivo tende a quebrar ritmo e alinhamento.
• Considere responsividade: se o produto precisa de escalas diferentes por breakpoint, trate isso como variação de token (por modo, coleção ou estratégia acordada com dev), não como ajustes manuais em cada componente.

Espaçamentos como tokens: ritmo, alinhamento e previsibilidade

Tokens de espaçamento definem o ritmo do layout: padding, margin, gaps, distâncias entre seções, recuos internos de componentes. Uma escala consistente reduz decisões repetitivas e melhora a legibilidade visual. Em design systems, é comum usar uma escala baseada em múltiplos (por exemplo, 4 ou 8) para facilitar cálculos e implementação.

Passo a passo: criando uma escala de espaçamento

• 1) Escolha uma unidade base: por exemplo, 4. Isso significa que a maioria dos espaçamentos será múltiplo de 4 (4, 8, 12, 16, 20…).
• 2) Defina a escala: crie tokens base como space/0, space/4, space/8, space/12, space/16, space/24, space/32, space/40, space/48, space/64. Evite uma escala longa demais; inclua apenas o que você realmente usa.
• 3) Crie tokens semânticos para contextos recorrentes: por exemplo, layout/gutter, layout/section, component/padding, component/gap, form/field-gap. Esses tokens apontam para valores da escala base.
• 4) Aplique em Auto Layout: use tokens para Padding e Spacing between items nos frames com Auto Layout. Isso garante consistência e facilita ajustes globais.
• 5) Padronize densidade (opcional): se o produto tem modo compacto/confortável, você pode criar modos (Compact/Comfortable) e mapear tokens semânticos para valores diferentes (ex.: component/padding = 12 no confortável e 8 no compacto).

Exemplo de mapeamento semântico para espaçamento:

space/8  = 8 space/12 = 12 space/16 = 16 space/24 = 24 component/padding-sm = space/8 component/padding-md = space/12 component/gap-sm     = space/8 component/gap-md     = space/12 layout/section-gap  = space/24

Erros que quebram a consistência de espaçamento

• Usar valores “quebrados” sem justificativa: 10, 18, 22 surgem quando o time ajusta “no olho”. Se for necessário, crie um token e documente o motivo, mas evite proliferar.
• Não diferenciar espaço interno e externo: padding e margin têm funções diferentes; tokens semânticos ajudam a não misturar.
• Ignorar o conteúdo: espaçamento deve considerar densidade de informação. Tokens semânticos permitem variar por contexto sem abandonar a escala.

Raio (border radius) como token: linguagem de forma

O raio de borda define a “personalidade” visual: mais quadrado, mais arredondado, mais amigável, mais técnico. Sem tokens, é comum ver botões com 6px, cards com 10px e inputs com 8px, criando ruído. Com tokens, você define uma escala e aplica por intenção.

Passo a passo: definindo tokens de raio

• 1) Defina uma escala curta: por exemplo, radius/0, radius/4, radius/8, radius/12, radius/16, radius/full (para pill/círculo).
• 2) Crie tokens semânticos: radius/control (inputs, botões), radius/card, radius/modal, radius/chip. Mapeie cada um para um valor da escala.
• 3) Aplique em componentes: vincule o raio do frame/shape ao token semântico. Para componentes com cantos diferentes (ex.: topo arredondado e base reta), mantenha a regra clara e consistente.
• 4) Considere estados e variações: normalmente o raio não muda por estado, mas pode mudar por tamanho (ex.: botão pequeno vs grande). Se isso ocorrer, crie tokens como radius/control-sm e radius/control-md.

Exemplo de escala e semântica:

radius/0    = 0 radius/4    = 4 radius/8    = 8 radius/12   = 12 radius/full = 999 radius/control = radius/8 radius/card    = radius/12 radius/chip    = radius/full

Como aplicar tokens no dia a dia sem “quebrar” componentes

Tokens só viram fonte de verdade quando estão conectados aos componentes e aos estilos usados em telas reais. A aplicação precisa ser sistemática para evitar que o arquivo acumule valores locais.

Checklist prático de aplicação

• Preenchimentos e traços: sempre use tokens semânticos (ex.: surface/default, border/subtle) em vez de escolher cores diretamente.
• Texto: aplique estilos tipográficos semânticos (ex.: type/body/md) e tokens de cor de texto (ex.: text/primary).
• Auto Layout: use tokens para padding e gap. Se um componente tem padding diferente do padrão, transforme em token semântico de componente e avalie se não deveria ser global.
• Raio: vincule o raio ao token semântico apropriado e evite ajustes manuais por instância.
• Evite overrides desnecessários: se muitas instâncias de um componente recebem override do mesmo valor, isso indica falta de token/variante.

Estratégia de evolução: como mudar tokens sem causar efeito dominó

Uma vantagem de tokens é permitir mudanças controladas, mas isso exige disciplina na forma como você introduz e altera valores.

Troca de paleta ou ajuste de contraste

Quando a paleta muda, você deve preferir alterar tokens base e, se necessário, o mapeamento semântico por tema. Componentes continuam referenciando text/primary, surface/default etc., então a mudança se propaga sem retrabalho manual.

Mudança de escala tipográfica

Se o corpo do texto passa de 16 para 15 (ou 14 para 16), altere o token base e/ou o estilo semântico correspondente (type/body/md). Evite criar um novo estilo “Body 15” apenas para uma tela; isso fragmenta o sistema.

Ajuste de densidade (compacto vs confortável)

Em vez de duplicar componentes, use modos/temas de variáveis para mapear tokens semânticos de espaçamento para valores menores/maiores. Assim, o mesmo componente se adapta ao modo sem precisar de variantes extras.

Exemplo integrado: tokens aplicados em um componente de formulário

Considere um campo de texto com label, input e mensagem de ajuda/erro. Sem tokens, cada parte pode receber valores arbitrários. Com tokens, você define decisões claras:

• Label: estilo type/body/sm, cor text/secondary.
• Input (container): superfície surface/default, borda border/subtle, raio radius/control.
• Padding interno: component/padding-md.
• Gap entre label e input: form/field-gap (mapeado para space/8 ou space/12).
• Texto digitado: estilo type/body/md, cor text/primary.
• Mensagem de erro: estilo type/caption, cor feedback/error.

Quando você alterna para tema escuro, apenas o mapeamento de surface/default, text/primary, border/subtle e feedback/error muda. O componente permanece intacto.

Como preparar tokens para handoff sem ruído

Mesmo sem entrar em estrutura de arquivos ou nomenclatura avançada, há práticas que reduzem atrito com desenvolvimento: manter tokens semânticos estáveis, evitar duplicatas e garantir que cada token tenha um propósito claro. O time de dev precisa saber “qual token usar” sem interpretar intenções a cada tela.

Checklist de qualidade de tokens

• Não há dois tokens com o mesmo significado: se text/default e text/primary fazem a mesma coisa, consolide.
• Semântica cobre os principais contextos: texto, superfície, borda, ação, feedback, foco.
• Escalas são enxutas: espaço e raio com poucos degraus bem utilizados.
• Tokens são usados de verdade: componentes e telas referenciam tokens; valores locais são exceção documentada.
• Mapeamento por tema é consistente: no dark mode, superfícies e textos mantêm hierarquia (primário, secundário, desabilitado) com contraste adequado.