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 Ratio Name Value Best for Minor Second 1.067 Tight, minimal difference Dense UI, dashboards Major Second 1.125 Subtle progression Apps, data-heavy interfaces Minor Third 1.200 Balanced, versatile Most websites, SaaS Major Third 1.250 Clear hierarchy Marketing sites, blogs Perfect Fourth 1.333 Strong contrast Editorial, landing pages Augmented Fourth 1.414 Dramatic Bold designs, portfolios Perfect Fifth 1.500 Very dramatic Hero-heavy designs 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 Font Size Line Height Use ≤ 14px 1.6–1.7 Small text, captions 16–20px 1.5–1.6 Body text 20–32px 1.3–1.4 Subheadings 32–48px 1.1–1.2 Headings 48px+ 1.0–1.1 Display/hero text Rule of thumb: As font size increases, line height decreases. Letter Spacing Rules Size Letter Spacing Why Small text (≤14px) 0.01–0.02em Slightly open for readability Body text 0em (normal) Don't touch it Subheadings -0.01em Slightly tighten Headings -0.02em to -0.03em Tighten as size grows Display text -0.03em to -0.05em Tight tracking at large sizes Font Weight Pairing Role Weight Tailwind Body 400 (Regular) font-normal Body emphasis 500 (Medium) font-medium Subheading 600 (Semibold) font-semibold Heading 700 (Bold) font-bold Display 800 (Extrabold) font-extrabold Output Example (CSS Custom Properties) :root { --font-size-xs : 0.694 rem ; / 11.1px / --font-size-sm : 0.833 rem ; / 13.3px / --font-size-base : 1 rem ; / 16px / --font-size-lg : 1.2 rem ; / 19.2px / --font-size-xl : 1.44 rem ; / 23px / --font-size-2xl : 1.728 rem ; / 27.6px / --font-size-3xl : 2.074 rem ; / 33.2px / --font-size-4xl : 2.488 rem ; / 39.8px / --font-size-5xl : 2.986 rem ; / 47.8px / } Color Palette Generation Step 1: Choose Base Colors Every palette needs: Token Purpose Example primary Main brand color, CTAs Your brand color neutral Text, borders, backgrounds Gray (warm/cool/pure) success Positive states Green warning Caution states Amber/yellow error Destructive states Red info Informational Blue (can overlap primary) 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: Step Lightness Adjustment Saturation Adjustment 50 +45% -30% 100 +38% -25% 200 +28% -15% 300 +18% -5% 400 +8% 0% 500 0% (base) 0% (base) 600 -8% +5% 700 -18% +5% 800 -28% 0% 900 -38% -10% 950 -45% -20% 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 Level Ratio Applies to AA Normal Text ≥ 4.5:1 Body text (< 18px or < 14px bold) AA Large Text ≥ 3:1 ≥ 18px regular or ≥ 14px bold AAA Normal Text ≥ 7:1 Enhanced accessibility AA UI Components ≥ 3:1 Borders, icons, focus rings Quick Reference (Neutral on White #FFFFFF) Shade Approx Contrast Passes 300 ~2.5:1 ❌ Decorative only 400 ~3.5:1 ✅ Large text, UI 500 ~4.5:1 ✅ AA body text 600 ~6:1 ✅ AA comfortable 700 ~8:1 ✅ AAA body text Checking Contrast Programmatically When generating palettes, always verify: text (900) on bg (50) → must be ≥ 4.5:1 text-muted (500) on bg (50) → must be ≥ 4.5:1 primary (600) on white → must be ≥ 4.5:1 primary-text on primary (600) → must be ≥ 4.5:1 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 : 0 px ; --space-0 .5 : 2 px ; --space-1 : 4 px ; --space-1 .5 : 6 px ; --space-2 : 8 px ; --space-3 : 12 px ; --space-4 : 16 px ; --space-5 : 20 px ; --space-6 : 24 px ; --space-8 : 32 px ; --space-10 : 40 px ; --space-12 : 48 px ; --space-16 : 64 px ; --space-20 : 80 px ; --space-24 : 96 px ; --space-32 : 128 px ; } This matches Tailwind's default scale exactly. Spacing Usage Guide Context Spacing Values Inline icon gap space-1 to space-2 4–8px Button padding space-2 × space-4 8px 16px Card padding space-4 to space-6 16–24px Section gap (between elements) space-6 to space-8 24–32px Section padding (container) space-12 to space-16 48–64px Page section vertical rhythm space-16 to space-24 64–96px The Container Width Scale Token Width Use sm 640px Narrow content (auth forms) md 768px Blog posts, documentation lg 1024px App layouts xl 1280px Wide layouts 2xl 1536px Full-width dashboards 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 : 1 rem ; --font-size-lg : 1.2 rem ; / Colors / --color-primary-500 : hsl ( 220 , 80 % , 50 % ) ; / Spacing / --space-4 : 1 rem ; } 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 Ask: What's the project? (marketing site, SaaS app, dashboard?) Type scale: Pick ratio based on project type → generate scale Colors: Get brand color → generate shade scales for primary + neutral + semantic Verify contrast: Check all text/bg combos against WCAG AA Spacing: Use base-4 scale (match Tailwind) Dark mode: Derive from light palette using inversion pattern 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