Token Reference

Three layers. The foundation holds the raw ramps a theme re-tints; the semantic layer maps them to roles like surface-elevated and resolves both modes via light-dark(); the interaction layer times motion and stacks depth. How to write, scope and switch a theme is the Themes page; this one lists what exists.

@theme {
  /* Foundation Colors (oklch for better perception) */
  --color-neutral-50: oklch(0.965 0.006 240);
  --color-neutral-500: oklch(0.55 0.016 240);
  --color-neutral-900: oklch(0.15 0.012 240);

  /* Intent 500s darkened so white text passes WCAG AA */
  --color-primary-500: oklch(0.58 0.15 240);
  --color-success-500: oklch(0.5 0.15 140);
  --color-danger-500: oklch(0.5 0.17 25);
}

/* Semantic Layer – maps foundation to
   roles; light-dark() resolves both modes */
--color-surface-base: light-dark(
  var(--color-neutral-0), var(--color-neutral-900));
--color-text-primary: light-dark(
  var(--color-neutral-900), var(--color-neutral-100));
--color-primary: light-dark(
  var(--color-primary-600), var(--color-primary-500));

/* Interactive states */
--color-interactive-hover:
  oklch(from var(--color-primary-500) l c h / 0.1);
--color-interactive-focus: light-dark(
  var(--color-primary-500), var(--color-primary-400));

/* Interaction Layer – motion & depth */
--blocks-duration-fast: 150ms;
--blocks-duration-normal: 250ms;
--blocks-ease-gentle: cubic-bezier(0.25, 0.1, 0.25, 1);

--blocks-shadow-sm: var(--blocks-shadow-scale-sm);
--blocks-shadow-md: var(--blocks-shadow-scale-md);

Custom theming and dark mode used to live on this page. They moved to Themes → Write Your Own Theme and Themes → Dark Mode.

Intent Ramps

Six intent ramps (primary, secondary, success, warning, danger, info), each a full 50–950 ladder. The ramps are tuned so text-on-fill clears WCAG AA on every solid fill: white on the 500/600/700 fills in light mode, near-black on the lighter 400/500 fills in dark mode. It is the label colour for every solid intent, which is why it is not named after one of them. text-on-primary still exists, resolves to the same value and governs the primary fill alone, so retuning it cannot repaint success or danger along with it. Warning is the deliberate exception (its fill stays light in both modes and pairs with its own warm-dark text-on-warning).

Intent Roles

The primary intent carries 6 roles, listed below; every other intent carries them under the same suffixes, and the gaps are listed under the table. Solid things (a button, a badge, a progress bar) take the base fill, bg-primary, with text-text-on-fill as the label on it. Text in the intent's colour on a reading surface (a page, a card, a panel) or on the intent's own -subtle tint takes text-primary-text, the stop that clears AA there. Tailwind also emits text-primary from the fill token and nothing flags it; as text it lands below AA (4.28:1 on bg-primary-subtle), so write text-primary-text. text-primary-emphasis is the near-ink step for a heading or a strong statement. The two classes that look alike do opposite jobs: text-primary-text is text in the primary colour, text-text-on-fill (or its primary-only alias text-text-on-primary) is the label on a primary fill. The swatches render in whatever theme is active, on this site the docs skin's own primary; the light and dark stops under each token are the library's own.

• neutral has no -text token: its base already clears AA as text on every ground in every theme, so a -text role would only alias the base
• warning -text: the light stop is -800, the only rung of a yellow ramp that reads on white — it lands amber-brown while the fill stays yellow
• danger -text: the light stop is the fill's stop, red already reads on paper; dark needs -300 because sRGB red is too dim on the lightened panels at -400

Run urbicon css-reference intents (the urbicon CLI) for the stops of every other intent.

Neutral Intent Chrome

The neutral intent (bg-neutral, text-neutral, neutral borders) is built from a separate --color-warm-neutral-* ramp, but never renders it directly: each role re-derives the ramp stop through oklch(from … l c var(--neutral-chrome-hue)), keeping the ramp's lightness and chroma and taking only the hue from the knob. The knob defaults to 240, so the library's own chrome is cool, and re-tinting it is a one-line theme move (see Motion & Depth). The swatches below render in whatever theme is active: this docs site re-pins them to the warm ramp directly, which is why they look warm here.

Your own color tokens live in the same system: any --color-* variable declared in @theme gets its Tailwind utilities for free.

@theme {
  /* bg-brand-500, text-brand-500, border-brand-500, … */
  --color-brand-500: oklch(0.5 0.25 45);
}

Urbicon UI does not ship a custom spacing token layer. It uses Tailwind's built-in spacing scale directly. Apply spacing with the standard utilities (p-4, gap-2, m-6). Each step is 0.25rem × n, driven by Tailwind's own --spacing variable.

Sizes, weights, leading, tracking and families are Tailwind @theme variables; override them alongside your color ramps (Themes → Typography, including the paired --text-*--line-height rule). The two sub-xs steps are library-added and ship size-only; every other row re-tunes a Tailwind built-in.

Weights

Physical Scale

Real --radius-* CSS variables, each with a matching Tailwind utility.

Semantic Tiers

Components consume a 3-tier semantic vocabulary, not raw radii. Re-tint the three tier variables to reshape the whole library at once (the full cascade: Radius Tiers). A fourth token, --radius-bridge, is not a tier: it pairs pill triggers with their dropdown panels.

The interaction layer ships real --blocks-duration-* and --blocks-shadow-* variables (plus easing curves like --blocks-ease-gentle). Durations collapse to 1ms under prefers-reduced-motion; prefers-contrast: more widens the focus ring to 3px and darkens subtle borders to text colour; in print, shadows drop to none and hairlines promote to a real grey rule.

Theme-level chroma knobs

Two tokens let a theme match its chrome to its chassis without touching contrast. The four coloured themes set both; see blocks/src/lib/style/themes/forest.css. The Neutral theme sets neither, by design: it inherits the library-default cool grey chrome and leaves the shadow tint untouched.