CHANGELOG

Version history

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

v3.14.0–3.14.6 May 2026 latest

· Dynamic interaction state overrides (3.14.5): overrides.interaction replaces and extends the legacy overrides.interface.function.* form — overrides can now target function or feedback groups, specific items (e.g. primary, warning_default), solid or ghost presets, and individual states (normal, action, active, focus, disabled); override colors pass through the full decomposition pipeline (dilution, base adaptation, quadrant mirroring, accessibility text) instead of being applied as raw patches
· Figma brand bundle splitting (3.14.0): figma:generate now automatically splits oversized brand token bundles into semantic chunks (_brand_product.json, _brand_text.json, _brand_interface.json) when the token count exceeds the Figma per-collection limit (default 5,000 tokens); the logical token contract and dist/ output are unchanged — splitting only affects the intermediate data/brand/ files consumed by Tokens Studio; override the limit via the APLICA_THEME_ENGINE_BRAND_TOKEN_LIMIT environment variable
· Bug fixes (3.14.1–3.14.4): brand shard groups preserved in figma themes; underscore filename convention adopted for Tokens Studio compatibility; legacy dotted shard names excluded from figma output

v3.13.5–3.13.8 May 2026

· Mode-aware feedback decomposition (3.13.6): options.interaction.decomposition.modeResolution accepts 'quadrant' (default, existing behavior) or 'mode' — when set to 'mode', feedback tokens follow light/dark semantics without quadrant polarity inversion, producing the same surface, text, and border colors on positive and negative surfaces within the same mode
· Bug fixes (3.13.5, 3.13.7, 3.13.8): dilution-derived colors now correctly mirror across quadrants (light-positive == dark-negative); mode-aware feedback text and borders align with surface semantics; quadrant mirroring for default feedback (modeResolution: 'quadrant') restored after a regression introduced in 3.13.6

v3.13.0–3.13.4 May 2026

· Preview Summary view (3.13.0): theme-engine preview now includes a View dropdown to switch between Detailed (existing explorer) and Summary modes — Summary renders a compact table showing background, txtOn, border, txt, and contrast ratios for every semantic family and state, optimized for fast QA across theme combinations
· Anchor-aware dilution (3.13.1–3.13.3): dilution method gains target: 'anchor' — moves interaction states toward a configurable chromatic anchor instead of always targeting white/black or the canvas; anchor.source accepts 'palette' (current brand palette family), 'hex' (fixed color), or 'token' (another generated scale); anchor.canvasAware and anchor.canvasMix let the anchor remain hue-stable while still lightening on light canvases and darkening on dark canvases
· Quadrant-aware base adaptation (3.13.4): options.baseAdaptation: true makes interaction normal surfaces (function/feedback) and product default surfaces respond to the active light/dark + positive/negative quadrant — by default normal and default remain fixed at the authored base color regardless of quadrant; opt in only when brands need those base surfaces to adapt

v3.12.0 April 2026

· 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.