Design Tokens

Design tokens are the atomic values that define Voidable's visual language. Every color, spacing step, font size, shadow, radius, and motion curve is expressed as a CSS custom property prefixed with --void-. Components consume these tokens rather than hard-coding values, so a single override propagates everywhere.

Tokens ship in the @voidable/theme package. After importing it, all tokens are available as standard CSS custom properties:

@import '@voidable/theme';

The theme is organized into two tiers:

• Primitives (primitives.css) -- Raw scales with no semantic meaning. Color palettes, spacing steps, font stacks.
• Semantic tokens (tokens.css) -- Purpose-driven aliases like --void-color-bg and --void-color-text that reference primitives and adapt based on the active theme.

---

Color primitives

Primitive color palettes are always available on :root regardless of the active theme. They exist so semantic tokens (and your own overrides) can reference them.

Stone

| Token | Value | |---|---| | --void-stone-50 | #fafaf9 | | --void-stone-100 | #f5f5f4 | | --void-stone-200 | #e7e5e4 | | --void-stone-300 | #d6d3d1 | | --void-stone-400 | #a8a29e | | --void-stone-450 | #908a85 | | --void-stone-500 | #78716c | | --void-stone-600 | #57534e | | --void-stone-700 | #44403c | | --void-stone-800 | #292524 | | --void-stone-900 | #1c1917 | | --void-stone-950 | #0c0a09 |

Red (error)

| Token | Value | |---|---| | --void-red-50 | #fef2f2 | | --void-red-100 | #fee2e2 | | --void-red-200 | #fecaca | | --void-red-300 | #fca5a5 | | --void-red-400 | #f87171 | | --void-red-500 | #ef4444 | | --void-red-600 | #dc2626 | | --void-red-700 | #b91c1c | | --void-red-800 | #991b1b | | --void-red-900 | #7f1d1d | | --void-red-950 | #450a0a |

Amber (warning)

| Token | Value | |---|---| | --void-amber-50 | #fefae4 | | --void-amber-100 | #fdf1be | | --void-amber-200 | #f9e182 | | --void-amber-300 | #f1cb48 | | --void-amber-400 | #e5c03c | | --void-amber-500 | #cca93c | | --void-amber-600 | #a88a2a | | --void-amber-700 | #846b20 | | --void-amber-800 | #655118 | | --void-amber-900 | #503f13 | | --void-amber-950 | #30260b |

Green (success)

| Token | Value | |---|---| | --void-green-50 | #f0fdf4 | | --void-green-100 | #dcfce7 | | --void-green-200 | #bbf7d0 | | --void-green-300 | #86efac | | --void-green-400 | #4ade80 | | --void-green-500 | #22c55e | | --void-green-600 | #16a34a | | --void-green-700 | #15803d | | --void-green-800 | #166534 | | --void-green-900 | #14532d | | --void-green-950 | #052e16 |

Blue (info)

| Token | Value | |---|---| | --void-blue-50 | #eff6ff | | --void-blue-100 | #dbeafe | | --void-blue-200 | #bfdbfe | | --void-blue-300 | #93c5fd | | --void-blue-400 | #60a5fa | | --void-blue-500 | #3b82f6 | | --void-blue-600 | #2563eb | | --void-blue-700 | #1d4ed8 | | --void-blue-800 | #1e40af | | --void-blue-900 | #1e3a8a | | --void-blue-950 | #172554 |

Purple (notice)

| Token | Value | |---|---| | --void-purple-50 | #faf5ff | | --void-purple-100 | #f3e8ff | | --void-purple-200 | #e9d5ff | | --void-purple-300 | #d8b4fe | | --void-purple-400 | #c084fc | | --void-purple-500 | #a855f7 | | --void-purple-600 | #9333ea | | --void-purple-700 | #7e22ce | | --void-purple-800 | #6b21a8 | | --void-purple-900 | #581c87 | | --void-purple-950 | #3b0764 |

Pink (highlight)

| Token | Value | |---|---| | --void-pink-50 | #fdf2f8 | | --void-pink-100 | #fce7f3 | | --void-pink-200 | #fbcfe8 | | --void-pink-300 | #f9a8d4 | | --void-pink-400 | #f472b6 | | --void-pink-500 | #ec4899 | | --void-pink-600 | #db2777 | | --void-pink-700 | #be185d | | --void-pink-800 | #9d174d | | --void-pink-900 | #831843 | | --void-pink-950 | #500724 |

Black, white, and dark surfaces

| Token | Value | Purpose | |---|---|---| | --void-black | #000000 | Pure black | | --void-white | #ffffff | Pure white | | --void-dark-1 | #0a0a0a | Dark surface step 1 (near-black elevation) | | --void-dark-2 | #0b0b0b | Dark surface step 2 | | --void-dark-3 | #111111 | Dark surface step 3 | | --void-dark-4 | #141414 | Dark surface step 4 |

---

Semantic color tokens

Semantic tokens carry purpose -- "the background color" rather than "stone-900". They change automatically between dark and light themes via the data-theme attribute on your root element.

Dark mode is the default. Set data-theme="light" on <html> to activate light mode.

Surface colors

| Token | Dark value | Light value | |---|---|---| | --void-color-bg | var(--void-black) | var(--void-white) | | --void-color-bg-secondary | var(--void-dark-1) | var(--void-stone-100) | | --void-color-bg-elevated | var(--void-dark-3) | var(--void-white) | | --void-color-bg-hover | var(--void-dark-4) | var(--void-stone-200) | | --void-color-bg-accent | var(--void-dark-2) | var(--void-stone-100) | | --void-color-bg-overlay | black 70% / transparent | black 30% / transparent |

Text colors

| Token | Dark value | Light value | |---|---|---| | --void-color-text | var(--void-stone-100) | var(--void-stone-900) | | --void-color-text-secondary | var(--void-stone-400) | var(--void-stone-600) | | --void-color-text-muted | var(--void-stone-500) | var(--void-stone-500) | | --void-color-text-tertiary | var(--void-stone-450) | var(--void-stone-400) | | --void-color-text-disabled | var(--void-stone-600) | var(--void-stone-300) | | --void-color-text-on-accent | var(--void-black) | var(--void-white) |

Border colors

| Token | Dark value | Light value | |---|---|---| | --void-color-border | white 14% / transparent | var(--void-stone-300) | | --void-color-border-strong | white 22% / transparent | var(--void-stone-400) | | --void-color-border-focus | white 55% / transparent | var(--void-stone-600) |

Accent colors

| Token | Dark value | Light value | |---|---|---| | --void-color-accent | var(--void-white) | var(--void-stone-900) | | --void-color-accent-hover | var(--void-stone-200) | var(--void-stone-950) |

Status colors

Status tokens map to the primitive palettes. Dark mode uses the -500 stop; light mode uses -600 for better contrast on white backgrounds.

| Token | Dark value | Light value | |---|---|---| | --void-color-error | var(--void-red-500) | var(--void-red-600) | | --void-color-warning | var(--void-amber-500) | var(--void-amber-600) | | --void-color-success | var(--void-green-500) | var(--void-green-600) | | --void-color-info | var(--void-blue-500) | var(--void-blue-600) | | --void-color-notice | var(--void-purple-500) | var(--void-purple-600) | | --void-color-highlight | var(--void-pink-500) | var(--void-pink-600) |

Status subtle colors

Subtle status colors use color-mix() to create low-opacity tinted backgrounds. Dark mode uses 14% opacity; light mode uses 8%.

| Token | Dark value | Light value | |---|---|---| | --void-color-error-subtle | error 14% / transparent | error 8% / transparent | | --void-color-warning-subtle | warning 14% / transparent | warning 8% / transparent | | --void-color-success-subtle | success 14% / transparent | success 8% / transparent | | --void-color-info-subtle | info 14% / transparent | info 8% / transparent | | --void-color-notice-subtle | notice 14% / transparent | notice 8% / transparent | | --void-color-highlight-subtle | highlight 14% / transparent | highlight 8% / transparent |

---

Spacing

Spacing tokens use a numeric scale based on a 0.25rem (4px) grid. Named aliases provide T-shirt sizing for common use.

Numeric scale

| Token | Value | |---|---| | --void-space-1 | 0.25rem (4px) | | --void-space-1h | 0.375rem (6px) | | --void-space-2 | 0.5rem (8px) | | --void-space-2h | 0.625rem (10px) | | --void-space-3 | 0.75rem (12px) | | --void-space-4 | 1rem (16px) | | --void-space-5 | 1.25rem (20px) | | --void-space-6 | 1.5rem (24px) | | --void-space-7 | 1.75rem (28px) | | --void-space-8 | 2rem (32px) | | --void-space-9 | 2.25rem (36px) | | --void-space-10 | 2.5rem (40px) | | --void-space-12 | 3rem (48px) | | --void-space-14 | 3.5rem (56px) | | --void-space-15 | 3.75rem (60px) | | --void-space-16 | 4rem (64px) | | --void-space-20 | 5rem (80px) | | --void-space-24 | 6rem (96px) | | --void-space-28 | 7rem (112px) | | --void-space-30 | 7.5rem (120px) | | --void-space-32 | 8rem (128px) | | --void-space-35 | 8.75rem (140px) | | --void-space-40 | 10rem (160px) |

Named aliases

| Token | Maps to | |---|---| | --void-space-xs | --void-space-1 (0.25rem) | | --void-space-sm | --void-space-2 (0.5rem) | | --void-space-md | --void-space-3 (0.75rem) | | --void-space-lg | --void-space-4 (1rem) | | --void-space-xl | --void-space-6 (1.5rem) |

Semantic spacing aliases

Defined in tokens.css, these mirror the named spacing primitives:

| Token | Maps to | |---|---| | --void-spacing-xs | var(--void-space-xs) | | --void-spacing-sm | var(--void-space-sm) | | --void-spacing-md | var(--void-space-md) | | --void-spacing-lg | var(--void-space-lg) | | --void-spacing-xl | var(--void-space-xl) |

---

Typography

Text sizes

| Token | Value | |---|---| | --void-text-2xs | 0.625rem (10px) | | --void-text-xs | 0.75rem (12px) | | --void-text-sm | 0.8125rem (13px) | | --void-text-base | 0.875rem (14px) | | --void-text-md | 1rem (16px) | | --void-text-lg | 1.125rem (18px) | | --void-text-xl | 1.25rem (20px) | | --void-text-2xl | 1.5rem (24px) | | --void-text-3xl | 1.875rem (30px) | | --void-text-4xl | 2.25rem (36px) | | --void-text-5xl | 3rem (48px) |

Font weights

| Token | Value | |---|---| | --void-weight-normal | 400 | | --void-weight-medium | 500 | | --void-weight-semibold | 600 | | --void-weight-bold | 700 |

Line heights

| Token | Value | Notes | |---|---|---| | --void-leading-display | 0.92 | Large display headings | | --void-leading-none | 1 | No extra leading | | --void-leading-snug | 1.05 | Slightly more than none | | --void-leading-tight | 1.2 | | | --void-leading-normal | 1.5 | | | --void-leading-relaxed | 1.7 | | | --void-leading-loose | 1.75 | Extra loose for code blocks |

Letter spacing (tracking)

| Token | Value | Use case | |---|---|---| | --void-tracking-tightest | -0.05em | Display text, wordmarks | | --void-tracking-tighter | -0.04em | Large headings | | --void-tracking-tight | -0.025em | Headings | | --void-tracking-snug | -0.01em | Subheadings, card titles | | --void-tracking-normal | 0em | Body text (default) | | --void-tracking-wide | 0.04em | Tags, badges | | --void-tracking-wider | 0.06em | Labels | | --void-tracking-widest | 0.1em | Uppercase labels, section headers |

Font families

| Token | Value | |---|---| | --void-font-sans | 'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif | | --void-font-mono | 'JetBrains Mono', ui-monospace, 'SF Mono', 'Fira Code', monospace |

---

Border radius

| Token | Value | |---|---| | --void-radius-none | 0 | | --void-radius-xs | 4px | | --void-radius-sm | 6px | | --void-radius-md | 8px | | --void-radius-lg | 12px | | --void-radius-xl | 16px | | --void-radius-full | 9999px |

The data-shape="sharp" attribute on a parent element resets all radius tokens to 0, giving every component a sharp-cornered appearance:

<html data-shape="sharp">

---

Shadows

Shadows use white-based rgba values for glow-style elevation on dark surfaces.

| Token | Value | |---|---| | --void-shadow-sm | 0 1px 3px rgba(255,255,255,.14) | | --void-shadow-md | 0 2px 6px rgba(255,255,255,.12), 0 10px 24px rgba(255,255,255,.20) | | --void-shadow-lg | 0 4px 10px rgba(255,255,255,.16), 0 22px 50px rgba(255,255,255,.28) | | --void-shadow-xl | 0 6px 14px rgba(255,255,255,.20), 0 40px 88px rgba(255,255,255,.38) |

Ring hairlines

Subtle 1px ring effects for card edges and elevated surfaces:

| Token | Value | |---|---| | --void-ring-hair | 0 0 0 1px rgba(255,255,255,.06) | | --void-ring-hair-strong | 0 0 0 1px rgba(255,255,255,.12) |

---

Motion

Durations

| Token | Value | |---|---| | --void-duration-fast | 100ms | | --void-duration-normal | 200ms | | --void-duration-slow | 300ms |

Easings

| Token | Value | |---|---| | --void-ease-in | cubic-bezier(0.4, 0, 1, 0.2) | | --void-ease-out | cubic-bezier(0, 0, 0.2, 1) | | --void-ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) |

---

Z-index layers

A fixed stacking order so overlapping elements layer predictably:

| Token | Value | |---|---| | --void-z-dropdown | 100 | | --void-z-sticky | 200 | | --void-z-modal | 300 | | --void-z-toast | 400 | | --void-z-tooltip | 500 |

---

Icon

| Token | Value | |---|---| | --void-icon-stroke-width | 1.5 |

---

Layout

| Token | Value | |---|---| | --void-sidebar-width | 15rem | | --void-sidebar-collapsed-width | 3.75rem |

---

The tone system

Many Voidable components use an internal --tone custom property pattern for color theming. Instead of writing separate rulesets for every color variant, each component defines:

void-badge {
  --tone: var(--void-color-accent);
  background: var(--tone);
}

void-badge[color="error"]   { --tone: var(--void-color-error); }
void-badge[color="warning"] { --tone: var(--void-color-warning); }
void-badge[color="success"] { --tone: var(--void-color-success); }

Some components derive additional tones for subtle backgrounds and borders:

void-stat {
  --tone: var(--void-color-accent);
  --tone-subtle: color-mix(in srgb, var(--tone) 14%, transparent);
  --tone-border: color-mix(in srgb, var(--tone) 36%, transparent);

  background: var(--tone-subtle);
  border: 1px solid var(--tone-border);
}

You set the tone from HTML using the color attribute:

<void-badge color="error">3</void-badge>
<void-stat color="success">+12%</void-stat>

The available color values are: error, warning, success, info, notice, and highlight. The default (no attribute) uses --void-color-accent.

---

Using tokens in custom CSS

Reference any token as a standard CSS custom property:

.my-card {
  background: var(--void-color-bg-elevated);
  border: 1px solid var(--void-color-border);
  border-radius: var(--void-radius-md);
  padding: var(--void-space-4);
  font-family: var(--void-font-sans);
  font-size: var(--void-text-sm);
  color: var(--void-color-text);
  box-shadow: var(--void-shadow-md);
  transition: background var(--void-duration-normal) var(--void-ease-out);
}

.my-card:hover {
  background: var(--void-color-bg-hover);
}

Tokens compose naturally. Build a status banner using semantic colors:

.status-banner {
  padding: var(--void-space-3) var(--void-space-4);
  border-radius: var(--void-radius-sm);
  font-size: var(--void-text-sm);
  font-weight: var(--void-weight-medium);
  line-height: var(--void-leading-normal);
}

.status-banner.error {
  background: var(--void-color-error-subtle);
  color: var(--void-color-error);
}

.status-banner.success {
  background: var(--void-color-success-subtle);
  color: var(--void-color-success);
}

Override tokens at any scope to customize a subtree:

.branded-section {
  --void-color-accent: #3b82f6;
  --void-color-accent-hover: #2563eb;
  --void-color-text-on-accent: #ffffff;
}

Every Voidable component inside .branded-section will pick up the new accent color automatically.