Tokens · @luz-ds/tokens

Tokens

CSS custom properties for every colour, space, size and type value. Use the semantic ones: they change with the color mode.

Two layers

Primitives hold raw values: --luz-blue-60, --luz-space-md. They are the same in every mode.
Semantic tokens give a colour a job: --luz-text-primary, --luz-surface-page. Each mode points them at different primitives.
Space, size, radius, shadow and type scales, font roles, breakpoints and motion are primitives that components use directly: they do not change with the mode.

packages/tokens/tokens.json        the source of the primitives
packages/tokens/src/semantic.css   the semantic colours, per mode
dist/luz-tokens.css                both layers, and the ET Book font
dist/tokens.css                    both layers, no font

Use semantic colours, never primitive ones

A component that uses a primitive colour looks right in one mode and wrong in the others.

/* Do: semantic tokens follow the mode */
.panel {
  color: var(--luz-text-primary);
  background: var(--luz-surface);
  border: 1px solid var(--luz-divider);
  padding: var(--luz-space-md);
}

/* Don't: a primitive colour stays the same in dark mode */
.panel {
  color: var(--luz-gray-100);
  background: var(--luz-blue-10);
}

Text on a solid fill

Behind --luz-text-on-fill, use a fill token, not the brand or status colour.

The fills: --luz-brand-fill, --luz-brand-fill-hover, --luz-brand-fill-active and --luz-color-danger-fill.
In light and high contrast they equal the brand and danger colours. In dark mode they are a step darker: the dark brand colour is light enough to read as text, and white on it falls below 4.5:1.

Token families

Color

Every colour a component may use, named by its job, with its value in light, dark and high contrast side by side.
Spacing and sizing

The space scale for gaps and padding, and the heights of buttons and fields.
Typography

The three font stacks, the type scale in rem, and the smallest size each kind of text may use.
Color modes and themes

Switch between light, dark and high contrast with one attribute, or make a look of your own.
Radius

The corner radius scale: square, 2px, 4px at most, and round.
Shadows

The elevation scale: how far a surface seems to float above the page.
Motion

The durations and easings of every transition, which drop to zero when the reader asks for reduced motion. Ships with @luz-ds/tokens.
Layers

Which layer sits on top: the z-index of every overlay, in order. Ships with @luz-ds/core.
Layout and breakpoints

How wide content gets, and where the layout changes. Widths ship with @luz-ds/core, breakpoints with @luz-ds/tokens.
Color palette

The primitive colour scales. For theme authors only: components never use them.
Tokens in Figma

The tokens as one design-tokens file for Figma variables and other design tools, with the same names and the three modes.
Contrast check

Check your own color overrides against the contrast LUZ promises, with one command or in the page, before they reach a user.
Make your own theme

LUZ ships one look in three color modes. A theme of your own is a file of semantic tokens: start from the template, check it, load it.