CHANGELOG

Histórico de versões

Aplica Tokens Theme Engine — evolução do sistema de tokens de design.

v3.14.0–3.14.6 Maio 2026 latest

· Overrides dinâmicos de estado de interação (3.14.5): overrides.interaction substitui e estende o formato legado overrides.interface.function.* — overrides agora podem ter como alvo grupos function ou feedback, itens específicos (ex.: primary, warning_default), presets solid ou ghost, e estados individuais (normal, action, active, focus, disabled); as cores de override passam pelo pipeline de decomposição completo (dilution, base adaptation, espelhamento de quadrante, texto de acessibilidade) em vez de serem aplicadas como patches brutos
· Splitting de bundles de marca para Figma (3.14.0): figma:generate agora divide automaticamente bundles de tokens de marca oversized em chunks semânticos (_brand_product.json, _brand_text.json, _brand_interface.json) quando a contagem de tokens excede o limite por coleção do Figma (padrão 5.000 tokens); o contrato lógico de tokens e o output em dist/ não mudam — a divisão afeta apenas os arquivos intermediários em data/brand/ consumidos pelo Tokens Studio; sobrescreva o limite via a variável de ambiente APLICA_THEME_ENGINE_BRAND_TOKEN_LIMIT
· Correções de bugs (3.14.1–3.14.4): grupos de shards de marca preservados nos temas Figma; convenção de nomes com underscore adotada para compatibilidade com Tokens Studio; nomes de shards com ponto excluídos do output Figma

v3.13.5–3.13.8 Maio 2026

· Decomposição de feedback por modo (3.13.6): options.interaction.decomposition.modeResolution aceita 'quadrant' (padrão, comportamento existente) ou 'mode' — quando 'mode', os tokens de feedback seguem semântica light/dark sem inversão de polaridade de quadrante, produzindo as mesmas cores de superfície, texto e borda em superfícies positive e negative dentro do mesmo modo
· Correções de bugs (3.13.5, 3.13.7, 3.13.8): cores derivadas em dilution agora espelham corretamente entre quadrantes (light-positive == dark-negative); texto e bordas de feedback mode-aware alinham com as superfícies; espelhamento por quadrante do feedback padrão (modeResolution: 'quadrant') restaurado após regressão introduzida no 3.13.6

v3.13.0–3.13.4 Maio 2026

· Preview modo Summary (3.13.0): theme-engine preview ganha dropdown View para alternar entre Detailed (explorador existente) e Summary — o modo Summary exibe uma tabela compacta com background, txtOn, border, txt e contrast ratios para cada família semântica e estado, otimizado para QA rápido entre combinações de tema
· Dilution com âncora cromática (3.13.1–3.13.3): o método dilution ganha target: 'anchor' — move os estados de interação em direção a uma cor-âncora configurável em vez de sempre mirar branco/preto ou o canvas; anchor.source aceita 'palette' (família de paleta atual), 'hex' (cor fixa) ou 'token' (outra escala gerada); anchor.canvasAware e anchor.canvasMix permitem que a âncora mantenha seu hue próprio enquanto ainda clareia em canvases claros e escurece em canvases escuros
· Adaptação de base por quadrante (3.13.4): options.baseAdaptation: true faz com que superfícies normal de interaction (function/feedback) e superfícies default de product respondam ao quadrante ativo (light/dark + positive/negative) — por padrão normal e default permanecem fixos na cor base autorada independente do quadrante; ative apenas quando a marca precisa que essas superfícies se adaptem

v3.12.0 Abril 2026

· Configuração de decomposição de interação aprimorada: temas podem declarar options.interaction.groups.{function|feedback} para configurar método de decomposição e levels de surface independentemente por grupo — function e feedback podem usar métodos diferentes no mesmo tema
· Overrides de surface por grupo: options.interaction.groups.function.surfaces.solid e .ghost carregam sua própria config de decomposição e levels, resolvida por mesclagem tema → surface → grupo → grupo-surface
· Validação atualizada: groups.{function|feedback}.levels não é suportado (usar groups.{function|feedback}.surfaces.solid.levels ou .ghost.levels)

v3.11.0 Abril 2026

· theme-engine preview --serve agora inclui live reload — o browser atualiza automaticamente quando dist/ muda, sem necessidade de reload manual enquanto se itera em configs de tema

v3.10.1 Abril 2026

· Bug fix: overrides de decomposição de interação agrupados (options.interaction.groups.*) agora resolvem corretamente em todas as combinações de surface e estado — a versão anterior podia produzir valores de cor incorretos quando config de nível de grupo coexistia com config de nível de surface

v3.10.0 Abril 2026

· Distribuição nativa de orientação para IA em workspaces consumidores: theme-engine ai:init agora implanta arquivos de contexto a partir do pacote publicado em vez de templates locais, mantendo workspaces consumidores sincronizados com a evolução do engine sem gestão manual de arquivos
· AI_CONTEXT.md e THEME_CONFIG_REFERENCE.md são agora empacotados e distribuídos com cada release do engine — rodar ai:init após um upgrade de versão atualiza a orientação automaticamente

v3.9.0 Abril 2026

· Modos de decomposição de interação: temas podem declarar options.interaction.decomposition.method como system-scale (comportamento legado, agora nomeado explicitamente) ou dilution (novo) para interface.function e interface.feedback
· Presets de surface expandidos com grupos opcionais solid e ghost — temas que optam por legacyStructure: false geram grupos function e feedback explícitos em brand, mode, surface e semantic
· Ajuste fino de interação por estado: configure valores diretamente em options.interaction.surfaces.{solid|ghost}.levels — em system-scale são níveis de paleta (active: 120), em dilution são fatores autorais (active: 0.8, action: 1.2, focus: 0.3)
· Comando theme-engine preview — gera preview HTML estático em dist/preview/ para inspecionar background, border, txtOn, txt, classes de tipografia e elevation em todas as combinações de tema; flags --build (rebuild antes) e --serve (servidor local estático)

v3.8.5 Abril 2026

· Automação de publicação confiável (trusted publishing) via GitHub Actions — fluxo de release sem segredos de npm token
· Runtimes das GitHub Actions atualizados para Node.js 24

v3.8.4 Abril 2026

· Tokens txt negativos agora seguem o contrato de canvas declarado em todo o pipeline até dist/ — interface.function, interface.feedback, disabled e product corrigidos
· Polaridade de produto sobrevive ao sync:architecture — novo branch mode.productBySurface garante que readable text de produto chegue a surface, semantic e dist/ sem colapsar para o contrato positive
· Workspaces novos inicializam corretamente o branch surface-aware de produto ao rodar sync:architecture do zero
· test:txt-inversion agora audita o JSON final em dist/ em vez de camadas intermediárias — falhas em branches negativos de interface e produto são detectadas no mesmo layer que o Figma consome

v3.8.3 Abril 2026

· txt ambiente agora segue o canvas do arquivo final em ambas as polaridades — brand.ambient.contrast.*.txt, neutral.*.txt e grayscale.*.txt resolvem contra contrast.base.positive.background do modo ativo
· Superfícies negativas ambientes resolvem a partir do canvas do modo inverso — light-negative alinha com o contrato dark; dark-negative alinha com o contrato light
· Cobertura de regressão agora protege contrast.base, neutral e grayscale em todos os quatro quadrantes de mode/surface

v3.8.2 Abril 2026

· brand.branding agora respeita a polaridade positive/negative nos outputs semânticos — sync:architecture carrega branch mode.brand.brandingBySurface separado para que surface.color.brand.branding.* não colapse light-positive e light-negative na mesma cadeia de aliases
· Dark mode segue a mesma regra de surface inversa que o light mode — dark-negative espelha o branch light enquanto dark-positive permanece no branch dark
· Cobertura de regressão agora valida o espelhamento de branding por surface e impede que mudanças futuras de sync achateem outputs negativos silenciosamente

v3.8.1 Abril 2026

· Correção de acessibilidade do txt ambiente: brand.ambient.neutral.*.txt e brand.ambient.grayscale.*.txt agora validam contra o contrast.base declarado, não o background do nível
· txtOn e txt ambiente deixam de compartilhar o mesmo alvo de acessibilidade implicitamente — contratos agora distintos e corretos
· Cobertura de regressão estendida em test:txt-inversion para proteger o contrato de surface declarada

v3.8.0 Abril 2026

· Alias CLI preferido theme-engine — comando mais curto para workspaces consumidores; aplica-theme-engine preservado como fallback de compatibilidade
· Toda a documentação ativa padroniza em theme-engine primeiro — README, consumer guide, onboarding e docs EN/PT-BR
· Smoke de pacote instalado agora valida os dois nomes de CLI

v3.7.5 Abril 2026

· Fix Tokens Studio-safe: branches de texto legível de produto desabilitadas não emitem mais nós txt: null inválidos
· Workspaces com generateTxt: true e textExposure.product: false agora geram JSON seguro para Figma/Tokens Studio

v3.7.4 Abril 2026

· Inversão de texto legível para superfícies negativas: brand.text.negative.* resolve corretamente em light-negative e dark-negative
· Tokens txt de produto removidos das camadas públicas quando textExposure.product está desabilitado
· Migrador legado infere exposição de texto de feedback a partir de aliases planos do contrato legado

v3.7.2 Abril 2026

· Propagação de brand.branding corrigida através de mode antes de chegar a surface e outputs semânticos
· Migrador legado agora preserva o contrato generation.colorText automaticamente na conversão

v3.7.1 Abril 2026

· Fix de inversão do txt ambiente: brand.ambient agora resolve texto legível contra os backgrounds positive/negative corretos
· Caminho de regressão test:txt-inversion adicionado ao pipeline de validação

v3.7.0 Abril 2026

· Plataforma de output jsonTyped — primeiro delivery de output extensível com metadata tipada por token
· Campos configuráveis: type, value, description, path — nomes ajustáveis via formatOptions.jsonTyped em transformers.config.mjs
· description pode ser excluído do output omitindo a chave na configuração
· Backward compatible — contrato json existente não muda; habilite as duas plataformas na mesma camada se precisar

v3.6.4 Abril 2026

· Fix de migração: generate-foundation.mjs agora preserva corretamente txt.base.items em workspaces com product text families customizados
· Temas estilo Brewer com famílias personalizadas (ex.: tada, ze) não mais perdem dados de txt após generate-foundation

v3.6.3 Abril 2026

· Scaffolding do init agora usa includePrimitives: false por padrão — workspace mais enxuto out-of-the-box
· Banner ASCII de onboarding no CLI init — exibe versão, licença, docs e link de apoio
· Cobertura de smoke para ai:init no fluxo de validação do pacote publicado

v3.6.1 Abril 2026

· generation.colorText no workspace config — generateTxt, txtBaseColorLevel, fallbackBaseColorLevel e textExposure agora ficam em aplica-theme-engine.config.mjs, não por tema
· Controle centralizado garante contrato de texto uniforme para todos os temas do workspace

v3.6.0 Abril 2026

· Token txt — contrato de cor expandido de 3 para 4 partes: background / txtOn / border / txt
· txt representa texto legível sobre canvas (não sobre fundo colorido); sempre acessível em WCAG contra o fundo ambiente
· txtBaseColorLevel — controla o nível de paleta inicial para busca do txt (default: 140)
· Text states estruturados (normal / action / active / focus) propagam txt em todas as camadas
· Aliases planos de foundation: foundation.txt.info, foundation.txt.primary, foundation.txt.promo
· textExposure — controla quais famílias recebem aliases foundation.txt.* (default: feedback apenas)
· Breaking: aliases de texto não mais herdam de surface.* — geração unificada a partir da paleta

v3.5.2 Abril 2026

· AI UI Integration Program — contrato formal de consumo de tokens por agentes de IA (Cursor, Claude Code, GitHub Copilot)
· ai:init — injeta arquivos de integração de editor no workspace do consumidor (.cursor/rules/, .claude/skills/, .github/instructions/, docs/context/)
· Archetypes de componente: Button, Dialog, Input, Badge, Select, Card, Tabs — modelos de decisão de tokens canonicalizados
· Foundation Styles como caminho de consumo preferido para IA — classes typography.css e elevation.css sancionadas
· Portal rule para headless UI (Base UI, Radix) — aplica classe de tema ao document.body
· Sandbox de validação Base UI + Radix parity sandbox

v3.4.0 Abril 2026

· Novo comando figma:generate — gera e mantém os três arquivos que o Tokens Studio precisa ($themes.json, $themes.engine.json.template, $metadata.json)
· Merge inteligente: campos de propriedade do Figma (id, $figmaStyleReferences, variableIDs) são preservados; estrutura regenerada a cada execução
· IDs estáveis via SHA1 de "group:name" — sem IDs aleatórios que forçam re-sync no Figma
· Arquitetura schema como fonte única de verdade — todos os layers propagados via sync:architecture
· colorContrastDecompose: API para decomposição personalizada de paletas por contraste
· Validação de surface/txtOn — aviso automático quando txtOn está fora de escala
· Auto-regeneração AA não-interativa quando acceptAALevelFallback está ativo

v3.0.0 Abril 2026

· Arquitetura package-first — @aplica/aplica-theme-engine publicado como pacote NPM independente
· Consumer workspace model — configuração e dados ficam no projeto consumidor, não no pacote
· APIs de configuração públicas: /config e /transformers/config para extensibilidade
· aplica-theme-engine init — scaffolding de workspace com wizard ou template inicial
· migrate:legacy-consumer — migração automatizada de projetos monolíticos pré-v3
· Separação clara entre data/ (gerado) e dist/ (build) dentro do workspace do consumidor

v2.26.0 Abril 2026

· Foundation Styles Generation — gera typography_styles.json e elevation_styles.json por foundation brand
· Classes CSS compostas em dist/css/foundation/{brand}/typography.css e elevation.css
· Tipografia como estilo composto: sete propriedades em uma classe, referenciando tokens semânticos
· Elevação como estilo composto: box-shadow por nível (level_minus_one até level_five)
· Valores resolvem em runtime pelo arquivo de tema ativo — troca de tema atualiza automaticamente

v2.22.x – v2.25.x Março–Abril 2026

· Dimensões em rem no CSS — saída CSS usa rem; JSON/ESM/CJS mantêm px
· Estado focus para interface — tokens de foco adicionados à camada de função
· txtOnStrategy: "custom-tint" — permite cor customizada para texto sobre backgrounds de marca
· Escalas tipográficas nano e zetta — extremidades da escala de tamanho
· Elevation configurável por tema — cada marca pode ter sombras independentes
· Border offset configurável — controle granular do offset de borda por token

v2.0.0 Dezembro 2025 legacy

· Gerador dinâmico de temas — substituiu geração manual de tokens
· Pipeline OKLCh completo — decomposição de cores em paletas de 19 níveis
· Algoritmo de inversão de dark mode: dark[N] = light[20-N]
· 4 variantes por tema: light-positive, light-negative, dark-positive, dark-negative
· Nomenclatura canônica e contrato de naming (canonical-taxonomy-and-naming-contract)
· Bundle de migração V1 → V2

v1.x 2025 legacy

· Sistema base de tokens — CSS custom properties, JSON, ES Modules, TypeScript declarations
· Formalização de depth, opacity, tipografia e bordas
· Compatibilidade com monorepo
· Tokens parcialmente manuais — limitação identificada, resolvida na v2

Alpha 2020–2021 legacy

· Quatro decisões fundadoras: nomeação semântica, separação de camadas, decomposição de cores, algoritmo de acessibilidade
· Exploração conceitual sem geração dinâmica — base do sistema atual

O histórico completo de decisões de design — incluindo o mapeamento V1→V2 e os racionais de cada mudança — está documentado em 06 · History na documentação.