Design Tokens
Design tokens are CSS custom properties that provide consistent values across your design system. They adapt automatically to light and dark modes.
Colors
OKLCH-based seed-and-derive architecture with automatic light/dark mode switching via light-dark() function.
Architecture
VB's color system has four layers. Components should use the highest applicable layer:
| Layer | Examples | Who uses it |
|---|---|---|
| 1. Primitives & seeds | --color-gray-*, --hue-primary, --lightness-primary, --chroma-primary |
Token files only. Themes set seeds; core derives everything else. |
| 2. Brand slots | --color-primary, --color-secondary, --color-accent + hover/active/subtle |
Components when brand identity is intentional. |
| 3. Semantic UI tokens | --color-surface, --color-text, --color-border, --color-interactive |
Components for role-based colors. Preferred layer. |
| 4. Component-local tokens | --_color, --btn-color |
A single component seed derived from a semantic token. |
Gray Scale
| Token | Value | Description |
|---|---|---|
--color-gray-50 | oklch(98% 0 0) | Lightest gray |
--color-gray-100 | oklch(96% 0 0) | |
--color-gray-200 | oklch(90% 0 0) | |
--color-gray-300 | oklch(80% 0 0) | |
--color-gray-400 | oklch(70% 0 0) | |
--color-gray-500 | oklch(55% 0 0) | Mid gray |
--color-gray-600 | oklch(45% 0 0) | |
--color-gray-700 | oklch(35% 0 0) | |
--color-gray-800 | oklch(25% 0 0) | |
--color-gray-900 | oklch(15% 0 0) | Darkest gray |
Semantic Colors
Use semantic tokens for automatic light/dark adaptation.
| Token | Description |
|---|---|
--color-background | Page background |
--color-surface | Card/component surface |
--color-surface-raised | Elevated surface |
--color-surface-sunken | Recessed surface |
--color-surface-alt | Alternate surface (hover backgrounds, skeletons) |
--color-text | Primary text |
--color-text-muted | Secondary text |
--color-text-subtle | Tertiary text |
--color-border | Default borders |
--color-border-strong | Emphasized borders |
--color-border-muted | Subtle/muted borders |
--color-interactive | Buttons, links |
--color-interactive-hover | Interactive hover state |
Brand Colors
| Token | Description |
|---|---|
--color-primary | Primary brand color |
--color-primary-hover | Primary hover state |
--color-primary-subtle | Primary tint for backgrounds |
--color-secondary | Secondary brand color |
--color-accent | Accent/highlight color |
Status Colors
| Token | Hue | Description |
|---|---|---|
--color-success | 145 | Green for positive |
--color-warning | 70 | Yellow/orange for caution |
--color-error | 25 | Red for errors |
--color-info | 240 | Blue for informational |
Usage Example
Color tokens
/* Semantic colors adapt to light/dark mode */.card { background: var(--color-surface); color: var(--color-text); border: 1px solid var(--color-border);} /* Brand colors */.button { background: var(--color-primary); color: var(--color-text-on-primary);} .button:hover { background: var(--color-primary-hover);}Spacing
T-shirt size scale for consistent spacing throughout your design.
Spacing scale visualization:
3xs
2px
2xs
4px
xs
8px
s
12px
m
16px
l
24px
xl
32px
2xl
48px
3xl
64px
| Token | Value | Pixels |
|---|---|---|
--size-3xs | 0.125rem | 2px |
--size-2xs | 0.25rem | 4px |
--size-xs | 0.5rem | 8px |
--size-s | 0.75rem | 12px |
--size-m | 1rem | 16px |
--size-l | 1.5rem | 24px |
--size-xl | 2rem | 32px |
--size-2xl | 3rem | 48px |
--size-3xl | 4rem | 64px |
Numeric Aliases
Open Props compatible numeric scale for easy migration.
| Alias | Maps To |
|---|---|
--size-1 | --size-2xs |
--size-2 | --size-xs |
--size-3 | --size-m |
--size-5 | --size-l |
--size-7 | --size-xl |
--size-8 | --size-2xl |
--size-9 | --size-3xl |
Usage Example
Spacing tokens
/* T-shirt size scale */.section { padding: var(--size-l); /* 1.5rem / 24px */ margin-block: var(--size-xl); /* 2rem / 32px */ gap: var(--size-m); /* 1rem / 16px */} /* Numeric aliases (Open Props compatible) */.card { padding: var(--size-3); /* Same as --size-m */ gap: var(--size-2); /* Same as --size-xs */}Typography
System font stacks and a harmonious type scale.
Font Families
| Token | Stack |
|---|---|
--font-sans | system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif |
--font-serif | Charter, "Bitstream Charter", "Sitka Text", Cambria, serif |
--font-mono | ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, monospace |
Font Sizes
xs - 0.75rem (12px)
sm - 0.875rem (14px)
md - 1rem (16px)
lg - 1.125rem (18px)
xl - 1.25rem (20px)
2xl - 1.5rem (24px)
3xl - 1.875rem (30px)
4xl - 2.25rem (36px)
5xl - 3rem (48px)
Line Heights
| Token | Value | Use Case |
|---|---|---|
--line-height-none | 1 | Single line text |
--line-height-tight | 1.25 | Headings |
--line-height-snug | 1.375 | UI text |
--line-height-normal | 1.5 | Default body |
--line-height-relaxed | 1.625 | Long-form prose |
--line-height-loose | 1.75 | Generous spacing |
Measure (Line Length)
| Token | Value |
|---|---|
--measure-narrow | 45ch |
--measure-normal | 65ch |
--measure-wide | 80ch |
Usage Example
Typography tokens
/* Font families */body { font-family: var(--font-sans);} code { font-family: var(--font-mono);} /* Font sizes */h1 { font-size: var(--font-size-4xl); }h2 { font-size: var(--font-size-3xl); }p { font-size: var(--font-size-md); } /* Line heights */.dense { line-height: var(--line-height-tight); }.prose { line-height: var(--line-height-relaxed); }Borders
Border widths and radius scale for consistent UI shapes.
Border Widths
| Token | Value |
|---|---|
--border-width-thin | 1px |
--border-width-medium | 2px |
--border-width-thick | 4px |
Border Radius
xs
s
m
l
xl
full
| Token | Value | Pixels |
|---|---|---|
--radius-xs | 0.125rem | 2px |
--radius-s | 0.25rem | 4px |
--radius-m | 0.5rem | 8px |
--radius-l | 0.75rem | 12px |
--radius-xl | 1rem | 16px |
--radius-2xl | 1.5rem | 24px |
--radius-full | 9999px | Pill/circle |
Usage Example
Border tokens
/* Border widths */.input { border: var(--border-width-thin) solid var(--color-border);} /* Border radius */.button { border-radius: var(--radius-m); }.avatar { border-radius: var(--radius-full); }.card { border-radius: var(--radius-l); }Shadows
Elevation system with subtle to dramatic shadow depths.
xs
sm
md
lg
xl
| Token | Use Case |
|---|---|
--shadow-xs | Subtle elevation |
--shadow-sm | Cards, buttons |
--shadow-md | Dropdowns |
--shadow-lg | Popovers, tooltips |
--shadow-xl | Modals |
--shadow-2xl | Dramatic elevation |
--shadow-inner | Inset effect |
--shadow-none | Remove shadow |
Usage Example
Shadow tokens
/* Shadow scale */.card { box-shadow: var(--shadow-sm); }.modal { box-shadow: var(--shadow-xl); } /* Numeric aliases */.tooltip { box-shadow: var(--shadow-2); }Motion
Animation timing and easing functions. Automatically respects prefers-reduced-motion.
Durations
| Token | Value | Use Case |
|---|---|---|
--duration-instant | 50ms | Immediate feedback |
--duration-fast | 100ms | Hover states |
--duration-normal | 200ms | Standard transitions |
--duration-slow | 300ms | Complex animations |
--duration-slower | 500ms | Page transitions |
Easing Functions
| Token | Character |
|---|---|
--ease-1 | Subtle |
--ease-2 | Moderate |
--ease-3 | Standard (default) |
--ease-4 | Emphasized |
--ease-5 | Dramatic |
--ease-in | Accelerating |
--ease-out | Decelerating |
--ease-elastic-1 | Slight bounce |
--ease-elastic-2 | More bounce |
Reduced Motion
All duration tokens automatically become 0ms when users have prefers-reduced-motion: reduce enabled.
Usage Example
Motion tokens
/* Duration scale */.transition-fast { transition: all var(--duration-fast) var(--ease-default);} .transition-slow { transition: all var(--duration-slow) var(--ease-out);} /* Respects prefers-reduced-motion automatically */Next Steps
Themes
Apply brand themes to change colors and personality.
Attributes
Data attributes for layout and styling.
Elements
Browse all styled HTML elements.