Pular para o conteúdo principal

Entendendo os Tokens Gerados

Público​

Este artigo é para desenvolvedores que rodaram o engine — seja npm run tokens:build concluiu com sucesso, ou eles têm uma pasta dist/ nova — e querem entender o que foi gerado, como navegar e quais tokens usar em cada caso.

O que o engine gerou​

Após um tokens:build bem-sucedido, dois diretórios existem no seu projeto:

data/ — dados intermediários do pipeline​

Nunca use isso diretamente. É o estado de trabalho do engine entre as etapas do pipeline:

data/
├── brand/<marca>/        ← Paletas de cores decompostas por marca
├── mode/                 ← Modulação de luminosidade light/dark
├── surface/              ← Contexto de surface positiva/negativa
├── dimension/            ← Escala espacial e tipográfica
├── semantic/             ← Definições de tokens com propósito
└── foundation/<nome>/    ← Definições de aliases Foundation

Arquivos em data/ são gerados. Qualquer edição manual é sobrescrita na próxima build.

dist/ — output para consumidores​

É isso que você importa nas suas aplicações:

dist/
├── json/
│   ├── <marca>-light-positive-semantic.json
│   ├── <marca>-light-positive-foundation.json
│   ├── <marca>-dark-positive-semantic.json
│   └── ...
├── css/
│   ├── semantic/<marca>-light-positive.css
│   └── foundation/<marca>/foundation.css
├── esm/
│   ├── <marca>-light-positive-semantic.mjs
│   └── foundation/<marca>/foundation.mjs
├── js/
│   ├── <marca>-light-positive-semantic.js
│   └── foundation/<marca>/foundation.cjs
└── dts/
    └── ...

Convenção de nomenclatura dos arquivos​

Os arquivos de output seguem o padrão: {marca}-{mode}-{surface}-{camada}.{ext}

SegmentoValoresSignificado
marcanome da sua marcaA marca configurada (ex.: aplica_joy)
modelight, darkContexto de luminosidade
surfacepositive, negativePolaridade de surface (positive = padrão, negative = invertida)
camadasemantic, foundationQual camada de token (omitido no CSS, ambas as camadas em um arquivo)

Exemplo: aplica_joy-dark-positive-semantic.mjs — brand Aplica Joy, dark mode, surface positiva, camada semântica, formato ESM.

Duas camadas de token: quando usar cada uma​

Semantic (semantic.*)​

Tokens com propósito que codificam para que serve um token. Cada nome de token descreve seu papel na UI — não seu valor visual.

semantic.color.interface.function.primary.normal.background
         │      │         │        │       │      └─ propriedade
         │      │         │        │       └─ intensidade (lowest/normal/highest)
         │      │         │        └─ categoria de cor (function, feedback, brand, text...)
         │      │         └─ grupo semântico (interface, ambient, gradient...)
         │      └─ tipo (color, dimension, typography, border, depth...)
         └─ namespace

Use Semantic quando:

  • Estiver construindo componentes do design system (botões, inputs, cards)
  • Precisar de um token específico que Foundation não expõe
  • Precisar do conjunto completo de variantes (intensidades lowest/normal/highest)

Foundation (foundation.*)​

Aliases simplificados que apontam para tokens Semantic. Os nomes Foundation são intencionalmente curtos e descritivos para times de produto.

foundation.bg.primary          → semantic.color.interface.function.primary.normal.background
foundation.txt.body            → semantic.color.text.body.default
foundation.spacing.medium      → semantic.dimension.spacing.medium

Use Foundation quando:

  • Estiver construindo funcionalidades de produto (telas, fluxos, conteúdo)
  • Quiser nomes mais curtos com menos carga cognitiva
  • O token que precisa tem um alias Foundation

Regra: Foundation é um atalho para Semantic, não o substitui como fonte de verdade. Se não existe um alias Foundation para o seu caso, use Semantic diretamente.

Convenções de nomenclatura de tokens​

Nomenclatura de CSS custom properties​

O separador ponto nos caminhos de token vira hífen no CSS:

semantic.color.interface.function.primary.normal.background
→ --semantic-color-interface-function-primary-normal-background

foundation.bg.primary
→ --foundation-bg-primary

camelCase em JavaScript​

Objetos ESM/CJS usam camelCase para segmentos com múltiplas palavras:

// Caminho do token: semantic.color.interface.function.primary.normal.background
semantic.color.interface.function.primary.normal.background

// Caminho do token: foundation.bg.primary
foundation.bg.primary

Categorias de cor​

CategoriaCaminhoContém
Função de interfacesemantic.color.interface.function.*Ações primária, secundária, link
Feedback de interfacesemantic.color.interface.feedback.*Info, success, warning, danger
Brandingsemantic.color.brand.*Brand first, second, third
Textosemantic.color.text.*Body, heading, muted, disabled
Ambientsemantic.color.ambient.*Cores de background, overlay
Productsemantic.color.product.*Promo, cashback, premium

Propriedades de cor por token​

Cada token de cor expõe quatro propriedades (desde 3.6.0 — eram três antes):

PropriedadeDescrição
backgroundCor de preenchimento (surfaces, badges, botões)
txtOnCor de texto/ícone que passa WCAG sobre background
borderCor de borda com contraste adequado em relação à surface
txtCor de texto legível sobre canvas — para fluxo de conteúdo, não sobre backgrounds coloridos. Veja 07-txt-token.

Exemplo: semantic.color.interface.function.primary.normal.background → #C40145

Níveis de intensidade​

A maioria dos grupos de cor expõe três níveis de intensidade:

NívelDescrição
lowestSutil — backgrounds tingidos, badges
normalPadrão — botão primário, ação principal
highestÊnfase — estados hover, bordas em destaque

Tokens de dimensão​

semantic.dimension.spacing.nano    → 4px
semantic.dimension.spacing.micro   → 8px
semantic.dimension.spacing.small   → 12px
semantic.dimension.spacing.medium  → 32px
semantic.dimension.spacing.large   → 48px

Quantos arquivos foram gerados​

Com a configuração padrão (1 marca × 2 modes × 2 surfaces × 2 camadas):

FormatoArquivos por build
JSON1 marca × 2 modes × 2 surfaces × 2 camadas = 4 arquivos
CSS1 arquivo combinado por variante = 4 arquivos
ESMMesmo que JSON = 4 arquivos
CJSMesmo que JSON = 4 arquivos
TypeScriptMesmo que JSON = 4 arquivos

Adicione mais marcas na configuração e a contagem escala automaticamente: 3 marcas × 2 × 2 × 2 = 24 arquivos JSON.

Qual arquivo importar​

Caso de usoImport
Estilizar uma app web (CSS puro ou qualquer framework)dist/css/semantic/<marca>-light-positive.css
Ler cores/dimensões em JavaScriptdist/esm/<marca>-light-positive-semantic.mjs
Carregar aliases Foundation (simplificados)dist/esm/foundation/<marca>/foundation.mjs
Passar tokens para Figma / Tokens Studiodist/json/<marca>-light-positive-semantic.json
Script Node.js (CommonJS)dist/js/<marca>-light-positive-semantic.js

Importe apenas a variante que precisar — não é necessário carregar todos os arquivos.

Verificando o output​

Após tokens:build, verifique se o dist/ está completo:

# Listar arquivos CSS gerados
ls dist/css/semantic/

# Verificar um valor de token pontualmente
grep 'foundation-bg-primary' dist/css/semantic/aplica_joy-light-positive.css

# Validar data/ antes do build (detecta incompatibilidades de schema cedo)
theme-engine validate:data

Referências​