Design Tokens
Three layers of CSS custom properties plus two adjustment axes. Every component consumes the top semantic layer; lower layers cascade through attribute selectors on the document root.
Architecture
Three layers feed each other, then two axes (spacing, curves) adjust component-level density and corner sharpness independently of theme and mode.
Primitives
Raw values — colors, radius, sizing, spacing, fonts.
--color-blazeorange-500: #ff5100--radius-radius-12: 0.75rem--spacing-space-16: 1remModes
data-mode={light, dim, dark}. Sets backgrounds, foregrounds, and per-palette aliases.
--backgrounds-primary: var(--color-mono-0)--foregrounds-primary: var(--color-mono-950)--blazeorange-main: var(--color-blazeorange-500)Themes
data-theme={industrial-retro, minimal, …}. Component-level semantic tokens — what components actually use.
--action-primary-bg: var(--blazeorange-main)--container-bg: var(--backgrounds-primary)--font-heading: "Geist", sans-serifSpacing
data-spacing={compact, standard, wide}. Adjusts every --spacing-*, --size-*, and --font-size-* token.
--spacing-md: var(--spacing-space-12)Curves
data-curves={sharp, slight, sweeping}. Adjusts every --curves-* token.
--curves-md: var(--radius-radius-12) Primitives
Layer 1 lives in :root and never changes. Every other layer ultimately resolves to a primitive.
Color palettes
20 palettes. 19 of them have 11 shades (50 through 950); mono adds a 0 for pure white.
monoblazeorangebluechillblueribbonbostonbluecerisecrimsonelectriclimeelectricvioletforestgreengossamerlochmaramaitaipurpleheartredvioletrocksprayseagreenteaktorchredvioleteggplant 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
--backgrounds-primaryprimary
--backgrounds-secondarysecondary
--backgrounds-tertiarytertiary
--backgrounds-quaternaryquaternary
--backgrounds-quinaryquinary
Foregrounds
--foregrounds-primaryprimary
--foregrounds-secondarysecondary
--foregrounds-tertiarytertiary
--foregrounds-quaternaryquaternary
--foregrounds-quinaryquinary
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
--container-bgSurface (cards, popovers, page bg)
--container-bg-altAlt surface (subtle stripe)
--container-bg-inverseInverted surface
--container-borderHairline border
--container-border-altStronger border
--container-border-inverseInverted border
--container-fgBody text
--container-fg-altMuted text
--container-fg-inverseInverted text
Interactive
Inputs, selectable rows, hoverable items — anything the user targets with pointer or keyboard. --interactive-border is the system-wide focus-ring colour.
--interactive-bgResting
--interactive-bg-hoverHover
--interactive-bg-activeActive
--interactive-bg-selectedSelected
--interactive-bg-disabledDisabled
--interactive-bg-altAlt resting
--interactive-bg-alt2Alt 2
--interactive-borderFocus / default border
--interactive-border-altAlt border
--interactive-fgForeground
--interactive-fg-altMuted / icon
--interactive-fg-activeActive fg
--interactive-fg-selectedSelected fg
--interactive-fg-disabledDisabled fg
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.
Action primary
Filled CTA — the most prominent action.
--action-primary-bgBackground
--action-primary-bg-hoverHover
--action-primary-bg-activeActive
--action-primary-bg-selectedSelected
--action-primary-bg-disabledDisabled
--action-primary-bg-inverseInverse
--action-primary-fgForeground
--action-primary-fg-activeActive fg
--action-primary-fg-disabledDisabled fg
--action-primary-fg-inverseInverse fg
Action secondary
Outline button — secondary actions.
--action-secondary-borderBorder
--action-secondary-bg-hoverHover bg
--action-secondary-bg-activeActive bg
--action-secondary-bg-selectedSelected bg
--action-secondary-bg-disabledDisabled bg
--action-secondary-fgForeground
--action-secondary-fg-altAlt fg
--action-secondary-fg-activeActive fg
--action-secondary-fg-inverseInverse fg
Action tertiary
Ghost button — tertiary / passive actions.
--action-tertiary-bgBackground
--action-tertiary-bg-hoverHover
--action-tertiary-bg-activeActive
--action-tertiary-bg-selectedSelected
--action-tertiary-bg-altAlt bg
--action-tertiary-borderBorder
--action-tertiary-fgForeground
--action-tertiary-fg-altAlt fg
--action-tertiary-fg-activeActive fg
Status
Five intent families — each with the same six-variant shape. Hover any swatch to see the full token name.
--destructive-* — Errors, dangerous actions
--destructive-bgbg
--destructive-bg-altbg-alt
--destructive-bg-inversebg-inv
--destructive-borderborder
--destructive-fgfg
--destructive-fg-altfg-alt
--cautionary-* — Warnings, attention needed
--cautionary-bgbg
--cautionary-bg-altbg-alt
--cautionary-bg-inversebg-inv
--cautionary-borderborder
--cautionary-fgfg
--cautionary-fg-altfg-alt
--important-* — High-emphasis flags
--important-bgbg
--important-bg-altbg-alt
--important-bg-inversebg-inv
--important-borderborder
--important-fgfg
--important-fg-altfg-alt
--informative-* — Neutral information
--informative-bgbg
--informative-bg-altbg-alt
--informative-bg-inversebg-inv
--informative-borderborder
--informative-fgfg
--informative-fg-altfg-alt
--positive-* — Success, confirmation
--positive-bgbg
--positive-bg-altbg-alt
--positive-bg-inversebg-inv
--positive-borderborder
--positive-fgfg
--positive-fg-altfg-alt
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), --font-size-* (text). Bars below show the spacing family at the active data-spacing setting.
--spacing-xxs0.125rem--spacing-xs0.25rem--spacing-sm0.5rem--spacing-md0.75rem--spacing-lg1rem--spacing-xl1.25rem--spacing-2xl1.5rem--spacing-3xl2.5rem--spacing-4xl5remCurves scale
data-curves drives --curves-*. Six levels, backed by radius primitives.
--curves-xxs2px--curves-xs4px--curves-sm8px--curves-md12px--curves-lg16px--curves-xl24pxUsage
Tokens are plain CSS custom properties — reference them anywhere a CSS value is accepted. In Tailwind v4 use arbitrary-value syntax with the appropriate type hint.
The color: and length: hints are required in Tailwind v4 — without them, the var resolves to a generic value and the utility silently falls back. For one-off scoped overrides, set CSS variables inline:
For runtime mode / theme switching with persistence and font preloading, use the RagnarProvider — see the Theming guide.