palette-generation.md
GitHubPalette 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.