Aplica DS — V3

Context

V3 is the current phase of Aplica DS (2024–present). It is the distribution phase: everything proven in V2 was repackaged so that any team can adopt it without forking or copying internal files.

The two structural changes that define V3:

1. Package-first — @aplica/aplica-theme-engine is published as a standalone npm package. Consumers install it as a dependency instead of copying source files.
2. Consumer workspace model — configuration and data live entirely in the consumer project. The package is a pure engine; it brings no opinions about brand, colors, or typography.

---

The Great Shift: From Copy to Package

In V2, teams adopted the Theme Engine by copying or forking the repository. Updates required manual merging. V3 replaced this model:

	V2	V3
Adoption	Copy / fork	npm install @aplica/aplica-theme-engine
Configuration	In the engine repo	In the consumer project (aplica.config.mjs)
Updates	Manual merge	npm update + migration bundle
Schema ownership	Engine-controlled	Consumer can override via paths.schemasDir

---

V3 Innovations

1. Standalone npm Package

npm install @aplica/aplica-theme-engine

The package exposes:

• defineThemeEngineConfig() — public configuration API with full TypeScript inference
• /config — importable config helpers
• /transformers/config — extensibility hooks for custom transformers

2. Consumer Workspace Scaffolding

npx theme-engine init

Interactive wizard that creates:

• aplica.config.mjs — project configuration
• data/ — schema and architecture files
• dist/ — build output directory

Alternatively, --template <starter> skips the wizard.

3. Automated V2 Migration

npx theme-engine migrate:legacy-consumer

Three subcommands for safe migration from pre-V3 monolithic projects:

Subcommand	Purpose
analyze	Reports what needs to change
convert	Applies the migration automatically
compare	Diffs the before/after state

4. Figma Integration via figma:generate

npx theme-engine figma:generate

Generates and maintains the three files Tokens Studio requires:

File	Purpose
data/$themes.json	Theme configuration for Tokens Studio
data/$themes.engine.json.template	Template for engine-managed fields
data/$metadata.json	Token metadata

Stable IDs via SHA1 of "group:name" — no random IDs that force re-sync in Figma. Figma-owned fields (id, $figmaStyleReferences, variableIDs) are preserved on every run.

5. Foundation Styles as CSS Classes

V3 graduated Foundation Styles — introduced in V2 2.26.0 — as the primary consumption path for component authors and AI agents:

# Generated by the engine
dist/css/foundation/{brand}/typography.css
dist/css/foundation/{brand}/elevation.css

Each class is a composite: typography classes bundle 7 CSS properties referencing semantic tokens; elevation classes bundle box-shadow per level. Values resolve at runtime from the active theme file — theme switching updates them automatically.

6. AI Skills Injection Program

npx theme-engine ai:init

Injects editor-specific context files into the consumer workspace:

Destination	Tool
docs/context/	All AI agents (shared)
.cursor/rules/	Cursor
.claude/skills/	Claude Code
.github/instructions/	GitHub Copilot

The injected files teach agents which token layer to read, how to map intent to semantic tokens, and when to prefer Foundation Styles over atomic token assembly.

8. theme-engine — preferred CLI alias (since 3.8.0)

npx theme-engine init
npx theme-engine ai:init
npx theme-engine build:all

theme-engine is now the preferred command name for consumer workspaces. The legacy aplica-theme-engine name is preserved as a compatibility fallback — existing scripts continue to work without changes.

All active documentation, onboarding flows, and consumer guides standardize on theme-engine first. The package name (@aplica/aplica-theme-engine) and config filenames (aplica-theme-engine.config.mjs) are unchanged.

---

7. AI UI Integration Program

A formal contract that specifies how AI agents consume the token system when generating UI:

• Preferred path: Foundation Styles (typography.css, elevation.css) — one class maps to a complete style decision
• Secondary path: Semantic tokens (action.bg.brand.default) — when fine-grained control is needed
• Never: Brand, Mode, or Surface layer tokens — those are engine internals

Seven component archetypes (Button, Dialog, Input, Badge, Select, Card, Tabs) define the canonical token decision model for each component type.

---

V3 milestone versions

Current version: 3.12.0 (2026-04-30)

• 3.12.0 — Enhanced interaction decomposition: options.interaction.groups.{function|feedback} allows function and feedback to use different decomposition methods and surface configs independently within the same theme; per-group surface overrides resolve by merging theme → surface → group → group-surface
• 3.11.0 — theme-engine preview --serve adds live reload — the browser refreshes automatically when dist/ changes; no manual reload needed while iterating on theme configs
• 3.10.1 — Bug fix: grouped interaction decomposition overrides (options.interaction.groups.*) now resolve correctly in all surface and state combinations
• 3.10.0 — Native AI guidance distribution: theme-engine ai:init now deploys context files from the published package instead of local templates; AI_CONTEXT.md and THEME_CONFIG_REFERENCE.md are packaged per release and updated automatically on ai:init after an upgrade
• 3.9.0 — Authored interaction decomposition modes (system-scale / dilution) for interface.function and interface.feedback; expanded solid / ghost surface presets via legacyStructure: false; per-state authored tuning under options.interaction.surfaces.{solid|ghost}.levels; theme-engine preview command generates static HTML preview in dist/preview/
• 3.8.5 — Trusted publishing release automation via GitHub Actions; runtimes upgraded to Node.js 24
• 3.8.4 — Negative *.txt tokens now follow the declared canvas contract all the way to dist/ for interface, feedback, disabled, and product branches; new mode.productBySurface branch ensures product polarity survives sync:architecture; test:txt-inversion now audits final distributable JSON in dist/
• 3.8.3 — Ambient readable text now follows the final file canvas in both polarities: brand.ambient.contrast.*, neutral.*, and grayscale.*.txt resolve against the declared contrast.base.positive.background; negative ambient surfaces resolve from the inverse mode canvas
• 3.8.2 — brand.branding now respects positive/negative surface polarity in semantic outputs via a dedicated mode.brand.brandingBySurface branch; dark mode follows the same inverse-surface rule as light mode
• 3.8.1 — Ambient txt accessibility correction: brand.ambient.neutral.*.txt and brand.ambient.grayscale.*.txt now validate against the declared contrast.base.{positive|negative}.background surface instead of the level background; regression coverage extended in test:txt-inversion
• 3.8.0 — theme-engine preferred CLI alias — shorter command for consumer workspaces; aplica-theme-engine preserved as a compatibility fallback; all active docs standardize on theme-engine first
• 3.7.5 — Tokens Studio-safe fix: disabled product readable-text branches no longer emit invalid txt: null nodes when generateTxt: true and textExposure.product: false
• 3.7.4 — Readable text inversion for negative surfaces: brand.text.negative.* now resolves correctly; product txt removed from public layers when product readable text is disabled; legacy migrator infers feedback text exposure from flat aliases
• 3.7.2 — brand.branding propagation fixed through mode before reaching surface and semantic outputs; legacy migrator now preserves generation.colorText contract automatically
• 3.7.1 — Ambient txt inversion fix at theme layer: brand.ambient now resolves readable text against the correct positive/negative background contexts
• 3.7.0 — jsonTyped output platform — first extensible output delivery with typed metadata (type, value, description, path); configurable via formatOptions.jsonTyped in transformers.config.mjs; backward compatible, existing json contract unchanged
• 3.6.4 — Migration fix: generate-foundation.mjs now correctly preserves txt.base.items in workspaces with custom product text families (e.g., Brewer-style themes with tada, ze)
• 3.6.3 — includePrimitives: false default in init scaffold, CLI onboarding banner, smoke coverage for ai:init
• 3.6.1 — generation.colorText workspace config (breaking config consolidation from per-theme to workspace)
• 3.6.0 — Four-part color contract: txt token added alongside background/txtOn/border; txtBaseColorLevel; text states (normal/action/active/focus) in all layers; breaking: text aliases no longer source from surface.*
• 3.5.2 — AI UI Integration Program — archetypes, portal rule for headless UI (Base UI, Radix)
• 3.5.0 — ai:init command — AI Skills Injection into consumer workspace
• 3.4.0 — figma:generate command — Tokens Studio scaffolding with stable SHA1 IDs
• 3.0.0 — Package-first architecture, consumer workspace model, public config API, init wizard, migrate:legacy-consumer

---

Reference Files

• npm package: @aplica/aplica-theme-engine
• Config API: aplica.config.mjs in the consumer project
• AI context: docs/context/ (injected by ai:init)
• Full changelog: CHANGELOG.md in the package repository
• AI UI program documentation: docs/context/ai-ui/ in the consumer workspace after ai:init