Overview

ZUI exposes its entire design system as CSS custom properties. Every colour, spacing value, font size, shadow, radius, easing curve, and z-index level is a token you can reference directly in your CSS.

Naming conventions

ZUI uses two distinct scale styles depending on the token type:

Numeric scales: 1, 2, 3…

Used when the scale is open-ended or maps to a raw numeric value. The number is the value itself or an index in a simple sequence.

T-shirt sizes: sm, md, lg…

Used when the scale has a bounded, semantic range — you pick a size relative to a baseline.

Named scales

Some tokens use descriptive names instead of a size or number:

Fluid tokens

Space and font-size tokens use clamp() to scale fluidly between a minimum and maximum viewport width. This means you get responsive sizing without media queries — values interpolate smoothly between breakpoints.

/* Space md: 24px at 320px viewport → 30px at 1350px */
--space-md: clamp(1.5rem, 1.3835rem + 0.5825vw, 1.875rem);

Space tokens also provide one-up pairs for fluid spacing that jumps between two steps:

/* Jumps from sm to md fluidly */
--space-sm-md: clamp(1rem, 0.7282rem + 1.3592vw, 1.875rem);

Theming with tokens

All tokens can be overridden. The recommended approach is to edit theme.css, which maps semantic tokens to the underlying palette:

:root {
  --color-theme: light-dark(var(--color-blue-600), var(--color-blue-400));
  --custom-font-sans: Inter;
  --radius-scale: 1.5;
}

See Theming for the full guide.

Token categories