design-tokens

Design Tokens

Generate type scales, color palettes, spacing systems, and dark mode derivations with math — not guessing. Includes WCAG contrast checking, systematic spacing grids, and production-ready CSS/Tailwind output.

When to Use

• User is setting up a new project's design system
• User asks for a type scale, color palette, or spacing system
• User needs WCAG-compliant color combinations
• User wants dark mode colors derived from a light palette
• User asks for "design tokens" or "theme setup"
• Building a Tailwind config or CSS custom properties

Core Philosophy

• Math over taste. Scales should follow ratios, not arbitrary values.
• Accessibility by default. Every text/background combo must pass WCAG AA.
• Systematic. Every value should be derivable from a base + ratio.
• Portable. Output as CSS custom properties, Tailwind config, or JSON tokens.

---

Type Scale Generation

The Formula

fontSize = baseFontSize × ratio^step

Recommended Ratios

Generating the Scale

Given a base size (typically 16px) and a ratio:

Step -2: 16 / ratio² = xs
Step -1: 16 / ratio  = sm
Step  0: 16          = base
Step  1: 16 × ratio  = lg
Step  2: 16 × ratio² = xl
Step  3: 16 × ratio³ = 2xl
Step  4: 16 × ratio⁴ = 3xl
Step  5: 16 × ratio⁵ = 4xl
Step  6: 16 × ratio⁶ = 5xl

Round to nearest 0.5px or convert to rem (÷ 16).

Line Height Rules

Rule of thumb: As font size increases, line height decreases.

Letter Spacing Rules

Font Weight Pairing

Output Example (CSS Custom Properties)

:root {
  --font-size-xs: 0.694rem;    /* 11.1px */
  --font-size-sm: 0.833rem;    /* 13.3px */
  --font-size-base: 1rem;      /* 16px */
  --font-size-lg: 1.2rem;      /* 19.2px */
  --font-size-xl: 1.44rem;     /* 23px */
  --font-size-2xl: 1.728rem;   /* 27.6px */
  --font-size-3xl: 2.074rem;   /* 33.2px */
  --font-size-4xl: 2.488rem;   /* 39.8px */
  --font-size-5xl: 2.986rem;   /* 47.8px */
}

---

Color Palette Generation

Step 1: Choose Base Colors

Every palette needs:

Step 2: Generate Shade Scale (50–950)

For each base color, generate a 10-step shade scale. The base color is typically the 500 step.

Method: HSL manipulation

Starting from the base HSL:

Clamp all values: lightness 0–100%, saturation 0–100%.

Step 3: Semantic Token Mapping

Map shade steps to semantic roles:

/* Light mode */
--color-bg: var(--neutral-50);
--color-bg-subtle: var(--neutral-100);
--color-bg-muted: var(--neutral-200);
--color-border: var(--neutral-200);
--color-border-strong: var(--neutral-300);
--color-text-muted: var(--neutral-500);
--color-text-subtle: var(--neutral-600);
--color-text: var(--neutral-900);
--color-text-heading: var(--neutral-950);

--color-primary: var(--primary-600);
--color-primary-hover: var(--primary-700);
--color-primary-bg: var(--primary-50);
--color-primary-text: white;

---

WCAG Contrast Checking

The Formula

Contrast ratio = (L1 + 0.05) / (L2 + 0.05)

Where L1 = lighter relative luminance, L2 = darker.

Relative Luminance

For each channel (R, G, B):
  sRGB = channel / 255
  linear = sRGB <= 0.04045 ? sRGB / 12.92 : ((sRGB + 0.055) / 1.055) ^ 2.4

L = 0.2126 × R_linear + 0.7152 × G_linear + 0.0722 × B_linear

WCAG Requirements

Quick Reference (Neutral on White #FFFFFF)

Checking Contrast Programmatically

When generating palettes, always verify:

1. text (900) on bg (50) → must be ≥ 4.5:1
2. text-muted (500) on bg (50) → must be ≥ 4.5:1
3. primary (600) on white → must be ≥ 4.5:1
4. primary-text on primary (600) → must be ≥ 4.5:1
5. border (200) on bg (50) → must be ≥ 3:1

If a combo fails, adjust the darker color one step darker until it passes.

---

Spacing System

Base-4 Scale (Recommended)

Everything is a multiple of 4px. Predictable, consistent, works with most font sizes.

:root {
  --space-0: 0px;
  --space-0.5: 2px;
  --space-1: 4px;
  --space-1.5: 6px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;
  --space-16: 64px;
  --space-20: 80px;
  --space-24: 96px;
  --space-32: 128px;
}

This matches Tailwind's default scale exactly.

Spacing Usage Guide

The Container Width Scale

---

Dark Mode Derivation

The Inversion Pattern

Don't manually pick dark mode colors. Derive them systematically:

Light mode          →  Dark mode
neutral-50  (bg)    →  neutral-950 (bg)
neutral-100 (bg-subtle) → neutral-900 (bg-subtle)
neutral-200 (border) → neutral-800 (border)
neutral-300 (border-strong) → neutral-700 (border-strong)
neutral-500 (text-muted) → neutral-400 (text-muted)
neutral-600 (text-subtle) → neutral-300 (text-subtle)
neutral-900 (text)  →  neutral-50  (text)
neutral-950 (heading) → neutral-50 (heading)

The rule: Background shades flip (50↔950, 100↔900, 200↔800). Text shades flip similarly. Middle shades (400–600) shift by ~1–2 steps.

Primary Color in Dark Mode

• Use a lighter step: primary-400 or primary-500 instead of primary-600
• Reduce saturation slightly for dark backgrounds (avoids eye strain)
• Verify contrast against neutral-900 or neutral-950 background

Semantic Tokens for Dark Mode

/* Light */
:root {
  --color-bg: var(--neutral-50);
  --color-text: var(--neutral-900);
  --color-primary: var(--primary-600);
}

/* Dark */
.dark {
  --color-bg: var(--neutral-950);
  --color-text: var(--neutral-50);
  --color-primary: var(--primary-400);
}

The beauty: components reference semantic tokens, never raw shades. Switching themes is just swapping the token mapping.

---

Output Formats

CSS Custom Properties

:root {
  /* Type */
  --font-size-base: 1rem;
  --font-size-lg: 1.2rem;
  /* Colors */
  --color-primary-500: hsl(220, 80%, 50%);
  /* Spacing */
  --space-4: 1rem;
}

Tailwind Config

module.exports = {
  theme: {
    extend: {
      fontSize: {
        'xs': '0.694rem',
        'sm': '0.833rem',
        'base': '1rem',
        'lg': '1.2rem',
        'xl': '1.44rem',
      },
      colors: {
        primary: {
          50: 'hsl(220, 50%, 95%)',
          500: 'hsl(220, 80%, 50%)',
          900: 'hsl(220, 60%, 15%)',
        },
      },
    },
  },
}

JSON Design Tokens (W3C Format)

{
  "color": {
    "primary": {
      "500": { "$value": "hsl(220, 80%, 50%)", "$type": "color" }
    }
  },
  "fontSize": {
    "base": { "$value": "1rem", "$type": "dimension" }
  }
}

---

Step-by-Step: Full Design Token Setup

1. Ask: What's the project? (marketing site, SaaS app, dashboard?)
2. Type scale: Pick ratio based on project type → generate scale
3. Colors: Get brand color → generate shade scales for primary + neutral + semantic
4. Verify contrast: Check all text/bg combos against WCAG AA
5. Spacing: Use base-4 scale (match Tailwind)
6. Dark mode: Derive from light palette using inversion pattern
7. Output: Generate CSS custom properties and/or Tailwind config

Examples

Example 1: "Set up design tokens for a SaaS dashboard"

• Type: Minor Third (1.2) ratio, 16px base — clear hierarchy without being dramatic
• Colors: Generate from brand blue, warm gray neutral
• Spacing: Base-4 (Tailwind default)
• Dark mode: Full derivation

Example 2: "I need a color palette from this brand color: #6366F1"

• Parse HSL: ~239°, 84%, 67%
• Generate 50–950 scale using the shade generation method
• Map semantic tokens
• Verify WCAG contrast for all text/bg combos
• Output as CSS + Tailwind config

Example 3: "Create a type scale for a blog"

• Ratio: Major Third (1.25) — strong hierarchy for editorial content
• Base: 18px (slightly larger for long-form reading)
• Generate scale with line-height and letter-spacing for each step