references/token-generation.md

Design Token Generation Guide

Reference for color palette algorithms, typography scales, and WCAG accessibility checking.

Color Palette Generation
Typography Scale System
Spacing Grid System
Accessibility Contrast
Export Formats

Color Palette Generation

HSV Color Space Algorithm

The token generator uses HSV (Hue, Saturation, Value) color space for precise control.

┌─────────────────────────────────────────────────────────────┐
│                    COLOR SCALE GENERATION                   │
├─────────────────────────────────────────────────────────────┤
│  Input: Brand Color (#0066CC)                               │
│  ↓                                                          │
│  Convert: Hex → RGB → HSV                                   │
│  ↓                                                          │
│  For each step (50, 100, 200... 900):                      │
│    • Adjust Value (brightness)                              │
│    • Adjust Saturation                                      │
│    • Keep Hue constant                                      │
│  ↓                                                          │
│  Output: 10-step color scale                                │
└─────────────────────────────────────────────────────────────┘

Brightness Algorithm

# For light shades (50-400): High fixed brightness
if step < 500:
    new_value = 0.95  # 95% brightness

# For dark shades (500-900): Exponential decrease
else:
    new_value = base_value * (1 - (step - 500) / 500)
    # At step 900: brightness ≈ base_value * 0.2

Saturation Scaling

# Saturation increases with step number
# 50 = 30% of base saturation
# 900 = 100% of base saturation
new_saturation = base_saturation * (0.3 + 0.7 * (step / 900))

Complementary Color Generation

Brand Color: #0066CC (H=210°, S=100%, V=80%)
                    ↓
           Add 180° to Hue
                    ↓
Secondary: #CC6600 (H=30°, S=100%, V=80%)

Color Scale Output

Step	Use Case	Brightness	Saturation
50	Subtle backgrounds	95% (fixed)	30%
100	Light backgrounds	95% (fixed)	38%
200	Hover states	95% (fixed)	46%
300	Borders	95% (fixed)	54%
400	Disabled states	95% (fixed)	62%
500	Base color	Original	70%
600	Hover (dark)	Original × 0.8	78%
700	Active states	Original × 0.6	86%
800	Text	Original × 0.4	94%
900	Headings	Original × 0.2	100%

Typography Scale System

Modular Scale (Major Third)

The generator uses a 1.25x ratio (major third) to create harmonious font sizes.

Base: 16px

Scale calculation:
  Smaller sizes: 16px ÷ 1.25^n
  Larger sizes: 16px × 1.25^n

Result:
  xs:   10px (16 ÷ 1.25²)
  sm:   13px (16 ÷ 1.25¹)
  base: 16px
  lg:   20px (16 × 1.25¹)
  xl:   25px (16 × 1.25²)
  2xl:  31px (16 × 1.25³)
  3xl:  39px (16 × 1.25⁴)
  4xl:  49px (16 × 1.25⁵)
  5xl:  61px (16 × 1.25⁶)

Type Scale Ratios

Ratio	Name	Multiplier	Character
1.067	Minor Second	Tight	Compact UIs
1.125	Major Second	Subtle	App interfaces
1.200	Minor Third	Moderate	General use
1.250	Major Third	Balanced	Default
1.333	Perfect Fourth	Pronounced	Marketing
1.414	Augmented Fourth	Bold	Editorial
1.618	Golden Ratio	Dramatic	Headlines

Pre-composed Text Styles

Style	Size	Weight	Line Height	Letter Spacing
h1	48px	700	1.2	-0.02em
h2	36px	700	1.3	-0.01em
h3	28px	600	1.4	0
h4	24px	600	1.4	0
h5	20px	600	1.5	0
h6	16px	600	1.5	0.01em
body	16px	400	1.5	0
small	14px	400	1.5	0
caption	12px	400	1.5	0.01em

Spacing Grid System

8pt Grid Foundation

All spacing values are multiples of 8px for visual consistency.

Base Unit: 8px

Multipliers: 0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8...

Results:
  0:  0px
  1:  4px  (0.5 × 8)
  2:  8px  (1 × 8)
  3:  12px (1.5 × 8)
  4:  16px (2 × 8)
  5:  20px (2.5 × 8)
  6:  24px (3 × 8)
  ...

Semantic Spacing Mapping

Token	Numeric	Value	Use Case
xs	1	4px	Inline icon margins
sm	2	8px	Button padding
md	4	16px	Card padding
lg	6	24px	Section spacing
xl	8	32px	Component gaps
2xl	12	48px	Section margins
3xl	16	64px	Page sections

Why 8pt Grid?

Divisibility: 8 divides evenly into common screen widths
Consistency: Creates predictable vertical rhythm
Accessibility: Touch targets naturally align to 48px (8 × 6)
Integration: Most design tools default to 8px grids

Accessibility Contrast

WCAG Contrast Requirements

Level	Normal Text	Large Text	Definition
AA	4.5:1	3:1	Minimum requirement
AAA	7:1	4.5:1	Enhanced accessibility

Large text: ≥18pt regular or ≥14pt bold

Contrast Ratio Formula

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

Where:
  L1 = Relative luminance of lighter color
  L2 = Relative luminance of darker color

Relative Luminance:
  L = 0.2126 × R + 0.7152 × G + 0.0722 × B
  (Values linearized from sRGB)

Color Step Contrast Guide

Background	Minimum Text Step	For AA
50	700+	Large text at 600
100	700+	Large text at 600
200	800+	Large text at 700
300	900	-
500 (base)	White or 50	-
700+	White or 50-100	-

Semantic Colors Accessibility

Generated semantic colors include contrast colors:

{
  "success": {
    "base": "#10B981",
    "light": "#34D399",
    "dark": "#059669",
    "contrast": "#FFFFFF"  // For text on base
  }
}

Export Formats

JSON Format

Best for: Design tool plugins, JavaScript/TypeScript projects, APIs

{
  "colors": {
    "primary": {
      "50": "#E6F2FF",
      "500": "#0066CC",
      "900": "#002855"
    }
  },
  "typography": {
    "fontSize": {
      "base": "16px",
      "lg": "20px"
    }
  }
}

CSS Custom Properties

Best for: Web applications, CSS frameworks

:root {
  --colors-primary-50: #E6F2FF;
  --colors-primary-500: #0066CC;
  --colors-primary-900: #002855;
  --typography-fontSize-base: 16px;
  --typography-fontSize-lg: 20px;
}

SCSS Variables

Best for: SCSS/SASS projects, component libraries

$colors-primary-50: #E6F2FF;
$colors-primary-500: #0066CC;
$colors-primary-900: #002855;
$typography-fontSize-base: 16px;
$typography-fontSize-lg: 20px;

Format Selection Guide

Format	When to Use
JSON	Figma plugins, Storybook, JS/TS, design tool APIs
CSS	Plain CSS projects, CSS-in-JS (some), web apps
SCSS	SASS pipelines, component libraries, theming
Summary	Quick verification, debugging

Quick Reference

Generation Command

# Default (modern style, JSON output)
python scripts/design_token_generator.py "#0066CC"

# Classic style, CSS output
python scripts/design_token_generator.py "#8B4513" classic css

# Playful style, summary view
python scripts/design_token_generator.py "#FF6B6B" playful summary

Style Differences

Aspect	Modern	Classic	Playful
Fonts	Inter, Fira Code	Helvetica, Courier	Poppins, Source Code Pro
Border Radius	8px default	4px default	16px default
Shadows	Layered, subtle	Single layer	Soft, pronounced

See also: component-architecture.md for component design patterns