@paradox-design/tokens

Design tokens for Paradox Design System. Plain JSON + a generator — zero runtime dependencies, no Lit. Use this package in React, Vue or Angular projects, or in plain SCSS.

Three layers

primitive  ──►  semantic  ──►  component

| Layer | Where | Example | Purpose | | ------------- | ---------------------------- | ---------------------------------------------------------- | -------------------------------------------- | | primitive | src/primitive/ | --pdx-color-blue-600: #2563eb | raw palette, do not use directly | | semantic | src/semantic/ | --pdx-color-action-primary-bg: var(--pdx-color-blue-600) | theme API — this is what themes override | | component | @paradox-design/components | --pdx-button-primary-bg | component API |

The rules are enforced by a machine, not by convention — scripts/validate-layers.mjs runs before every build:

• R1 — a primitive must have a literal value (no {references}),
• R2 — a semantic token must reference a primitive (exceptions are listed explicitly, with a reason),
• R3 — a semantic token must not point to another semantic token (the layer is flat),
• R4 — every reference must point to an existing token.

Installation and usage

npm install @paradox-design/tokens

CSS

/* Option 1: everything at once */
@import '@paradox-design/tokens/css';

/* Option 2: separately — when you want to swap the palette and keep the semantics */
@import '@paradox-design/tokens/css/primitive';
@import '@paradox-design/tokens/css/semantic';

⚠️ Order matters. semantic.css refers to variables from primitive.css through var(). Loading the semantic layer alone yields undefined values. This is deliberate — it lets you swap the palette without regenerating tokens.

SCSS

@use '@paradox-design/tokens/scss' as tokens;

.my-button {
  background: tokens.$pdx-color-action-primary-bg;
}

TypeScript / JavaScript

import { PdxColorActionPrimaryBg, PdxSpace4 } from '@paradox-design/tokens';

Every token is a separate named export (PdxPascalCase) holding a resolved value ('#2563eb', not var(--…)). Semantic values match the default theme — switching themes changes the CSS variables, not these constants. Use CSS custom properties for styling in the browser; the JS export is meant for places CSS cannot reach (canvas, charts, tests).

Source format: DTCG

The source of truth is JSON in the DTCG format ($value, $type) — the same format exported by Figma Tokens Studio. If Figma joins the workflow, you replace the files in src/ and touch nothing else.

Scripts

pnpm validate   # layer validation only
pnpm build      # validation + generating dist/
pnpm clean

Outputs

| Path | Format | Consumer | | --------------------------------------- | --------------------- | ---------------------- | | dist/css/{primitive,semantic,all}.css | CSS custom properties | browser | | dist/scss/_tokens.scss | SCSS variables | SCSS projects | | dist/js/tokens.{js,d.ts} | ESM + types | component code, tests | | dist/json/tokens.json | flat JSON | tooling, documentation |

Versioning

🔴 Tokens are public API. Removing a semantic token or changing its meaning is a major change, even if no component changed. Adding a token is a minor change.

License

MIT © Paradox Software