@aleph-alpha/design-tokens

Transforms design tokens from ui-library/tokens.json (Tokens Studio format) into platform-specific outputs that applications can consume directly — CSS custom properties, JS modules, or any format supported by Style Dictionary v4.

Installation

pnpm add @aleph-alpha/design-tokens

How to use

Backstage

Import the generated CSS and JS in your app. Example entry point (e.g. App.tsx):

// CSS — in your app entry (e.g. App.tsx)
import '@aleph-alpha/design-tokens/bui-theme.css';
import '@aleph-alpha/design-tokens/bui-spacing.css';

// JS — in your theme/config (e.g. theme.ts)
import { lightPalette, darkPalette } from '@aleph-alpha/design-tokens/mui-palette';
import { typographyConfig } from '@aleph-alpha/design-tokens/typography';

For more information, see BACKSTAGE.md.

How it works

The build script (sd.config.mjs) reads the multi-set tokens.json and runs Style Dictionary with the Tokens Studio transforms to resolve the 3-tier token architecture:

primitives (raw values) → theme (AA Base) → mode (Light / Dark)

Color tokens go through the full chain. Spacing and radius are mode-independent (primitives + theme only). Typography bypasses Style Dictionary entirely — it's generated from a declarative mapping in bui-mapping.mjs because the global set has cross-references that break the preprocessor.

Build

cd packages/design-tokens
pnpm build

Or via Nx from the workspace root:

npx nx build design-tokens

Supported targets

| Target | Docs | |--------|------| | Backstage | BACKSTAGE.md — BUI CSS variables, MUI palette, typography |

Extending

To add a new output target:

1. Define a new platform with transforms, format, and output files in sd.config.mjs
2. Add the new output to package.json exports