utilities

CSS Design Tokens with Custom Properties

A complete design token system using CSS custom properties for color, spacing, typography, and motion.

Design tokens are the foundation of any scalable design system. Implemented as CSS custom properties on :root, they create a single source of truth for every visual value in your project. Tokens that reference other tokens (aliases) let you build semantic layers — a brand colour referenced by a component colour token, which is then used in component CSS.

Live CSS Editor

CSS

Preview

/* ── Design Token System ──────────────────────────────── */

:root {
  /* Primitive color tokens */
  --green-50:  #f0fdf4;
  --green-500: #1d9e75;
  --green-600: #178a63;
  --blue-500:  #0ea5e9;
  --gray-50:   #f9fafb;
  --gray-100:  #f3f4f6;
  --gray-200:  #e5e7eb;
  --gray-500:  #6b7280;
  --gray-900:  #111827;

/* Semantic color tokens (reference primitives) */
  --color-primary:   var(--green-500);
  --color-primary-hover: var(--green-600);
  --color-bg:        #ffffff;
  --color-surface:   var(--gray-50);
  --color-border:    var(--gray-200);
  --color-text:      var(--gray-900);
  --color-muted:     var(--gray-500);
  --color-accent:    var(--green-500);

/* Spacing (4px grid) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;

/* Typography */
  --font-sans: system-ui, -apple-system, sans-serif;
  --font-mono: ui-monospace, 'Cascadia Code', monospace;
  --text-xs:   11px;
  --text-sm:   13px;
  --text-base: 15px;
  --text-lg:   18px;
  --text-xl:   22px;
  --text-2xl:  28px;
  --text-4xl:  clamp(28px, 5vw, 44px);

/* Shape */
  --radius-sm:   4px;
  --radius-md:   8px;
  --radius-lg:   12px;
  --radius-xl:   16px;
  --radius-full: 100px;

/* Shadow */
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.08);
  --shadow-md: 0 4px 12px rgba(0,0,0,0.10);
  --shadow-lg: 0 8px 32px rgba(0,0,0,0.12);

/* Motion */
  --ease-out:    cubic-bezier(0.16, 1, 0.3, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --duration-fast:   150ms;
  --duration-normal: 250ms;
  --duration-slow:   400ms;
  --transition-fast: var(--duration-fast) var(--ease-in-out);
  --transition-normal: var(--duration-normal) var(--ease-out);
}

/* Dark mode token overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg:      #0f0f0f;
    --color-surface: #1a1a1a;
    --color-border:  #2a2a2a;
    --color-text:    #f0f0f0;
    --color-muted:   #9ca3af;
    --color-accent:  #34d399;
  }
}

Edit CSS → see live previewTab = 2 spaces

Usage Note

Use semantic tokens (--color-primary, --color-text) in component CSS, not primitive tokens (--green-500). This way, swapping a brand colour only requires changing one primitive token. Components automatically inherit the change through the semantic token chain.