Tokens Overview
How design tokens are structured, shipped, and consumed in UnflowUI.
UnflowUI's token system has three layers: primitives (raw values), semantic tokens (role-based mappings), and CSS variables (runtime consumption).
Layers
Primitive Semantic variable Utility
────────── ───────────────── ──────────────
grey-100 ────────► --bg-muted ────────────► bg-muted
grey-600 ────────► --fg-muted ────────────► text-fg-muted
--uf-accent ─────► --accent-primary ──────► bg-primaryPrimitive 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-muted maps to a value (grey-100) in light mode and another in dark mode, and the accent roles derive from the tenant's --uf-accent at runtime.
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 '@unflowio/tokens/css';Typography
The type scale is a set of Tailwind text-* steps, each with its own line height:
| Utility | Size / line height |
|---|---|
text-5xs | 8 / 10 |
text-4xs | 9 / 12 |
text-3xs | 10 / 12 |
text-2xs | 11 / 14 |
text-xs | 12 / 16 |
text-sm | 14 / 20 |
text-md, text-base | 16 / 24 |
text-lg | 18 / 28 |
text-xl | 20 / 28 |
text-2xl | 24 / 32 |
text-3xl | 28 / 36 |
text-4xl | 36 / 40 |
text-5xl | 48 / 56 |
Product UI uses the density steps on top of this scale (text-caption, text-ui, text-reading, text-section, text-page-title); see Product tokens.
Fonts: font-sans reads --uf-font-sans (Manrope by default, overridable per tenant), font-display is Syne and font-mono is JetBrains Mono.
Token package structure
packages/tokens/src/
├── tokens.css ← the source: palette, semantic roles, Tailwind @theme
├── colors.ts ← generated: palette
├── primitives.ts ← generated: scale, typography, radii, shadows, animation
├── semantic.ts ← generated: semantic roles (light, dark, derived)
└── css-variables.ts ← generated: the stylesheet as a string (deprecated)The TypeScript files are generated from tokens.css by scripts/generate-tokens.mjs before every build; edit the CSS, never the TS.