@dloizides/design-tokens

Framework-agnostic design-token source for the dloizides.com portfolio — the cross-stack unifier (task #78). One typed token set per app, seeded byte-for-byte from each app's current values, emitted in three forms from one source.

#1 rule — behaviour-preserving extraction, not a redesign. Every preset mirrors the app's existing look. Adopting this package changes nothing visually. Runtime tests assert the RN output deep-equals the app's current DEFAULT_THEME_CONFIG and the AML CSS reproduces ui.css's :root verbatim.

Values only — no components. (Shared React components live in @dloizides/ui-layout, ui-forms, ui-feedback, ui-icons, ui-tables.)

The four output forms

One DesignTokens object per app feeds four pure emitters:

import {
  AML_TOKENS, EREVNA_TOKENS, KATALOGOS_TOKENS, PRESETS,
  toCssVars, toRnTheme, toTailwindPreset, toUiTheme,
  AML_CSS_VAR_NAMES, DEFAULT_CSS_VAR_NAMES,
} from '@dloizides/design-tokens';

// (a) AML console — reproduces wwwroot/shared/ui.css :root exactly
const css = toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES);

// (b) RN-web — drop in as the tenant-theme fallback (deep-equals the current default)
const rnDefault = toRnTheme(EREVNA_TOKENS);

// (c) DOM-React ThemeStudio — spread into tailwind.config.presets
const tw = toTailwindPreset(KATALOGOS_TOKENS);

// (d) Shared UI kit — hand straight to <UiProvider theme={…}>
const uiTheme = toUiTheme(MY_TOKENS);

toUiTheme is a LOSSLESS carrier

toUiTheme exists because the naive projection an app writes by hand — value => ({ '100': v, '500': v, '700': v }) — collapses a scale to one value, silently discarding the deeper brand step and every status background tint. A provider fed that way cannot reproduce the palette it was built from, which is what stops a shared component (StatCard, ThemedTextInput, Field) from rendering on-brand in a consuming app.

Every token lands in an addressable slot, so an app can project its whole palette back out of the live provider rather than keeping a static parallel copy:

The UiTheme shape is declared structurally in this package (as RnThemeConfig declares TenantThemeConfig), so the zero-dependency / zero-peer guarantee holds: the token source never depends on the kit it feeds.

The per-app presets

Each preset is seeded from that app's current source of truth:

RN presets carry no typography/radii/shadows/extensions — the RN theme has no centralized tokens for those today, so they are omitted (nothing to emit → zero change). The AML preset carries the richer superset (dark app-shell, ink scale, verdict palette, radii, shadows, fonts) in its extensions group.

FINREG module colours (FINREG_MODULE_COLORS, 1.5.0)

FINREG is a multi-module product (Payments / Accounting / CRM). Its interim EDA logo binds a colour to each module — the three orbits are the three modules — so colour reads as module identity rather than as one app's brand primary. Those tokens therefore sit beside the per-app presets, not inside one:

The base hexes are a decided design input (the logo), transcribed verbatim. They are light fills — none clears the WCAG AA 4.5:1 text floor on white — so anything painting a module colour as text or an icon on white uses onWhite, the darkened same-hue companion. The onWhite values were derived (lightest shade of the hue that still clears AA, carried a little past the floor) and both halves are pinned by finregModules.test.ts with their measured ratios, so a drift below AA fails the build. This is the SOURCE of these hexes — consumers read the token, they do not re-declare the literal (no-raw-color-literal).

Motion tokens (DEFAULT_MOTION, 1.7.0)

Motion is uniform across every portal, so — unlike colour — there is ONE shipped default rather than one per preset. DEFAULT_MOTION carries durations (ms) and easings:

instant (0) is the reduced-motion collapse target. Each easing carries both a web css cubic-bezier(...) string and the bezier [x1,y1,x2,y2] control points, so @dloizides/ui-motion can build a matching RN Easing.bezier(...) and web + native animate on the same curve. motion is an OPTIONAL field on DesignTokens (a preset MAY override it), so existing presets/emitters are byte-identical.

The token shape (aligned to TenantThemeConfig)

The core fields intentionally mirror @dloizides/tenant-theme-web's TenantThemeConfig (primary, secondary, accent, semantic, light, dark, typography, branding) so a per-tenant theme override layers cleanly on top of a preset — the tenant blob and the preset speak the same field names. Fields the core cannot express (a dark app-shell, an ink scale, sanctions verdict triads) live in an optional extensions group and are documented as Stack-A supersets, not part of the TenantThemeConfig contract.

Three additions (1.2.0) are core rather than extensions, because they are needed by any app with a status badge or a filled brand button — not by one stack:

All optional, and every emitter emits them only when a preset declares them, so presets that predate 1.2.0 produce byte-identical output.

The cross-stack naming contract (#78b)

Different stacks use different CSS-variable names for the same token. toCssVars takes a name map (CssVarNames) that says which CSS variable each token field emits as; a field mapped to undefined is skipped. Two maps ship:

• DEFAULT_CSS_VAR_NAMES — canonical kebab names (--primary, --background, --radius, …), with a dark-mode block. Adopt these for a fresh consumer.
• AML_CSS_VAR_NAMES — the AML console's existing ui.css names, so nothing there changes.

AML name-mapping table (core → ui.css variable)

Open naming decisions (need a human call before wider adoption)

These were resolved conservatively to guarantee zero change, but a human should confirm the intended long-term semantics:

1. AML secondary/accent — AML has a single brand. The preset mirrors --brand into both so the core shape is complete, but ui.css reads neither. If AML ever gains a real secondary brand, set it here.
2. AML dark = the app-shell. AML has a dark shell over a light workspace, not a light/dark mode toggle. The preset seeds dark from the shell so the shape is complete, and the AML name map omits dark* so no dark-mode block is emitted (the shell is emitted from the shell extension in :root). If a real AML dark mode is introduced, this needs revisiting.
3. semantic.info — AML has no info colour; it mirrors --brand. Confirm before relying on info in AML.
4. RN radii/shadows. The RN apps have no centralized radius/shadow tokens today, so the RN presets omit them. If RN adopts a radius/shadow scale later, decide whether it should share AML's values or define its own.

Adoption (separate tasks — this package ships values only)

This package does not modify any consuming app. Adoption is tracked separately:

• AML: replace the hand-written :root in ui.css with toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES) output.
• erevna/katalogos: import toRnTheme(EREVNA_TOKENS) as the defaultThemeConfig fallback.
• ThemeStudio: spread toTailwindPreset(...) into tailwind.config's presets.

Scripts

npm run build (tsup → CJS+ESM+d.ts), npm test (jest, 100% coverage), npm run lint, npm run typecheck. Publish via ./publish.ps1 patch|minor|major.