Atualização editorial em : fontes e exemplos revistos; a data da publicação original foi preservada.

Um arquivo JSON com cores e espaçamentos não cria variáveis CSS sozinho. Entre o dado e a interface precisa existir uma transformação verificável. Este exemplo mostra essa etapa com Node.js, sem dependências adicionais.

Tokens e propriedades CSS não são o mesmo formato

A especificação de formato do Design Tokens Community Group, versão 2025.10, descreve um formato de intercâmbio com propriedades como $type e $value. É um relatório de grupo comunitário, não uma recomendação W3C. Publicada em 28/10/2025, ela foi acrescentada nesta atualização: não estava disponível na data original deste artigo, 06/05/2025.

No navegador, as propriedades personalizadas CSS são declaradas com nomes iniciados por dois hífens e consumidas por var(). A declaração em :root permite reutilizá-las no documento, respeitando a cascata. O navegador não importa automaticamente o JSON usado abaixo.

Um conversor com contrato pequeno e explícito

O formato local deste exercício aceita somente os grupos colors e spacing, com nomes em letras minúsculas e hífens entre segmentos. Cores usam seis dígitos hexadecimais; espaçamentos usam números não negativos em px ou rem. Ele não implementa o formato DTCG, referências entre tokens ou sincronização com ferramentas de design.

Entrada, disponível em tokens.json:

{
  "colors": {
    "primary": "#007bff",
    "secondary": "#6c757d"
  },
  "spacing": {
    "medium": "16px",
    "small": "8px"
  }
}

O conversor completo valida toda a entrada antes de escrever a saída. Ordena grupos e nomes para que uma troca na ordem das chaves não gere diferenças no CSS:

const fs = require('node:fs');

function converter(tokens) {
  const objeto = valor => valor !== null && typeof valor === 'object' && !Array.isArray(valor);
  if (!objeto(tokens) || Object.keys(tokens).length === 0) throw new Error('Objeto de tokens vazio ou invalido.');
  const regras = { colors: /^#[0-9a-fA-F]{6}$/, spacing: /^(?:0|[1-9]\d*)(?:\.\d+)?(?:px|rem)$/ };
  const linhas = [];
  for (const grupo of Object.keys(tokens).sort()) {
    if (!Object.hasOwn(regras, grupo) || !objeto(tokens[grupo]) || !Object.keys(tokens[grupo]).length) {
      throw new Error(`Grupo invalido: ${grupo}`);
    }
    for (const nome of Object.keys(tokens[grupo]).sort()) {
      const valor = tokens[grupo][nome];
      if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(nome) ||
          typeof valor !== 'string' || !regras[grupo].test(valor)) {
        throw new Error(`Token invalido: ${grupo}.${nome}`);
      }
      linhas.push(`  --${grupo}-${nome}: ${valor};`);
    }
  }
  return `:root {\n${linhas.join('\n')}\n}\n`;
}

if (require.main === module) {
  try {
    if (process.argv.length !== 3) throw new Error('Uso: node converter.js tokens.json');
    process.stdout.write(converter(JSON.parse(fs.readFileSync(process.argv[2], 'utf8').replace(/^\uFEFF/, ''))));
  } catch (erro) {
    console.error(erro.message);
    process.exitCode = 1;
  }
}

module.exports = { converter };

Com Node.js 20 ou mais recente, execute os comandos a partir da raiz do repositório. A primeira linha imprime o CSS; ela não grava nem substitui uma folha de estilo:

node exemplos/design-tokens/converter.js exemplos/design-tokens/tokens.json
node --test exemplos/design-tokens/test.js

Saída para a entrada apresentada:

:root {
  --colors-primary: #007bff;
  --colors-secondary: #6c757d;
  --spacing-medium: 16px;
  --spacing-small: 8px;
}

Inclua essas declarações em uma folha de estilo carregada pela página. Uma regra consumidora poderia usar padding: var(--spacing-medium). Para verificar a transformação, altere medium para 1.5rem, execute novamente e confira que apenas essa declaração mudou.

Os testes automatizados cobrem saída determinística, propagação de uma alteração, rejeição de entradas fora do contrato e execução pela linha de comando. O código exibido é comparado ao arquivo executável durante a validação do site.

Limites

O exemplo não valida contraste, composição visual, temas ou compatibilidade com exportações de Figma. Os valores servem ao exercício, não a uma paleta recomendada. A versão anterior não guardava uma URL de fonte verificável; esta atualização substitui o relato pessoal não comprovado por documentação identificada e código conferível.