Advanced Color: Comfortable Codex Theme Palettes with HSL and OKLCH

A codex theme hsl color palette reads differently from a list of hex codes, and that difference decides whether a theme stays calm through a long session or starts grating after an hour. hsl() splits a color into hue, saturation and lightness, three numbers you can reason about one at a time. Most theme authors never leave hex, so most palettes get built by guessing in a color picker.

Why hex is a poor format for editing colors

A hex code packs three channels into six characters. Change one character and red, green and blue all move together in a direction you cannot predict from looking at the string. Asking for a slightly darker version means opening a picker and hoping.

• #3fb950 tells you where that green sits in sRGB and nothing about how bright it reads
• Two colors you think share brightness can differ by fifteen points on screen
• Every small adjustment becomes a round trip to a picker
• Nothing in the string hints at which value to move to darken it

What each HSL number controls

hsl(210 60% 45%) reads as a blue leaning hue, moderate saturation, lightness sitting below the middle. Darkening means pulling the third number down. Desaturating means pulling the second down. Once you trust that mapping you can write the whole palette by hand instead of clicking around a picker.

• Hue: the angle on the wheel, 0 to 360. Move it and you change which color family you are in
• Saturation: distance from grey. 0% is grey, 100% is as loud as the gamut allows
• Lightness: position between black and white, and the value you edit most
• Body text on a dark background usually lands between 70% and 85% lightness

Where OKLCH differs, and whether it is worth it

OKLCH is perceptually uniform, which means a given lightness value looks equally bright whatever the hue. HSL does not manage that. Two colors both set to 60% lightness in HSL can look wildly different, with yellow reading much brighter than blue. In OKLCH they line up, so the lightness ladder you lay out is actually a ladder.

The second difference is chroma instead of saturation. Chroma is not clipped by the display gamut, so values stay consistent when you move between hues. The trade-off sits in the toolchain: any browser recent enough to run Codex resolves oklch(), but older design tools preview it wrong. Keep a hex or hsl() fallback line above each declaration.

• oklch(65% 0.13 250): lightness, chroma, hue, in that order
• Lightness is perceptual, so 65% reads the same whether the hue is blue or yellow
• Chroma above roughly 0.37 leaves sRGB and gets clipped on most displays
• Keep a hex or hsl() fallback line above every oklch() declaration

Converting a theme you already have

• List every color in the theme file and note which slot each one fills
• Convert each value to HSL and write down the resulting triplet
• Group them by role: backgrounds, body text, syntax, accents
• Set target lightness steps per role before you touch any hue
• Move to OKLCH once the structure holds, one role at a time

Checks that catch trouble before you commit

• Compare body lightness against background lightness and keep the gap above 40 in OKLCH terms
• Squint at the screen: if two syntax colors merge, separate them in hue rather than lightness
• Turn screen brightness low and look again, which is where weak contrast themes fall apart
• Check both light and dark schemes, since any role you skip falls back to the default
• Look at the scrollbar and the gutter, usually the last elements anybody colors

Color is the one part of a theme that touches every line you read, so an hour spent on it upfront pays back for months. Compare against finished work in the gallery at https://codex-skin-studio.shop/en/gallery/, and the rest of the entry points sit on https://codex-skin-studio.shop/en/.

Frequently asked questions