Como construir uma ferramenta de visualização de token de design com Node.js

Os tokens de design oferecem às equipes de desenvolvimento uma linguagem compartilhada para cores, espaçamento, tipografia, bordas e outras decisões de interface. Em vez de inserir repetidamente valores como #2563eb ou 1.5remos desenvolvedores usam nomes significativos, como color-primary e space-large.

Os tokens melhoram a consistência, mas mantê-los torna-se difícil à medida que o sistema de design cresce. Um desenvolvedor pode inserir uma cor inválida, reutilizar um nome de token ou atualizar o arquivo de token sem regenerar o CSS consumido pelo aplicativo.

Neste tutorial, construiremos uma pequena ferramenta Node.js que:

• Lê tokens de design do JSON.
• Valida seus nomes e valores.
• Gera propriedades personalizadas CSS.
• Cria uma visualização HTML visual.
• Fornece a visualização por meio de um servidor Node.js local.

O aplicativo usa módulos Node.js integrados, portanto, não requer uma estrutura web.

Crie o projeto

Crie um novo diretório com a seguinte estrutura:

design-token-preview/ ├── data/ │ └── tokens.json ├── public/ ├── src/ │ ├── build.js │ └── server.js └── package.json

Adicione isto package.json arquivo:

{ "name": "design-token-preview", "version": "1.0.0", "type": "module", "scripts": { "build": "node src/build.js", "start": "node src/server.js" } }

O projeto utiliza módulos ES, permitindo-nos importar funções Node.js com sintaxe moderna.

Defina os tokens de design

Adicione o seguinte conteúdo a data/tokens.json:

{ "colors": { "primary": "#2563eb", "primary-dark": "#1e40af", "surface": "#ffffff", "surface-muted": "#f1f5f9", "text": "#0f172a", "text-muted": "#475569", "danger": "#dc2626" }, "spacing": { "small": "0.5rem", "medium": "1rem", "large": "1.5rem", "xlarge": "2rem" }, "radius": { "small": "0.25rem", "medium": "0.5rem", "large": "1rem" } }

Agrupar tokens por finalidade facilita a leitura do arquivo. O aplicativo converterá um valor como colors.primary na variável CSS --colors-primary.

Em um sistema de design maior, você pode criar grupos adicionais para tipografia, sombras, pontos de interrupção, transições e valores específicos de componentes.

Leia e valide o arquivo de token

Criar src/build.js:

import { readFile, writeFile, mkdir } from "node:fs/promises"; const tokenFile = new URL( "../data/tokens.json", import.meta.url ); const outputDirectory = new URL( "../public/", import.meta.url ); function isValidTokenName(name) { return /^(a-z)(a-z0-9-)*$/.test(name); } function isValidColor(value) { return /^#(0-9a-f){6}$/i.test(value); } function isValidLength(value) { return /^-?\d*\.?\d+(px|rem|em|%)$/.test(value); } function validateTokens(tokens) { const errors = (); for (const (groupName, group) of Object.entries(tokens)) { if (!isValidTokenName(groupName)) { errors.push( `Invalid group name: "${groupName}"` ); } if ( typeof group !== "object" || group === null || Array.isArray(group) ) { errors.push( `Token group "${groupName}" must be an object.` ); continue; } for (const (tokenName, value) of Object.entries(group)) { if (!isValidTokenName(tokenName)) { errors.push( `Invalid token name: "${groupName}.${tokenName}"` ); } if (typeof value !== "string") { errors.push( `${groupName}.${tokenName} must be a string.` ); continue; } if (groupName === "colors" && !isValidColor(value)) { errors.push( `${groupName}.${tokenName} must use a six-digit hex color.` ); } if ( ("spacing", "radius").includes(groupName) && !isValidLength(value) ) { errors.push( `${groupName}.${tokenName} must be a CSS length.` ); } } } if (errors.length > 0) { throw new Error( `Token validation failed:\n- ${errors.join("\n- ")}` ); } }

A validação evita que valores malformados cheguem silenciosamente ao CSS de produção. As regras atuais são intencionalmente limitadas, mas criam uma base útil.

Para um sistema de produção, você pode usar o esquema JSON ou uma biblioteca de validação para impor regras mais detalhadas.

Gerar propriedades personalizadas CSS

Adicione esta função a src/build.js:

function createCss(tokens) { const declarations = (); for (const (groupName, group) of Object.entries(tokens)) { for (const (tokenName, value) of Object.entries(group)) { declarations.push( ` --${groupName}-${tokenName}: ${value};` ); } } return `:root {\n${declarations.join("\n")}\n}\n`; }

O CSS gerado ficará assim:

:root { --colors-primary: #2563eb; --colors-primary-dark: #1e40af; --spacing-medium: 1rem; --radius-medium: 0.5rem; }

Propriedades personalizadas CSS podem ser usadas em todo um aplicativo:

.button { padding: var(--spacing-small) var(--spacing-medium); border: 0; border-radius: var(--radius-medium); color: var(--colors-surface); background: var(--colors-primary); } .button:hover { background: var(--colors-primary-dark); }

A alteração do token de origem atualiza todos os componentes que fazem referência à variável correspondente.

Um documentado guia de estilo web pode complementar este sistema explicando quando tokens e componentes devem ser usados.

Gere a visualização HTML

Uma visualização visual ajuda designers e desenvolvedores a identificar alterações inesperadas antes da publicação dos tokens.

Adicione a seguinte função:

function createPreview(tokens) { const colorCards = Object.entries(tokens.colors) .map(((name, value)) => `

class="color-swatch" style="background: ${value}" aria-label="${name}: ${value}" >

${name} ${value} `) .join(""); return `