N3-04 · Entendendo o pipeline de build

Contexto

Você alterou a cor primária de um tema. Rodou o build. Mas a cor no CSS não mudou. Por quê?

Ou: o gradiente existe no config mas não aparece no output. O que foi esquecido?

Entender o pipeline de build não é opcional para um Design Engineer — é o que separa "funciona na minha máquina" de "sei exatamente o que precisa rodar e em que ordem".

Conceito

Duas etapas, uma ordem

O pipeline tem dois estágios sequenciais. O segundo só funciona bem se o primeiro foi executado corretamente.

[Etapa 1 — Geração de Dados]
config/*.config.mjs
        │
        ├─ themes:generate    → data/brand/{tema}/
        ├─ dimension:generate → data/dimension/normal.json
        ├─ sync:architecture  → data/mode/, data/surface/, data/semantic/, data/foundation/
        ├─ foundations:generate → data/foundation/{nome}/styles/
        └─ figma:generate     → data/$themes.json, data/$metadata.json

[Etapa 2 — Style Dictionary]
data/  →  npm run build:all  →  dist/
                                 ├── css/
                                 ├── json/
                                 ├── esm/
                                 ├── cjs/
                                 └── dts/

A pasta data/ é intermediária — nunca edite arquivos em data/ manualmente. Qualquer edição manual é sobrescrita na próxima execução do pipeline.

O comando que faz tudo

npm run build:themes

Executa na ordem correta: ensure:data → themes:generate → dimension:generate → sync:architecture → foundations:generate → figma:generate → build:all.

Use este comando após clone do repositório, após mudanças em configs, ou quando não tem certeza do que está desatualizado.

Quando rodar build incremental

Mudança	Comandos necessários
Alterar cor de um tema	`themes:generate` → `build:all`
Alterar escala dimensional	`dimension:generate` → `build:all`
Alterar schema (feedback/product)	`sync:architecture` → `themes:generate` → `build:all`
Alterar foundation	`foundations:generate` → `build:all`
Adicionar / renomear tema, surface ou mode	`figma:generate`
`data/` já atualizado, só recriar dist/	`build:all`

Exemplo guiado

O papel do `sync:architecture`

Este é o comando mais incompreendido do pipeline. Pense nele como atualizar os links de uma planilha: o schema de arquitetura define quais tokens devem existir; o sync:architecture lê o schema e atualiza todas as camadas intermediárias (mode/, surface/, semantic/, foundation/engine/) para corresponder. Se você pular este passo, essas camadas ainda apontam para a estrutura antiga — novos slots de token não existem ainda, e o build do Style Dictionary os omite silenciosamente.

Quando é obrigatório:

# Adicionou um novo item de product ao schema
# → o sync propaga a nova categoria para mode/, surface/, semantic/
npm run sync:architecture
npm run themes:generate
npm run build:all

# Adicionou gradientes ao config de um tema
# → sem o sync, semantic.color.gradient não existe, gradiente é omitido
npm run sync:architecture
npm run build:all

Como testar sem gravar:

# Verifica se o schema e os configs dos temas estão alinhados
npm run sync:architecture:test

# Exibe o schema atual
npm run sync:architecture:schema

A armadilha dos gradientes

Este é o problema mais comum com gradientes:

# Você fez isso:
npm run themes:generate
npm run build:all

# O gradiente não aparece no CSS. Por quê?
# sync:architecture não rodou → semantic.color.gradient não existe
# Style Dictionary não encontra a seção → omite silenciosamente

# Solução:
npm run sync:architecture
npm run build:all

O build:themes já inclui o sync:architecture na ordem correta. Se você usou comandos individuais, esta é a ordem que nunca falha:

themes:generate → sync:architecture → build:all

Agora você tenta

Dado o cenário abaixo, escreva a sequência de comandos correta:

Você adicionou promo_extended como um novo item de Product no schema de arquitetura. Depois modificou a cor brand_principal no config de um tema existente. Por fim, você quer apenas recriar o dist/ sem alterar data/.

Sequência correta:

# 1. Novo item no schema → sync propaga para mode/surface/semantic
npm run sync:architecture

# 2. Cor alterada no config → themes:generate decompõe e grava data/brand/
npm run themes:generate

# 3. Recriar dist/ com os dados atualizados
npm run build:all

Se você tivesse dúvida sobre a ordem, o comando seguro sempre é npm run build:themes — ele resolve tudo.

Diagnóstico dos 5 problemas mais comuns

Sintoma	Causa provável	Solução
Gradiente não aparece no CSS	`sync:architecture` não rodou após `themes:generate`	`npm run sync:architecture` → `npm run build:all`
Token novo não aparece no `dist/`	Tema não registrado em `themes.config.json`	Adicionar entrada no arquivo global de temas
Cor diferente do esperado	Override em `overrides.*` sobrescrevendo o gerado	Verificar overrides no config do tema
Build falha com "reference not found"	`data/` desatualizado em relação aos configs	`npm run build:themes` (rebuild completo)
`txtOn` é preto/branco quando esperava cor de marca	`txtOnStrategy: 'high-contrast'` é o padrão	Mudar para `'brand-tint'` nas options do tema
Novo tema não aparece no Tokens Studio	`figma:generate` não rodou após adicionar o tema	`npm run figma:generate` ou `npm run build:themes`

Validando o output visualmente — `theme-engine preview` (desde 3.9.0)

Após o build, use o comando de preview para inspecionar todas as combinações de tema no browser antes de sincronizar com o Figma ou integrar em um projeto:

# Usar o dist/ atual
theme-engine preview

# Reconstruir primeiro e então gerar o preview
theme-engine preview --build

# Reconstruir, gerar preview e servir via servidor estático local com live reload (desde 3.11.0)
theme-engine preview --build --serve

Desde 3.11.0, --serve mantém o browser sincronizado automaticamente — cada vez que você rodar npm run themes:generate && npm run build:all em outro terminal, a aba recarrega sem intervenção.

O preview renderiza as quatro variantes (light-positive, light-negative, dark-positive, dark-negative) de todos os temas do workspace. Alterne entre Detailed (explorador em cards, padrão) e Summary (tabela compacta com contrast ratios — desde 3.13.0) pelo dropdown View. Para cada variante, mostra:

background, border, txtOn e txt em todas as famílias semânticas e estados
Classes foundation de tipografia aplicadas a texto de exemplo
Classes de elevação renderizadas como superfícies de cards elevados

Adicionar à tabela de diagnóstico:

Sintoma	Causa provável	Solução
`txtOn` visualmente errado no browser mas o build passa	Token resolvido contra canvas incorreto	`theme-engine preview` para inspecionar o resultado composto
Superfície ghost aparece invisível	`ghost.normal.background` é transparente — comportamento correto	Abrir `theme-engine preview` para verificar contraste contra o canvas composto

Checkpoint

Ao fim deste tutorial você deve saber:

As duas etapas do pipeline e a ordem que nunca falha
O que sync:architecture faz e quando é obrigatório
A diferença entre build:themes (completo) e os comandos incrementais
Por que nunca editar data/ manualmente
Diagnosticar os 5 problemas mais comuns pelo sintoma
Usar theme-engine preview para validar visualmente o output de tokens gerado

Próximo passo

N3-05 · Integrando tokens no seu projeto

O build gerou o dist/. Agora como você conecta esse output ao seu projeto React, Vue, Next.js ou CSS-only?

Referências

Pipeline completo em detalhe: 04-build-pipeline.md
Formatos de output: 05-output-formats.md
Guia de configuração: 03-configuration-guide.md

Contexto​

Conceito​

Duas etapas, uma ordem​

O comando que faz tudo​

Quando rodar build incremental​

Exemplo guiado​

O papel do sync:architecture​

A armadilha dos gradientes​

Agora você tenta​

Diagnóstico dos 5 problemas mais comuns​

Validando o output visualmente — theme-engine preview (desde 3.9.0)​

Checkpoint​

Próximo passo​

Referências​