Design Tokens

Design Tokens

Token Taxonomy

Primitive → Semantic → Component

/* 1. Primitive tokens — raw values, no semantics */
:root {
  --blue-100: oklch(94% 0.04 260);
  --blue-500: oklch(55% 0.22 260);
  --blue-900: oklch(25% 0.14 260);
  --gray-50:  oklch(98% 0 0);
  --gray-900: oklch(12% 0 0);
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-8: 2rem;
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
}

/* 2. Semantic tokens — intent, not value */
:root {
  --color-bg:       var(--gray-50);
  --color-surface:  #fff;
  --color-text:     var(--gray-900);
  --color-text-muted: oklch(50% 0 0);
  --color-primary:  var(--blue-500);
  --color-primary-hover: var(--blue-900);
  --color-border:   oklch(88% 0 0);
  --color-focus:    var(--blue-500);
  --space-section:  clamp(4rem, 3rem + 5vw, 10rem);
}

/* 3. Component tokens — scoped */
.button {
  --btn-bg: var(--color-primary);
  --btn-fg: #fff;
  --btn-radius: var(--radius-md);
  background: var(--btn-bg);
  color: var(--btn-fg);
  border-radius: var(--btn-radius);
}
.button--danger  { --btn-bg: oklch(55% 0.22 25); }
.button--success { --btn-bg: oklch(55% 0.22 145); }

Dark Mode

/* System preference */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg:      var(--gray-900);
    --color-surface: oklch(18% 0 0);
    --color-text:    oklch(95% 0 0);
    --color-text-muted: oklch(65% 0 0);
    --color-border:  oklch(28% 0 0);
  }
}

/* Manual toggle via data attribute */
[data-theme="dark"] {
  --color-bg:      var(--gray-900);
  --color-surface: oklch(18% 0 0);
  --color-text:    oklch(95% 0 0);
}

// Toggle and persist
const root = document.documentElement;
function setTheme(theme) {
  root.dataset.theme = theme;
  localStorage.setItem('theme', theme);
}
// Init from saved or system pref
const saved = localStorage.getItem('theme');
const system = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
setTheme(saved ?? system);

Style Dictionary (Token Pipeline)

// tokens/color.json
{
  "color": {
    "blue": {
      "500": { "value": "oklch(55% 0.22 260)", "type": "color" }
    },
    "primary": { "value": "{color.blue.500}", "type": "color" }
  }
}

// style-dictionary.config.js
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'dt',
      files: [{ destination: 'src/tokens.css', format: 'css/variables' }]
    },
    js: {
      transformGroup: 'js',
      files: [{ destination: 'src/tokens.js', format: 'javascript/es6' }]
    }
  }
};

Typography Scale

:root {
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  --text-xs:   clamp(0.75rem,  0.7rem  + 0.2vw, 0.875rem);
  --text-sm:   clamp(0.875rem, 0.82rem + 0.3vw, 1rem);
  --text-base: clamp(1rem,     0.94rem + 0.4vw, 1.125rem);
  --text-lg:   clamp(1.125rem, 1rem    + 0.7vw, 1.5rem);
  --text-xl:   clamp(1.25rem,  1rem    + 1vw,   2rem);
  --text-2xl:  clamp(1.5rem,   1rem    + 2vw,   3rem);
  --text-hero: clamp(2.5rem,   1rem    + 6vw,   6rem);

  --leading-tight:  1.2;
  --leading-normal: 1.5;
  --leading-loose:  1.8;
}