Tokens Overview

UnflowUI's token system has three layers: primitives (raw values), semantic tokens (role-based mappings), and CSS variables (runtime consumption).

Layers

Primitive            Semantic               CSS variable
──────────           ────────────           ─────────────────
brand-500 ──────►   interactive.primary ──► --color-brand-500
grey-100 ────────►   bg.subtle ───────────► --color-grey-100
red-500 ──────────►  border.emphasis ─────► --color-red-500

Primitive tokens

Primitive tokens define the full colour palette — every colour family with shades from 50 to 950. They are the authoritative colour values, not used directly in components.

See Colors for the full palette.

Semantic tokens

Semantic tokens give colours a role. A semantic token like bg.subtle maps to a specific primitive (grey-100) and may map to a different primitive in dark mode.

See Semantic tokens for the full mapping.

CSS variables

All primitive tokens are exposed as CSS custom properties in the format --color-{family}-{shade}:

--color-brand-500: oklch(…);
--color-grey-100: oklch(…);
--color-red-500: oklch(…);

These variables are what Tailwind utility classes reference at runtime. You import them once via:

import '@unflow-ui/tokens/css';

Token package structure

packages/tokens/src/
├── colors.ts       ← primitive colour values
├── primitives.ts   ← spacing, typography, radii, shadows (in progress)
├── semantic.ts     ← semantic role → primitive mapping (light + dark)
└── tokens.css      ← CSS @theme block with all custom properties