Customizing OKLCH colors in your VeloCMS theme

VeloCMS themes define all colors in OKLCH — a perceptually uniform color space where adjusting lightness by 10 points looks like a consistent change regardless of the hue. This is different from HSL, where a lightness change from 40% to 50% looks dramatic in some hues and barely noticeable in others. With OKLCH you get predictable, WCAG-accessible color systems without manually checking contrast ratios.

Understanding the three OKLCH axes

OKLCH uses three values: L (lightness, 0-100%), C (chroma, roughly 0-0.4 where 0 is grey and 0.37 is a saturated primary), and H (hue, 0-360 degrees). To shift your theme's accent color from blue to teal, change only H — from around 250 to around 180 — and leave L and C intact. The color stays the same relative luminance and saturation, just in a different hue family.

/* Example: changing primary accent from indigo to teal */
:root {
  /* original indigo */
  --primary: oklch(0.55 0.22 250);
  /* changed to teal -- only H changed */
  --primary: oklch(0.55 0.22 180);
}

/* Light/dark pair that maintains WCAG AA contrast */
:root  { --background: oklch(0.98 0 0); --foreground: oklch(0.12 0 0); }
.dark  { --background: oklch(0.10 0 0); --foreground: oklch(0.96 0 0); }

Editing theme colors in Admin Themes

Go to Admin Themes and select your active theme. The Colors section shows each semantic token — background, foreground, primary, secondary, muted, accent, destructive — with a visual swatch and an editable OKLCH value. Click a swatch to open the color picker, which displays the OKLCH axes as sliders. Drag the hue slider to shift the whole color family, or adjust chroma to go from muted to vivid. Changes preview live in the admin before you save.

Staying accessible without manual checks

The theme editor runs a live contrast check between background and foreground, and between primary and primary-foreground. If the contrast ratio drops below 4.5:1 (WCAG AA for normal text), a warning badge appears on the failing pair. Fix it by either darkening the foreground or lightening the background until the badge clears.