palette-generation.md

GitHub

Palette Generation

The scale convention

Design system palettes use a numeric scale from 50 (lightest) to 950 (darkest). The standard labels by palette size:

Size Labels
5 100, 300, 500, 700, 900
9 50, 100, 200, 300, 500, 700, 800, 900, 950
11 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

9 steps is the standard default (matches Tailwind).

Algorithm

Given a base color with lightness (L), chroma percentage, and hue (H):

Step 1 — Lightness bounds:

delta = 0.4
minL = max(0.05, baseL - delta)
maxL = min(0.95, baseL + delta)

Lightness is clamped to [0.05, 0.95] to avoid pure black/white which have zero chroma.

Step 2 — Distribute lightness evenly from maxL (lightest, label 50) to minL (darkest, label 950).

Step 3 — Clamp chroma per step. Each lightness level has a different maximum chroma for a given hue and color space:

maxChroma = findMaxChroma(step[i].L, hue, colorSpace)
step[i].C = (chromaPercentage / 100) * maxChroma

This ensures every step is within gamut. High-chroma base colors will have lower chroma at the lightest and darkest ends — this is correct and expected.

CSS variable output

:root {
  --color-50: oklch(0.971 0.012 250);
  --color-100: oklch(0.932 0.028 250);
  --color-200: oklch(0.882 0.048 250);
  --color-300: oklch(0.812 0.078 250);
  --color-500: oklch(0.623 0.188 250);
  --color-700: oklch(0.445 0.138 250);
  --color-800: oklch(0.362 0.108 250);
  --color-900: oklch(0.289 0.078 250);
  --color-950: oklch(0.215 0.048 250);
}

Multi-hue palettes

When generating palettes for multiple hues, use the same lightness and chroma percentage for all. Same L guarantees equal perceived brightness. Same chroma percentage (not absolute chroma) guarantees equal vividness relative to each hue's maximum.

:root {
  /* Same L, same C% (80% of max) — different absolute C per hue */
  --blue-500: oklch(0.623 0.141 250);   /* 80% of max 0.176 */
  --green-500: oklch(0.623 0.157 145);  /* 80% of max 0.196 */
  --red-500: oklch(0.623 0.202 25);     /* 80% of max 0.253 */
}

Different hues have different max chroma at the same lightness. Using the same absolute C value across hues would make some appear more vivid than others.

Dark mode

Reverse the palette mapping so that the lightest step becomes the darkest and vice versa:

:root {
  --color-bg: var(--color-50);
  --color-text: var(--color-950);
}

.dark {
  --color-bg: var(--color-950);
  --color-text: var(--color-50);
}

This works because oklch's perceptual uniformity means equal L steps in both directions produce equally readable results.

Why not HSL palettes?

Hue drift: hsl(240, 80%, 20%) and hsl(240, 80%, 90%) are not the same perceptual hue. The light variant shifts ~18° toward purple. OKLCH hue is stable.

Brightness inconsistency: hsl(60, 100%, 50%) (yellow) and hsl(240, 100%, 50%) (blue) have the same HSL lightness but wildly different perceived brightness.