CHANGELOG

Version history

Aplica Tokens Theme Engine — evolution of the design token system.

v3.12.0 April 2026 latest
  • · Enhanced interaction decomposition configuration: themes can now declare options.interaction.groups.{function|feedback} to configure decomposition method and surface levels independently per group — function and feedback can use different methods within the same theme
  • · Per-group surface overrides: options.interaction.groups.function.surfaces.solid and .ghost carry their own decomposition and levels config, resolved by merging theme-level → surface-level → group-level → group-surface-level
  • · Validation updated: groups.{function|feedback}.levels is not supported (use groups.{function|feedback}.surfaces.solid.levels or .ghost.levels instead)
v3.11.0 April 2026
  • · theme-engine preview --serve now includes live reload — the browser refreshes automatically when dist/ changes, no manual page reload needed while iterating on theme configs
v3.10.1 April 2026
  • · Bug fix: grouped interaction decomposition overrides (options.interaction.groups.*) now resolve correctly in all surface and state combinations — the previous version could produce wrong color values when group-level config existed alongside surface-level config
v3.10.0 April 2026
  • · Native AI guidance distribution for consumer workspaces: theme-engine ai:init now deploys context files from the published package instead of from a local template, keeping consumer workspaces in sync with engine evolution without manual file management
  • · AI_CONTEXT.md and THEME_CONFIG_REFERENCE.md are now packaged and distributed with each engine release — running ai:init after a version upgrade updates the guidance automatically
v3.9.0 April 2026
  • · Authored interaction decomposition modes: themes can declare options.interaction.decomposition.method as system-scale (legacy behavior, now explicitly named) or dilution (new) for interface.function and interface.feedback
  • · Expanded interaction surface presets with optional solid and ghost groups — themes opting out of legacyStructure: false generate explicit function and feedback groups across brand, mode, surface, and semantic
  • · Per-state authored interaction tuning: configure values directly under options.interaction.surfaces.{solid|ghost}.levels — in system-scale these are palette levels (active: 120); in dilution these are authored factors (active: 0.8, action: 1.2, focus: 0.3)
  • · theme-engine preview command — generates a workspace-local static HTML preview in dist/preview/ to inspect background, border, txtOn, txt, typography, and elevation classes across all theme combinations; flags --build (rebuild first) and --serve (local static server)
v3.8.5 April 2026
  • · Trusted publishing release automation via GitHub Actions — npm releases no longer require a stored npm token
  • · GitHub Actions runtimes upgraded to Node.js 24
v3.8.4 April 2026
  • · Negative txt tokens now follow the declared canvas contract all the way to dist/ — interface.function, interface.feedback, disabled, and product branches fixed
  • · Product polarity now survives sync:architecture — new mode.productBySurface branch ensures readable text reaches surface, semantic, and dist/ outputs without collapsing to the positive contract
  • · Fresh workspaces now correctly bootstrap the surface-aware product branch when sync:architecture runs from scratch
  • · test:txt-inversion now audits the final distributable JSON in dist/ instead of intermediate layers — failures in negative interface and product branches are caught at the same layer Figma imports
v3.8.3 April 2026
  • · Ambient txt now follows the final file canvas in both polarities — brand.ambient.contrast.*.txt, neutral.*.txt, and grayscale.*.txt resolve against contrast.base.positive.background for the active mode file
  • · Negative ambient surfaces resolve from the inverse mode canvas — light-negative aligns with the dark canvas contract; dark-negative aligns with the light canvas contract
  • · Regression coverage now protects contrast.base, neutral, and grayscale ambient text across all four mode/surface quadrants
v3.8.2 April 2026
  • · brand.branding now respects positive/negative surface polarity in semantic outputs — sync:architecture now carries a separate mode.brand.brandingBySurface branch so surface.color.brand.branding.* no longer collapses light-positive and light-negative into the same alias chain
  • · Dark mode follows the same inverse-surface rule as light mode — dark-negative mirrors the light branch while dark-positive stays on the dark branch
  • · Regression coverage now validates branding surface mirroring and prevents future sync changes from silently flattening negative branding outputs
v3.8.1 April 2026
  • · Ambient txt accessibility correction: brand.ambient.neutral.*.txt and brand.ambient.grayscale.*.txt now validate against the declared contrast.base surface, not the level background
  • · txtOn and ambient txt no longer share the same accessibility target implicitly — contracts are now distinct and correct
  • · Regression coverage extended in test:txt-inversion to protect the declared-surface ambient text contract
v3.8.0 April 2026
  • · Preferred theme-engine CLI alias — shorter command for consumer workspaces; aplica-theme-engine preserved as a compatibility fallback
  • · All active documentation standardizes on theme-engine first — README, consumer guide, onboarding, and EN/PT-BR docs
  • · Installed-package smoke coverage now validates both CLI names
v3.7.5 April 2026
  • · Tokens Studio-safe fix: disabled product readable-text branches no longer emit invalid txt: null nodes
  • · Workspaces with generateTxt: true and textExposure.product: false now generate Figma/Tokens Studio-safe JSON
v3.7.4 April 2026
  • · Readable text inversion for negative surfaces: brand.text.negative.* resolves correctly in light-negative and dark-negative
  • · Product txt tokens removed from public layers when textExposure.product is disabled
  • · Legacy migrator infers feedback text exposure from flat aliases in the legacy contract
v3.7.2 April 2026
  • · brand.branding propagation fixed through mode before reaching surface and semantic outputs
  • · Legacy migrator now preserves the generation.colorText contract automatically on conversion
v3.7.1 April 2026
  • · Ambient txt inversion fix: brand.ambient now resolves readable text against the correct positive/negative background contexts
  • · test:txt-inversion regression path added to the validation pipeline
v3.7.0 April 2026
  • · jsonTyped output platform — first extensible output delivery with typed metadata per token
  • · Configurable fields: type, value, description, path — key names adjustable via formatOptions.jsonTyped in transformers.config.mjs
  • · description can be excluded from output by omitting its key from the config
  • · Backward compatible — existing json contract unchanged; enable both platforms in the same layer if you need both
v3.6.4 April 2026
  • · Migration fix: generate-foundation.mjs now correctly preserves txt.base.items in workspaces with custom product text families
  • · Brewer-style themes with custom families (e.g., tada, ze) no longer lose txt data after generate-foundation
v3.6.3 April 2026
  • · init scaffold now defaults to includePrimitives: false — leaner out-of-the-box consumer workspace
  • · ASCII onboarding banner in CLI init — displays version, license, docs, and support link
  • · Smoke coverage for ai:init in published package validation flow
v3.6.1 April 2026
  • · generation.colorText in workspace config — generateTxt, txtBaseColorLevel, fallbackBaseColorLevel, and textExposure now live in aplica-theme-engine.config.mjs, not per-theme
  • · Centralized control ensures uniform text contract across all themes in the workspace
v3.6.0 April 2026
  • · txt token — color contract expanded from 3 to 4 parts: background / txtOn / border / txt
  • · txt represents readable text on canvas (not on a colored background); always WCAG-accessible against the ambient background
  • · txtBaseColorLevel — controls the starting palette level for txt lookup (default: 140)
  • · Structured text states (normal / action / active / focus) propagate txt through all layers
  • · Foundation flat aliases: foundation.txt.info, foundation.txt.primary, foundation.txt.promo
  • · textExposure — controls which families get foundation.txt.* aliases (default: feedback only)
  • · Breaking: text aliases no longer source from surface.* — unified generation from palette
v3.5.2 April 2026
  • · AI UI Integration Program — formal contract for AI agent token consumption (Cursor, Claude Code, GitHub Copilot)
  • · ai:init command — injects editor integration files into consumer workspace (.cursor/rules/, .claude/skills/, .github/instructions/, docs/context/)
  • · Component archetypes: Button, Dialog, Input, Badge, Select, Card, Tabs — canonicalized token decision models
  • · Foundation Styles as preferred AI consumption path — sanctioned typography.css and elevation.css classes
  • · Portal rule for headless UI (Base UI, Radix) — applies theme class to document.body
  • · Base UI validation sandbox + Radix parity sandbox
v3.4.0 April 2026
  • · New figma:generate command — generates and maintains the three files Tokens Studio needs ($themes.json, $themes.engine.json.template, $metadata.json)
  • · Smart merge: Figma-owned fields (id, $figmaStyleReferences, variableIDs) are preserved; structure is regenerated on every run
  • · Stable IDs via SHA1 of "group:name" — no random IDs forcing Figma re-sync
  • · Architecture schema as single source of truth — all layers propagated via sync:architecture
  • · colorContrastDecompose: API for custom contrast-based palette decomposition
  • · surface/txtOn validation — automatic warning when txtOn is out of scale
  • · Non-interactive AA auto-regeneration when acceptAALevelFallback is active
v3.0.0 April 2026
  • · Package-first architecture — @aplica/aplica-theme-engine published as a standalone NPM package
  • · Consumer workspace model — configuration and data live in the consumer project, not the package
  • · Public configuration APIs: /config and /transformers/config for extensibility
  • · aplica-theme-engine init — workspace scaffolding with wizard or starter template
  • · migrate:legacy-consumer — automated migration for pre-v3 monolithic projects
  • · Clear separation between data/ (generated) and dist/ (build) inside the consumer workspace
v2.26.0 April 2026
  • · Foundation Styles Generation — generates typography_styles.json and elevation_styles.json per foundation brand
  • · Composite CSS classes at dist/css/foundation/{brand}/typography.css and elevation.css
  • · Typography as composite style: seven properties in one class, referencing semantic tokens
  • · Elevation as composite style: box-shadow per level (level_minus_one through level_five)
  • · Values resolve at runtime from the active theme file — theme switching updates them automatically
v2.22.x – v2.25.x March–April 2026
  • · Dimensions in rem for CSS output — CSS uses rem; JSON/ESM/CJS keep px
  • · Focus state for interface — focus tokens added to the function layer
  • · txtOnStrategy: "custom-tint" — allows custom color for text on brand backgrounds
  • · Nano and zetta typographic scales — extremes of the type size scale
  • · Per-theme configurable elevation — each brand can have independent shadows
  • · Configurable border offset — granular border offset control per token
v2.0.0 December 2025 legacy
  • · Dynamic theme generator — replaced manual token generation
  • · Full OKLCh pipeline — color decomposition into 19-level palettes
  • · Dark mode inversion algorithm: dark[N] = light[20-N]
  • · 4 variants per theme: light-positive, light-negative, dark-positive, dark-negative
  • · Canonical naming and naming contract (canonical-taxonomy-and-naming-contract)
  • · V1 → V2 migration bundle
v1.x 2025 legacy
  • · Base token system — CSS custom properties, JSON, ES Modules, TypeScript declarations
  • · Formalization of depth, opacity, typography, and borders
  • · Monorepo compatibility
  • · Partially manual tokens — limitation identified, resolved in v2
Alpha 2020–2021 legacy
  • · Four founding decisions: semantic naming, layer separation, color decomposition, accessibility algorithm
  • · Conceptual exploration without dynamic generation — foundation of the current system

The full history of design decisions — including the V1→V2 mapping and the rationale for each change — is documented in 06 · History in the documentation.

Gostou? Apoie com um café