Design Tokens
A comprehensive design token system built with CSS custom properties and Tailwind 4. Organized in semantic layers for consistent theming and easy customization.
Token Architecture
Foundation Layer
Base design decisions like colors, spacing, and typography scales.
Raw ValuesSemantic Layer
Intent-based tokens that map foundation tokens to semantic meanings.
ContextualInteraction Layer
Motion, shadow, and focus tokens for consistent animations and depth.
Motion & DepthFoundation Colors
Semantic Tokens
Interaction Layer
Color System
Neutral Palette
primary
success
warning
danger
Spacing Scale
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.
| Utility | Value | Pixels | Visual |
|---|---|---|---|
| p-0 / gap-0 | 0 | 0px | |
| p-1 / gap-1 | 0.25rem | 4px | |
| p-2 / gap-2 | 0.5rem | 8px | |
| p-3 / gap-3 | 0.75rem | 12px | |
| p-4 / gap-4 | 1rem | 16px | |
| p-6 / gap-6 | 1.5rem | 24px | |
| p-8 / gap-8 | 2rem | 32px | |
| p-12 / gap-12 | 3rem | 48px |
Typography Scale
Type sizes are Tailwind's built-in text-* utilities — there
are no custom font-size CSS variables to import or override.
| Utility | Value | Pixels | Example |
|---|---|---|---|
| text-xs | 0.75rem | 12px | The quick brown fox |
| text-sm | 0.875rem | 14px | The quick brown fox |
| text-base | 1rem | 16px | The quick brown fox |
| text-lg | 1.125rem | 18px | The quick brown fox |
| text-xl | 1.25rem | 20px | The quick brown fox |
| text-2xl | 1.5rem | 24px | The quick brown fox |
Border Radius
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 these three variables to reshape the whole library at once — see the Tier System for the full cascade.
| Token | Value | Used by |
|---|---|---|
| --radius-commit | 9999px | Pill/round — actions, identity, status (Button, Badge, Toggle) |
| --radius-modify | var(--radius-sm) · 4px | Editable surfaces, navigation (Input, Select, Tab, Menu) |
| --radius-contain | var(--radius-xs) · 2px | Containers, panels (Card, Alert, Dialog, Tooltip) |
Motion & Depth
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; shadows drop to none in high-contrast
mode.
| Duration token | Value |
|---|---|
| --blocks-duration-instant | 75ms |
| --blocks-duration-fast | 150ms |
| --blocks-duration-normal | 250ms |
| --blocks-duration-slow | 350ms |
| --blocks-duration-slower | 500ms |
| --blocks-duration-slowest | 750ms |
| Shadow token | Source |
|---|---|
| --blocks-shadow-xs | var(--color-shadow-xs) |
| --blocks-shadow-sm | var(--color-shadow-sm) |
| --blocks-shadow-base | var(--color-shadow-base) |
| --blocks-shadow-md | var(--color-shadow-md) |
| --blocks-shadow-lg | var(--color-shadow-lg) |
Custom Theming
Use Tailwind 4's @theme directive to customize design tokens and create your own brand theme.
Custom Theme Example
Theming Best Practices
- Use semantic color names instead of specific color values
- Test your theme in both light and dark modes
- Ensure sufficient contrast ratios for accessibility
- Consider using OKLCH color space for better perceptual uniformity
- Keep your custom tokens organized and documented
Dark Mode Support
Design tokens automatically adapt to dark mode using light-dark(). No
manual dark: overrides needed.