Why teams lose months on theming

Six recurring pains when shipping multi-theme, whitelabel or dark mode — and how Aplica DS solves them with a single config.

Hardcoded values

#2563EB repeated across 50+ files. Changing the brand color becomes a manual find-and-replace across the entire codebase.

Dark mode = redo everything

Every new color needs a manual dark variant. Tokens double, bugs too.

Platforms diverge

CSS, React Native and Figma live in separate worlds. Divergence is a matter of time.

No semantic contract

blue-500 is a color, not a role. Without a decision layer, engineers guess — and get it wrong.

New brand = fork the system

Whitelabel without architecture becomes a fork. Each new brand multiplies maintenance cost.

Locked into one component library

Switching from Radix to Base UI, or using a proprietary DS, means rebuilding tokens from scratch. Aplica DS is agnostic: the semantic layer connects to any library via integration Skills.

WHY APLICA DS

Not just another token generator

Style Dictionary handles multi-platform output. CSS variables handle local customization. What both lack is the semantic layer that gives tokens intent.

	Manual CSS vars	Style Dictionary	Aplica DS
5-layer semantic structure	—	—	✓
Dark mode by construction (OKLCh)	—	—	✓
Multi-brand from one config	—	—	✓
Multi-platform output (CSS, JSON, TS…)	—	✓	✓
Deterministic pipeline (same config → same output)	—	partial	✓
Built-in algorithmic accessibility	—	—	✓

5-layer semantic structure

CSS vars — Style Dictionary — Aplica DS ✓

Dark mode by construction (OKLCh)

CSS vars — Style Dictionary — Aplica DS ✓

Multi-brand from one config

CSS vars — Style Dictionary — Aplica DS ✓

Multi-platform output (CSS, JSON, TS…)

CSS vars — Style Dictionary ✓ Aplica DS ✓

Deterministic pipeline (same config → same output)

CSS vars — Style Dict. partial Aplica DS ✓

Built-in algorithmic accessibility

CSS vars — Style Dictionary — Aplica DS ✓

SEMANTICS + AI

Tokens that communicate intent — not just values

A semantic token doesn't store a color. It stores a meaning. That changes what tools, engineers, and AI agents can do with it.

Compressed context for AI

An agent reading action.bg.danger.default understands its purpose without extra prompting. Semantics is machine-readable documentation, native to the token.

Unlimited brands, zero rewrite

The semantic contract is fixed. Values shift per brand, mode, or surface. Adding a new brand means configuring — not refactoring. The system grows without technical debt.

One contract for humans, engineers, and agents

Designer, dev, and LLM read the same token and reach the same conclusion. Semantics removes the translation layer between disciplines — and between product cycles.

NEW · v3.5

AI Skills — Cursor, Claude Code & Copilot

aplica-theme-engine ai:init injects integration skills into the workspace. Agents understand layers, states, txtOn, txt, and component archetypes — no hardcoding, no guessing variable names.

NEW · v3.6

Expanded color contract — `txt` token

The color contract expanded from 3 to 4 parts: background / txtOn / border / txt. The txt token is the readable text color on canvas — distinct from txtOn, which is text on the element's own colored background. Flat aliases at foundation.txt.*.

NEW · v3.7

Typed output — `jsonTyped`

New output format with structured metadata per token: type, value, description, and path — all key names configurable. Ideal for tooling, code generators, and AI agents that need context beyond the raw value.

See it in practice — the same token resolving differently across each brand:

Theme Playground

Switch brand, mode and surface. Foundation tokens resolve in real time through the Semantic layer.

Brand

Mode

Surface

Active Theme:Joy·light·positive

Typography

DISPLAY — fontFamilies-display

Display titles

TITLE — heading-title_2

Heading Title — fontFamilies-main

BODY — content-body

Body text with the theme's main font.

LABEL — content-label

Interface label / caption

CODE — fontFamilies-code (IBM Plex Mono)

--foundation-bg-brand-default

Foundation Colors

txt-title

bg-primary

txt-body

bg-secondary

txt-on-brand-default

bg-brand-default

txt-on-feedback-info

feedback-info

txt-on-feedback-success

feedback-success

txt-on-feedback-warning

feedback-warning

txt-on-feedback-danger

feedback-danger

Components

Example Card

Component using Semantic tokens for background, text and border.

Resolution chain

Foundation

→ semantic.color...

foundation.bg.brand.default

Short alias for product teams

Semantic

→ surface.color...

semantic.color.brand.branding
  .first.default.background

Purpose token — not a color, but a role

Surface

→ mode.interface...

surface.color.brand.branding
  .first.default.background

Surface context: positive / negative

Mode

→ theme.color.light.brand.branding.first.lowest.background

mode.interface.positive.branding
  .first.default.background

Luminosity context: light / dark

Brand

#e7398a

theme.color.light.brand.branding.first.lowest.background

Primitive value for Joy brand

Resolved value

Resolving...

Final value:

var(--resolving)

HOW IT WORKS

From config to token in 6 steps

One config file. One deterministic pipeline. Consistent, accessible tokens ready for any platform.

[01]

Directory verification

Ensures all data folders and files exist. Fails fast if anything is missing.

[02]

Dimensional scale

Generates the spacing scale in 3 variants: minor (8px), normal (16px), major (24px). Geometric progression, 10 steps each.

[03]

OKLCh pipeline

Decomposes each brand color into 19 lightness levels in the perceptual OKLCh color space. Dark mode derived mathematically: dark[N] = light[20-N].

[04]

Layer synchronization

Maps palette → Mode → Surface → Semantic. Produces 4 theme variants: light-positive, light-negative, dark-positive, dark-negative.

[05]

Foundation aliases

Generates short aliases for product teams: foundation.bg.primary, foundation.txt.title, foundation.spacing.medium — all pointing to the Semantic layer.

[06]

Multi-platform build

Style Dictionary compiles the generated tokens into CSS Custom Properties, JSON, ESM, CJS, and TypeScript declarations — ready for web, mobile, and Figma.

The result in code

01 · Config

Configure the engine in aplica-theme-engine.config.mjs.

import { defineThemeEngineConfig }
  from '@aplica/aplica-theme-engine/config';

export default defineThemeEngineConfig({
  paths: {
    configDir: './theme-engine/config',
    dataDir:   './data',
    distDir:   './dist'
  }
});

02 · Build

One command runs the full pipeline.

# run directly after npm install
npx theme-engine build

# or via package.json script
npm run tokens:build

03 · Usage

Foundation tokens ready for any platform.

@import './dist/css/foundation/engine/
         foundation.css';

.btn {
  background: var(--foundation-bg-brand-default);
  color:      var(--foundation-txt-title);
  padding:    var(--foundation-spacing-medium);
}

FOR WHOM

Three profiles, one engine

Each track has 6 progressive tutorials. From the designer working in Figma to the engineer integrating tokens in Radix, Base UI or any proprietary DS.

TRACK N1

Product Designer

Uses the system in Figma. Learns token vocabulary, built-in accessibility and automatic dark mode via Tokens Studio.

6 tutorials · ~3h Start N1 →

TRACK N2

System Designer

Configures and governs the Theme Engine. Creates themes, manages product colors and defines responsible overrides. Understands the semantic architecture to deliver whitelabel.

6 tutorials · ~4h · Prereq: N1 Start N2 →

TRACK N3

Design Engineer

Implements conformant components. Integrates tokens in React, Vue, React Native, Flutter or any component library (Radix, Base UI, proprietary). Adds brands to the engine via a single config file.

6 tutorials · ~5h · Prereq: N2 Start N3 →

Semantic themes for any UI library.

Why teams lose months on theming

Hardcoded values

Dark mode = redo everything

Platforms diverge

No semantic contract

New brand = fork the system

Locked into one component library

Not just another token generator

5-Layer Architecture

Tokens that communicate intent — not just values

Compressed context for AI

Unlimited brands, zero rewrite

One contract for humans, engineers, and agents

AI Skills — Cursor, Claude Code & Copilot

Expanded color contract — `txt` token

Typed output — `jsonTyped`

Theme Playground

Resolution chain

Resolved value

From config to token in 6 steps

Directory verification

Dimensional scale

OKLCh pipeline

Layer synchronization

Foundation aliases

Multi-platform build

Three profiles, one engine

Product Designer

System Designer

Design Engineer

100% open source

Where to start?

Product Designer

System Designer

Design Engineer

Semantic themes for any UI library.

Why teams lose months on theming

Hardcoded values

Dark mode = redo everything

Platforms diverge

No semantic contract

New brand = fork the system

Locked into one component library

Not just another token generator

5-Layer Architecture

Tokens that communicate intent — not just values

Compressed context for AI

Unlimited brands, zero rewrite

One contract for humans, engineers, and agents

AI Skills — Cursor, Claude Code & Copilot

Expanded color contract — txt token

Typed output — jsonTyped

Theme Playground

Resolution chain

Resolved value

From config to token in 6 steps

Directory verification

Dimensional scale

OKLCh pipeline

Layer synchronization

Foundation aliases

Multi-platform build

Three profiles, one engine

Product Designer

System Designer

Design Engineer

100% open source

Where to start?

Product Designer

System Designer

Design Engineer

Expanded color contract — `txt` token

Typed output — `jsonTyped`