Design Tokens

Architecture

Three layers feed each other, then two axes (spacing, curves) adjust component-level density and corner sharpness independently of theme and mode.

Primitives

Layer 1 lives in :root and never changes. Every other layer ultimately resolves to a primitive.

Color palettes

21 palettes with 11 shades each (50 through 950); mono adds a 0 for pure white.

The CSS declares every shade in oklch(), with the original hex kept in a trailing comment. Rendering is unchanged — the values are the same colors, expressed in a perceptually uniform space so that generated ramps and contrast maths stay predictable. The TypeScript export still hands back hex strings.

Radius / sizing / spacing

Modes

Layer 2 reads data-modeand remaps backgrounds, foregrounds, and every palette's contextual alias. The Modes page has the full rundown — the visualisations below show the active mode for each surface tier.

Backgrounds

Foregrounds

Themes

Layer 3 reads data-theme and defines the semantic tokens components actually consume. Below: every group, every variant, rendered in the active theme + mode.

Container

Interactive

Inputs, selectable rows, hoverable items — anything the user targets with pointer or keyboard. --interactive-border is the system-wide focus-ring colour.

Action

Three tiers — primary (CTA), secondary (outline), tertiary (ghost) — each with the same shape: bg, fg, and border across default / hover / active / selected / disabled / inverse states.

Status

Five intent families — each with the same six-variant shape. Hover any swatch to see the full token name.

Data viz

Eight series, each with main / tint / shade. Distinct hues at distinct lightness levels — readable in light, dim, and dark.

Spacing scale

data-spacing drives three families — --spacing-* (gaps / padding), --size-* (component heights), and --font-size-* (text). The first two shift by one primitive rung; --font-size-* shifts by one typeset step. Bars below show the spacing family at the active data-spacing setting.

Typeset

Type is the one scale that is not a set of static rungs. Eluan ships a fluid typeset of ten steps — --font-size-step-6 down to --font-size-step-neg3 — and every step interpolates with the viewport, so a page reads well on a phone and on a desktop without a single media query in your app. The old numeric primitives (--font-size-12 … --font-size-60) are gone.

The ten steps

Each step is anchored at three viewport widths, matching the s / m / l viewport primitives. The small column steps by a minor third (×1.2), the large column by a major third (×1.25) — bigger screens get more typographic contrast.

Between the anchors the value is a two-segment clamp(): small→medium from 480px to 748px, then medium→large from 748px to 1024px. Below 480px every step pins to its small value; above 1024px, to its large value. The bend at the medium anchor is why there are two segments rather than one straight line.

Two companion tokens travel with every size and should always be applied together — --line-height-step-* and --letter-spacing-step-*. Tracking is expressed in em, so it scales with the fluid size automatically; headings tighten progressively to -0.03emat step 6, which is the optical correction a dedicated “Tight” cut would give without a second font payload.

In React, reach for the Typography component instead — it applies all three at once and picks a sensible element per variant.

Pinning with data-typeset

data-typeset is the fifth axis, and the only one whose default is to be absent. Leave it off and the steps follow the viewport; set it and every step freezes to one column.

EluanProvider exposes this as defaultTypeset plus typeset / setTypeset on useEluanTheme(). Only explicit pins are persisted — "auto" is the absence of a preference, so it clears the eluan:typeset key rather than storing a value. See the Theming guide.

Density re-indexing

The --font-size-* aliases still exist, but they no longer hold values — each one selects a step, and data-spacing shifts which one, exactly as it shifts --spacing-* and --size-* by one primitive rung. Wide saturates at the top of the ladder (4xl and 5xl both land on step 6), mirroring compact, where xs and sm have always shared a rung.

So the two axes compose: density picks the rung, and the typeset (or the viewport) decides how big that rung is.

Curves scale

data-curves drives --curves-*. Six levels, backed by radius primitives.

Usage

Tokens are plain CSS custom properties — reference them anywhere a CSS value is accepted. No build step, no plugin, no configuration: in a stylesheet, in a style attribute, or in a stylex.create declaration.

Because the tokens stay as var() references rather than being inlined at build time, they re-resolve whenever the theme, mode or density axis changes — no recompile. For one-off scoped overrides, set CSS variables inline:

For runtime mode / theme switching with persistence and font preloading, use the EluanProvider — see the Theming guide.