Pular para o conteúdo principal

Guia de Migração

Premissa​

Este guia cobre três cenários de migração distintos:

  1. Monolítico para pacote NPM — como migrar um projeto que embutia o código-fonte do engine diretamente para o novo modelo de pacote NPM @aplica/aplica-theme-engine.
  2. Atualização de versão do engine — como atualizar um projeto que usa o pacote NPM para uma versão mais recente, sem perder configurações e sem quebrar temas existentes.
  3. Migração estrutural legada — como mover projetos com a estrutura antiga de config (config em dynamic-themes/themes/config/) para o modelo atual de consumer workspace.

Migração de Monolítico para Pacote NPM​

Se o seu projeto contém o código-fonte do engine diretamente (uma cópia do repositório do engine ou um git subtree), o comando migrate:legacy-consumer automatiza a conversão para o modelo de consumer workspace do pacote NPM.

Quando se aplica​

Seu projeto tem qualquer um dos seguintes:

  • Um diretório dynamic-themes/ na raiz do projeto
  • Scripts do engine diretamente no seu repositório (lib/, transformers/, schemas/)
  • npm run build:themes no package.json apontando para um caminho de script local

Processo de migração​

Passo 1 — Instalar o pacote​

npm install @aplica/aplica-theme-engine

Passo 2 — Analisar o workspace atual​

Execute o analyzer primeiro para entender o que será migrado:

theme-engine migrate:legacy-consumer analyze --source=./dynamic-themes

O analyzer reporta:

  • Quais arquivos de config foram encontrados e onde vão parar na nova estrutura
  • Quais schema overrides existem (irão para theme-engine/schemas/)
  • Se há scripts customizados que sobrescrevem o comportamento padrão do engine (devem ser tratados manualmente)

Passo 3 — Executar a migração​

# Dry run — visualizar todas as mudanças sem escrever nada
theme-engine migrate:legacy-consumer run --source=./dynamic-themes --dry-run

# Executar a migração
theme-engine migrate:legacy-consumer run --source=./dynamic-themes

A migração:

  • Cria theme-engine/config/ com seus configs de marca e config global
  • Cria aplica-theme-engine.config.mjs na raiz do projeto
  • Cria theme-engine/transformers.config.mjs a partir das suas configurações de transformer existentes
  • Cria theme-engine/schemas/ se você tinha schema overrides
  • Não apaga a estrutura antiga (a limpeza é manual, após verificação)

Passo 4 — Verificar paridade​

A migração é bem-sucedida quando tanto o build anterior quanto o novo produzem output dist/ idêntico. O sub-comando compare verifica isso:

# Build com o novo modelo de pacote
npm run tokens:build

# Comparar novo output com o output legado
theme-engine migrate:legacy-consumer compare

O compare faz diff arquivo por arquivo em dist/ e reporta quaisquer discrepâncias. Paridade significa que a migração está completa.

Passo 5 — Atualizar scripts do package.json​

Substitua os scripts de build antigos pelos novos scripts de consumer:

{
  "scripts": {
    "tokens:build":       "theme-engine build",
    "tokens:build:all":   "theme-engine build:all",
    "tokens:themes":      "theme-engine themes:generate",
    "tokens:sync":        "theme-engine sync:architecture",
    "tokens:foundations": "theme-engine foundations:generate",
    "tokens:validate":    "theme-engine validate:data"
  }
}

Passo 6 — Limpeza (após paridade confirmada)​

# Remover o código-fonte embutido do engine
rm -rf dynamic-themes/
rm -rf lib/
rm -rf transformers/

Atualize o .gitignore para excluir diretórios gerados:

/data/
/dist/

Flags de migração​

FlagDescrição
--source=<caminho>Caminho para o diretório legado do engine (padrão: ./dynamic-themes)
--forceSobrescrever arquivos existentes no consumer workspace alvo
--profile=<nome>Usar um perfil de migração específico para layouts não-padrão

Como o Engine Versiona Mudanças​

O engine segue Semantic Versioning (SemVer). O que isso significa para consumidores:

Tipo de versãoO que mudaImpacto
Patch (2.18.x → 2.18.1)Correções de bugs, ajustes internosSeguro atualizar direto
Minor (2.18.x → 2.19.0)Novos tokens adicionados, novos recursos opcionaisSeguro atualizar — não remove nada existente
Major (2.x → 3.0)Tokens renomeados ou removidos, mudança de estrutura de pastaRequer migração explícita — caminhos antigos deixam de existir

O que conta como breaking change​

  • Renomear um caminho de token (ex.: semantic.color.interface.oldName → semantic.color.interface.newName)
  • Remover um token do schema
  • Mudar a estrutura de pastas do dist/ de forma incompatível

O que NÃO é breaking change​

  • Adicionar novos tokens ao schema
  • Adicionar novos temas
  • Adicionar novos formatos de output (dts/, etc.)
  • Melhoras internas ao pipeline de build

Fontes de informação por versão​

Antes de qualquer migração, leia:

CHANGELOG.md          — Narrativa do que mudou e por quê
RELEASE_FILES.md      — Lista exata de arquivos adicionados, modificados e removidos por versão
CHANGELOG-ARCHIVE.md  — Histórico para versões 2.11.x e anteriores

Atualização de Versão Minor / Patch​

Para atualizações que não envolvem breaking changes (minor ou patch):

Passo 1 — Verificar a versão atual​

cat package.json | grep '"version"'

Passo 2 — Ler o CHANGELOG​

Leia as entradas entre a versão atual e a versão alvo. Identifique:

  • Novos arquivos de lógica adicionados (schemas/, lib/, scripts em dynamic-themes/)
  • Configurações que precisam ser atualizadas (marcadas como "Configurations that MUST be updated")
  • Novos tokens adicionados ao schema (indicam que sync:architecture precisa rodar)

Passo 3 — Separar: lógica vs configuração​

Esta é a regra de ouro da atualização:

O que vem do upstream (nova versão)O que permanece do seu projeto
Scripts em dynamic-themes/config/*.config.mjs (configs de tema)
schemas/ (architecture.mjs, etc.)config/global/themes.config.json
lib/paths.mjsconfig/foundations/*.config.mjs
transformers/Overrides e customizações

Nunca sobrescreva seu config/ com arquivos do upstream. O upstream fornece lógica — sua config é sua.

Passo 4 — Executar verificação antes de buildar​

# Verificar se a estrutura de dados ainda bate com o schema
npm run sync:architecture:test

# Build completo para confirmar que tudo resolve corretamente
npm run build:themes

Passo 5 — Confirmar output​

# Verificar que os dist/ foram gerados corretamente
ls dist/css/
ls dist/json/

# Confirmar que nenhum token crítico sumiu
grep "semantic-color-interface-function-primary" dist/css/*.css | head -5

Migração Estrutural — Legado para Centralizado​

A maior mudança estrutural do engine foi a centralização dos configs: o que estava em dynamic-themes/themes/config/ e dynamic-themes/themes/schemas/ foi movido para a raiz do projeto.

Quando este cenário se aplica​

Se o seu projeto tem configs em qualquer destes locais:

  • dynamic-themes/themes/config/*.config.mjs
  • dynamic-themes/themes/config/global/
  • dynamic-themes/themes/config/foundations/
  • dynamic-themes/themes/schemas/
  • dynamic-themes/schemas/
  • transformers/schemas/

Mapa de caminhos: legado → centralizado​

Localização legadaNova localização
dynamic-themes/themes/config/global/themes.config.jsonconfig/global/themes.config.json
dynamic-themes/themes/config/global/dimension.config.mjsconfig/global/dimension.config.mjs
dynamic-themes/themes/config/*.config.mjsconfig/*.config.mjs
dynamic-themes/themes/config/foundations/config/foundations/
dynamic-themes/themes/schemas/ ou dynamic-themes/schemas/schemas/ (de upstream)
transformers/schemas/schemas/ (conteúdo migrado)
Caminhos hardcoded nos scriptslib/paths.mjs (de upstream)

Processo de migração estrutural​

1. Verificação de versão (obrigatório primeiro)​

cat package.json | grep '"version"'

Leia o CHANGELOG a partir da versão atual até a versão alvo. Para versões 2.11.x e anteriores, também leia CHANGELOG-ARCHIVE.md.

2. Backup​

git stash
# ou simplesmente criar um branch antes de começar
git checkout -b migration/centralized-config

3. Inventário pré-migração​

Liste todos os arquivos de configuração do projeto antes de mover qualquer coisa:

# Configs de tema
ls dynamic-themes/themes/config/*.config.mjs

# Config global
ls dynamic-themes/themes/config/global/

# Foundations
ls dynamic-themes/themes/config/foundations/

# Schemas customizados (se existirem)
ls dynamic-themes/themes/schemas/ 2>/dev/null
ls dynamic-themes/schemas/ 2>/dev/null

4. Rodar o script de migração​

O engine fornece um script que copia os configs do projeto para os novos caminhos sem sobrescrever nada:

# Dry run — ver o que seria copiado sem alterar arquivos
npm run migrate:centralized -- --dry-run

# Executar a migração (copia, não move — mantém os arquivos antigos por segurança)
npm run migrate:centralized

# Para mover em vez de copiar (só após confirmar que o dry-run está correto)
npm run migrate:centralized -- --move

O script cria config/, config/global/, config/foundations/ e schemas/ se não existirem. Ele não cria lib/paths.mjs — esse arquivo vem do upstream.

5. Trazer lógica do upstream​

Após mover os configs, traga os arquivos de lógica da nova versão:

# lib/paths.mjs — fonte única de caminhos
# schemas/architecture.mjs, typography-styles.mjs, foundation-styles.mjs
# Scripts atualizados em dynamic-themes/

Os scripts e transformers atualizados usam lib/paths.mjs como fonte única de todos os caminhos — qualquer referência hardcoded a dynamic-themes/themes/config/ nos scripts legados deve ser substituída por imports de lib/paths.mjs.

6. Verificação​

# Verificar estrutura sem gravar
npm run sync:architecture:test

# Build completo
npm run build:themes

# Build Style Dictionary
npm run build

# Testes (se o projeto tiver)
npm run test

Confirme que data/ e dist/ foram gerados corretamente e que nenhum script ainda lê de dynamic-themes/themes/config/, dynamic-themes/themes/schemas/ ou transformers/schemas/.

7. Limpeza​

Somente após confirmar que o build e os testes passam:

# Remover estrutura legada
rm -rf dynamic-themes/themes/config/
rm -rf dynamic-themes/themes/schemas/
rm -rf transformers/schemas/  # se existir e conteúdo foi migrado

Migração para Versão com $description (2.19.x+)​

A versão 2.19.x adicionou campos $description aos tokens para melhorar o contexto em ferramentas de design e AI. Esta é uma migração additive — não quebra nada — mas requer dois novos arquivos do upstream:

schemas/semantic-token-descriptions.mjs     ← descrições dos tokens Semantic
config/foundations/foundation-token-descriptions.mjs  ← descrições dos tokens Foundation

Traga esses arquivos do upstream. Suas overrides de descrição por foundation ficam em config/foundations/*.config.mjs nos campos descriptions e styles.elevation[level].description — o script de migração os preserva.

Após adicionar, rode sync:architecture e verifique que data/semantic/default.json e data/foundation/engine/default.json têm os campos $description.

Quando Tokens São Renomeados (Major Version)​

Se um caminho de token mudou entre versões (ex.: um breaking change de major):

1. Identificar quais tokens mudaram​

Leia o CHANGELOG da versão major — ele listará os caminhos antigos, os novos e a razão.

2. Encontrar todas as ocorrências no código consumidor​

# Buscar o token antigo em componentes
grep -r "semantic-color-interface-old-name" src/

# Buscar em arquivos CSS
grep -r "semantic.color.interface.oldName" src/

3. Substituir​

Substitua globalmente o caminho antigo pelo novo. No CSS, tokens seguem o padrão de substituição direto: semantic.color.old.path → --semantic-color-old-path vira --semantic-color-new-path.

4. Validar o build​

npm run build:themes
npm run build

# Verificar que a nova variável existe no output
grep "semantic-color-new-path" dist/css/*.css

Migração para 3.6.x — Contrato de cor de 4 partes​

A versão 3.6.0 introduziu uma breaking change: o contrato de propriedades de cor expandiu de três partes (background, txtOn, border) para quatro (background, txtOn, border, txt). A versão 3.6.1 consolidou os controles de geração de texto em uma chave de config no nível do workspace.

O que mudou​

ÁreaAntes (3.5.x)Depois (3.6.x)
Propriedades do bloco de corbackground, txtOn, border+ txt
Fontes de aliases de textoHerdadas de surface.*Geradas da paleta diretamente
Localização da config de textoCampos options.* por temageneration.colorText no workspace config
Padrão de includePrimitivestruefalse (desde 3.6.3)

Passo 1 — Atualizar o pacote​

npm install @aplica/aplica-theme-engine@^3.6.3

Passo 2 — Habilitar geração de txt no workspace config​

Adicionar generation.colorText ao aplica-theme-engine.config.mjs:

import { defineThemeEngineConfig } from '@aplica/aplica-theme-engine/config';

export default defineThemeEngineConfig({
  generation: {
    colorText: {
      generateTxt: true,
      txtBaseColorLevel: 140,
      fallbackBaseColorLevel: 160,
      textExposure: ['feedback'],     // adicionar 'interfaceFunction' ou 'product' se necessário
    }
  },
  paths: { /* seus paths existentes */ }
});

Se estiver atualizando especificamente da 3.6.0: Remova quaisquer campos generateTxt, txtBaseColorLevel, fallbackBaseColorLevel ou textExposure dos configs de tema individuais — eles foram movidos para o workspace config na 3.6.1.

Passo 3 — Rebuild​

theme-engine build

O build vai gerar propriedades txt em todos os blocos de cor em data/ e dist/.

Passo 4 — Revisar uso de cor de texto nos componentes​

Buscar onde valores de surface.* foram usados como cores de texto:

grep -r "surface.*txt\|txtOn.*canvas\|surface.*color" src/

Migrar para os novos aliases txt:

Padrão antigoNovo padrão
var(--semantic-color-interface-feedback-info-normal-surface) como textovar(--foundation-txt-info)
var(--semantic-color-interface-function-primary-normal-txtOn) no canvasvar(--semantic-color-interface-function-primary-normal-txt)

Passo 5 — Verificar includePrimitives​

Se o setup do Figma do projeto depende de _primitive_theme.json, configure explicitamente includePrimitives: true nas options do tema — o padrão mudou para false na 3.6.3:

// No config do tema
options: {
  includePrimitives: true,
}

Checklist para 3.5.x → 3.6.x​

  • Atualizar pacote para 3.6.3
  • Adicionar generation.colorText ao workspace config com generateTxt: true
  • Remover campos txt-relacionados dos configs de tema individuais (mudança 3.6.0 → 3.6.1)
  • Rodar theme-engine build
  • Revisar componentes que usam valores surface.* como cor de texto → migrar para foundation.txt.* ou *.txt.normal
  • Verificar configuração de includePrimitives se primitivos Figma são necessários
  • Confirmar que o output em dist/ contém propriedades txt nos tokens de cor

Checklist de Migração Rápida​

Para minor/patch:

  • Ler CHANGELOG da versão atual até alvo
  • Atualizar lógica (scripts, schemas, lib/) do upstream
  • Preservar configs do projeto (config/*.config.mjs, etc.)
  • Rodar sync:architecture:test → build:themes → build
  • Confirmar output em dist/

Para migração estrutural:

  • Verificar versão atual no package.json
  • Ler CHANGELOG e RELEASE_FILES para o range de versões
  • Fazer backup / criar branch
  • Fazer inventário de configs legados
  • Rodar npm run migrate:centralized -- --dry-run
  • Rodar npm run migrate:centralized
  • Trazer lib/paths.mjs, schemas/ e scripts atualizados do upstream
  • Corrigir imports nos scripts que apontam para caminhos legados
  • Rodar sync:architecture:test → build:themes → build → test
  • Remover pastas legadas somente após validação

Referências​