Governança de Design Tokens: Ligar Variáveis do Figma Diretamente ao Código Astro em Produção

A morte anunciada da entrega manual (“Design Handoff”)

Qualquer designer digital conhece a frustração de inspecionar um website em produção seis meses após a entrega final dos ficheiros. Abre as ferramentas de programação do navegador no portal do cliente, seleciona o botão de ação principal e descobre que o azul-marinho da marca — calibrado ao detalhe durante semanas — se fragmentou em onze códigos hexadecimais ligeiramente diferentes espalhados por quarenta folhas de estilo. O espaçamento interno de 24px dos cartões transformou-se em 22px na página de preços e em 28px nos artigos. O tema escuro parece baço e ilegível porque um programador teve de adivinhar a cor do estado hover numa sexta-feira à noite.

Durante mais de uma década, a indústria tentou resolver este problema escrevendo documentação cada vez mais extensa. As agências entregavam manuais em PDF com noventa páginas, agendavam reuniões intermináveis de passagem de testemunho (handoff) e policiavam o código com capturas de ecrã anotadas a vermelho. Nada disto resultou.

Falhou porque copiar valores manualmente entre um ecrã de desenho visual e um repositório de código é um processo de compressão com perda de dados. Sempre que uma decisão tomada dentro do Figma exige que um ser humano leia um número no painel lateral e o volte a digitar num componente Astro ou num ficheiro CSS, a entropia vence inevitavelmente.

Na Webxtek, onde o meu trabalho em design digital e sistemas de identidade decorre lado a lado com a engenharia de sistemas, eliminámos por completo o conceito de entrega manual. Ao tratarmos o Manual de Marca e o Design Digital como uma pipeline contínua de compilação — regida pela especificação Design Tokens Community Group (DTCG) do W3C e automatizada através do Style Dictionary — uma alteração validada numa variável do Figma é compilada diretamente para variáveis nativas de CSS em produção através de um pull request automático no Git.

Porque é que a maioria das configurações de Variáveis no Figma falha antes de chegar ao código

Desde que o Figma lançou o suporte nativo para Variáveis e Modos (Variables and Modes), centenas de equipas correram a converter os seus estilos de cor em variáveis. Contudo, sempre que audito esses ficheiros no arranque de projetos de Design UX/UI, verifico que cerca de 80% são impossíveis de ligar de forma limpa ao código de produção.

Porquê? Porque o designer criou uma lista plana de variáveis batizadas segundo a aparência visual bruta (Azul-Primario, Cinzento-Claro, Espaco-16) e associou os componentes da interface diretamente a essas primitivas.

Pensa no que acontece no exato momento em que a empresa decide lançar um modo escuro de alto contraste, ou adquire uma segunda marca do grupo que precisa de partilhar a mesma arquitetura de componentes em Astro mas com uma paleta terracota em vez de azul: se o fundo do cartão estiver ligado diretamente a Cinzento-100, é impossível invertê-lo para escuro sem destruir o significado semântico do nome Cinzento-100.

Uma verdadeira Governança de Design Tokens exige uma Taxonomia Semântica de Três Níveis:

Quando impomos esta disciplina de três níveis dentro do Figma — ativando especificamente a opção “Ocultar da publicação” em todas as coleções Primitivas de Nível 1 para que os designers de produto só possam aplicar tokens Semânticos de Nível 2 aos ecrãs e à tipografia — estabelecemos um contrato inquebrável entre o design visual e a engenharia frontend.

O Contrato JSON W3C DTCG: Falar exatamente a mesma língua

Historicamente, cada ferramenta de design exportava variáveis num formato JSON proprietário e incompatível. Hoje, a norma W3C Design Tokens Community Group (DTCG) uniformizou o esquema através de chaves explícitas $value, $type e $description.

No nosso fluxo de trabalho na Webxtek, guardamos todas as primitivas cromáticas no espaço de cor percetual OKLCH em vez de códigos hexadecimais legados. Porque escolhemos OKLCH? Porque nos códigos hexadecimais sRGB tradicionais, a luminosidade matemática está desligada da perceção da retina humana. No espaço OKLCH, o primeiro canal (L, de 0 a 1) representa a claridade real percebida pelo olho humano. Se duas cores de matizes diferentes partilharem o mesmo valor L de 0.65, apresentam exatamente o mesmo rácio de contraste WCAG sobre texto branco ou preto — tornando os sistemas multimarca de Branding matematicamente previsíveis.

Vê a estrutura de um ficheiro de tokens governado segundo a norma W3C DTCG exportado a partir das nossas coleções no Figma:

{
  "$schema": "https://tr.designtokens.org/format/",
  "primitive": {
    "color": {
      "cobalt": {
        "600": {
          "$type": "color",
          "$value": "oklch(0.54 0.19 258)",
          "$description": "Azul cobalto principal da marca a 54% de luminosidade percetual"
        },
        "700": {
          "$type": "color",
          "$value": "oklch(0.46 0.18 258)"
        }
      },
      "neutral": {
        "50": { "$type": "color", "$value": "oklch(0.98 0.005 258)" },
        "950": { "$type": "color", "$value": "oklch(0.14 0.015 258)" }
      }
    }
  },
  "semantic": {
    "surface": {
      "canvas": {
        "$type": "color",
        "$value": "{primitive.color.neutral.50}",
        "$extensions": {
          "com.x078.modes": {
            "light": "{primitive.color.neutral.50}",
            "dark": "{primitive.color.neutral.950}"
          }
        }
      }
    },
    "action": {
      "primary-bg": {
        "$type": "color",
        "$value": "{primitive.color.cobalt.600}",
        "$extensions": {
          "com.x078.modes": {
            "light": "{primitive.color.cobalt.600}",
            "dark": "{primitive.color.cobalt.700}"
          }
        }
      }
    }
  }
}

Compilar Tokens para Astro e Tailwind v4 através do Style Dictionary

Depois de os tokens estarem registados em JSON válido no repositório Git, como é que se transformam em estilos de custo zero em execução dentro de um projeto Astro?

Nunca carregamos ficheiros JSON de tokens no navegador do cliente em tempo de execução — isso desperdiçaria JavaScript e atrasaria a renderização inicial da página. Em vez disso, executamos o Style Dictionary v4 durante a fase de compilação para transformar o grafo JSON diretamente em variáveis nativas de CSS (Custom Properties) e blocos @theme do Tailwind CSS v4.

Com a transição do Tailwind CSS v4 de ficheiros de configuração em JavaScript (tailwind.config.js) para uma arquitetura nativa em CSS baseada na diretiva @theme, a ponte entre as Variáveis do Figma e os componentes Astro tornou-se extraordinariamente limpa:

// scripts/compilar-tokens.mjs — Pipeline Style Dictionary 4 para Astro + Tailwind v4
import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary({
  source: ['src/tokens/**/*.tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'src/styles/generated/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: {
            outputReferences: true, // Preserva a ligação var(--primitive-color-cobalt-600)!
          },
        },
      ],
    },
  },
});

await sd.buildAllPlatforms();

Ao ativarmos outputReferences: true, o Style Dictionary emite uma folha de estilo tokens.css limpa e hierárquica que é importada diretamente no layout base do Astro. Combinada com a diretiva @theme inline do Tailwind v4, cada token semântico fica imediatamente disponível tanto como classe utilitária tipada (bg-surface-canvas, bg-action-primary) como através de variável nativa de CSS (var(--semantic-action-primary-bg)) dentro dos blocos <style> isolados dos componentes .astro — com zero bytes de sobrecarga de JavaScript no navegador.

Tipografia e espaçamentos fluidos: Superar os breakpoints estáticos

Uma das áreas onde o código em produção chocava constantemente com as pranchetas do Figma era a adaptação responsiva. No Figma, o designer desenha habitualmente dois ecrãs estáticos: um ecrã móvel de 390px onde o título principal mede 32px, e um ecrã de computador de 1440px onde o mesmo título mede 56px.

Se o programador traduzir esses dois números literalmente através de media queries (@media (min-width: 1024px)), a tipografia dá um salto brusco aos 1024px e parece desproporcionada num tablet de 768px ou numa janela dividida a meio ecrã num portátil.

Na nossa pipeline governada de tokens, o script do Style Dictionary lê os valores do modo mobile (mínimo) e do modo desktop (máximo) diretamente da coleção de Variáveis do Figma e calcula automaticamente uma rampa matemática fluida em CSS clamp():

/* Tokens Fluidos de Tipografia e Espaçamento compilados automaticamente dos Modos Min/Max do Figma */
:root {
  /* Escala suavemente de 2rem (32px) aos 390px de largura até 3.5rem (56px) aos 1440px */
  --font-size-display-xl: clamp(2rem, 1.44rem + 2.28vw, 3.5rem);
  
  /* Ritmo vertical fluido de secção: 3.5rem em telemóvel -> 7rem em desktop */
  --space-section-y: clamp(3.5rem, 2.18rem + 5.33vw, 7rem);
}

Ao gerar funções clamp() diretamente a partir dos modos móvel e desktop definidos pelo designer, o website em Astro adapta-se com fluidez contínua a qualquer largura de ecrã existente — desde telemóveis dobráveis compactos até monitores panorâmicos de estúdio — enquanto o designer no Figma só precisa de manter dois números inteiros simples.

Impor governança em CI/CD: Como travar códigos hexadecimais avulsos para sempre

Construir uma pipeline de compilação é apenas metade da solução; a governança é o que impede que um programador apressado contorne o sistema de tokens seis meses mais tarde.

Quando implementamos sistemas de Manual de Marca e bibliotecas de componentes para equipas empresariais, protegemos a ponte entre o Figma e o Astro com três barreiras automatizadas no GitHub Actions:

1. Validação Automática de Contraste e Esquema nos Pull Requests de Tokens: Sempre que um designer publica uma atualização no Figma que abre um pull request na pasta src/tokens/, um script de CI calcula automaticamente o rácio de contraste OKLCH entre cada token semântico de texto (color.text.*) e o respetivo token de superfície (color.surface.*) tanto no Modo Claro como no Modo Escuro. Se uma alteração reduzir acidentalmente o contraste abaixo do nível WCAG AA (4.5:1), o pull request é bloqueado automaticamente antes mesmo da revisão humana.
2. Proibição de Valores Fixos no Linter: Configuramos o stylelint (e o oxlint nos componentes Astro/JSX) com regras estritas (color-no-hex, scale-unlimited/declaration-strict-value) que interrompem a compilação se qualquer programador escrever um código #hex, rgb() ou medida arbitrária [17px] fora do ficheiro gerado tokens.css.
3. Limpeza de Tokens Órfãos: Durante o build do Astro, verificamos se todos os tokens de Componente de Nível 3 criados no Figma estão efetivamente a ser utilizados na biblioteca de código, impedindo a acumulação de CSS morto ao longo dos anos.

A vantagem competitiva em 2026–2030: Uma única fonte de verdade

Considera o ganho operacional desta arquitetura. Quando uma marca evolui — seja para afinar uma cor de destaque por exigência da Lei Europeia da Acessibilidade, lançar uma campanha sazonal ou criar um novo portal para o mercado internacional — deixam de existir maratonas de quarenta horas a procurar e substituir códigos de cor em centenas de ficheiros. O responsável de design atualiza a coleção semântica, valida os testes automáticos de contraste, aprova o pull request e o Astro recompila toda a plataforma em noventa segundos.

O design e a engenharia nunca deveriam ter sido dois departamentos rivais a atirar desenhos estáticos por cima de um muro. Ao ancorar os teus projetos de Design UX/UI e Design Digital numa governança rigorosa de Design Tokens do W3C, o teu ficheiro no Figma e o teu código em produção passam a ser duas vistas exatas da mesma verdade.

Na prática, aplicas exatamente estes padrões operacionais em setores exigentes como design de interiores e decoração e design de joias e acessórios personalizados. Quando alinhas a tua estrutura através de branding e rebranding para marcas mais claras e fortes e Design UX/UI, transformas boas práticas técnicas numa vantagem competitiva real e mensurável para o teu negócio.