CHANGELOG

Histórico de versões

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

v3.12.0 Abril 2026 latest
  • · 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.

Gostou? Apoie com um café