Design Tokens

Intent Ramps

Six intent ramps — primary, secondary, success, warning, danger, info — each a full 50–950 ladder. The 500/600/700 stops are tuned dark enough that white text-on-fill passes WCAG AA on the solid fills — that 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). A separate warm-neutral ramp powers the themeable neutral intent chrome.

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.

Type is themeable exactly like color. Sizes, weights, leading, tracking and font families are Tailwind @theme variables — --text-sm, --font-weight-medium, --leading-tight, --tracking-wide, --font-sans, --font-mono — and you override them in the same @theme block that retunes --color-primary-500. This docs site is the proof: it rethemes the whole library's type by overriding --font-mono and --font-sans — see apps/docs/src/lib/style/rooms-docs.css.

/* app.css — the SAME @theme block that retunes color.
   Safe because the library never re-imports Tailwind: your
   @theme is compiled last and wins. */
@import 'tailwindcss';
@import '@urbicon-ui/blocks/style/index.css';

@theme {
  /* Families — blocks never sets `font-sans`, so body type simply
     inherits from your page. It DOES use `font-mono` (CommandPalette
     shortcut keys, JourneyTimeline meta), so this retunes those. */
  --font-sans: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  /* Size AND its paired line-height. Tailwind's built-in sizes each
     ship a --text-*--line-height; changing the size alone leaves the
     old rhythm behind on all ~128 text-sm call sites. */
  --text-sm: 0.9375rem;
  --text-sm--line-height: calc(1.375 / 0.9375);

  --font-weight-medium: 550;
  --leading-tight: 1.3;
  --tracking-wide: 0.02em;
}

Know where the leverage is. The library's usage is steep and lopsided: --text-sm reaches the most call sites by a wide margin, while nothing above text-xl is used at all — so overriding --text-6xl changes nothing in the library, and --text-sm reshapes it. And because blocks never sets font-sans, body type inherits from your page: you already own the font decision — no override needed.

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 — see the Tier System for the full cascade. 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 promotes hairline borders; in print, shadows drop to none.

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.

Use Tailwind 4's @theme directive to override tokens, or import one of the shipped themes — see Themes for the full gallery.

@import '@urbicon-ui/blocks/style/index.css';

/* Option A — import a shipped theme
   (neutral, ocean, forest, rose, sunset) */
@import '@urbicon-ui/blocks/style/themes/ocean.css';

/* Option B — re-tint the ramps yourself. The semantic layer
   consumes several stops (600/500 base, 700/400 hover,
   800/300 active, 900/200 emphasis, 50/900 subtle), so
   override the WHOLE ramp: keep each stop's lightness and
   chroma, swap only the hue. */
@theme {
  --color-primary-500: oklch(0.58 0.15 280);
  --color-primary-600: oklch(0.52 0.15 280);
  --color-primary-700: oklch(0.44 0.13 280);
  /* … all stops 50–950 with the new hue */

  /* The chassis, NOT optional: surface/text/border derive
     from neutral, so a purple brand on the default cool
     240 chassis reads broken. Same L/C, hue → 290. */
  --color-neutral-50: oklch(0.98 0.005 290);
  --color-neutral-500: oklch(0.55 0.016 290);
  --color-neutral-900: oklch(0.15 0.012 290);
  /* … all 15 stops (25–950) with the new hue. Leave
     --color-neutral-0 (pure white) alone — tinting it
     tints your white. */
}

/* Raw partial values — :root, never @theme (see Motion & Depth). */
:root {
  --blocks-shadow-tint: 0.2 0.025 290;
  --neutral-chrome-hue: 290;
}

/* Custom brand tokens get Tailwind utilities for free
   (bg-brand-500, text-brand-500, …) */
@theme {
  --color-brand-500: oklch(0.5 0.25 45);
}

Design tokens automatically adapt to dark mode using light-dark(): :root declares color-scheme: light dark, so the browser resolves the matching branch from the user's preference. A manual toggle only sets :root.light / :root.dark to override the color-scheme — no token duplication, and no manual dark: overrides needed.