Migrate color system from HEX to OKLCH

[ravisuhag]

Summary

Migrate the design token color system from HEX values to OKLCH color format for perceptually uniform colors, better dynamic theming, and wider gamut (P3) display support.

Motivation

• Perceptual uniformity — equal numeric changes in OKLCH produce equal visual changes, unlike HEX/RGB
• Better dark mode authoring — the lightness channel makes light↔dark palette mapping more predictable and systematic
• Wider gamut — natively supports P3 displays without fallback hacks
• Dynamic theming — programmatic adjustments to L (lightness), C (chroma), or H (hue) produce consistent, predictable results

Scope

Primitive tokens (main effort)

Convert all HEX values to oklch() in:

• packages/raystack/styles/primitives/gray.css — 4 gray palettes × 12 steps × 2 themes
• packages/raystack/styles/primitives/accent.css — 3 accent palettes × 13 steps × 2 themes
• packages/raystack/styles/primitives/appearance.css — semantic primitives (neutral, danger, attention, success) × 2 themes
• Visualization colors — 14 palettes × 12 steps × 2 themes

Overlay tokens

Convert HEX+alpha overlays to OKLCH alpha syntax:

/* before */
--rs-color-overlay-black-a6: #00000080;
/* after */
--rs-color-overlay-black-a6: oklch(0 0 0 / 50%);

ColorPicker component

• Update packages/raystack/components/color-picker/utils.ts to support OKLCH as a color mode
• Replace or supplement the color npm package (no OKLCH support) with culori or colorjs.io

Documentation

• Update apps/www/src/content/docs/theme/colors/index.mdx with OKLCH format references

No component changes needed

Components consume semantic CSS variables (var(--rs-color-...)), so no component CSS files need modification.

Approach

1. Write a conversion script using culori or colorjs.io to batch-convert HEX → OKLCH
2. Convert primitive token files (gray.css, accent.css, appearance.css)
3. Convert overlay tokens
4. Run visual regression tests to catch any perceptual shifts
5. Update ColorPicker to support OKLCH mode
6. Update docs

Browser Support

OKLCH is supported in all modern browsers (Chrome 111+, Firefox 113+, Safari 15.4+). If older browser support is required, provide HEX fallbacks using CSS cascade:

--rs-gray-1: #fcfcfc;
--rs-gray-1: oklch(0.993 0.001 264);

References

• OKLCH color space
• CSS Color Level 4 spec
• Can I Use: oklch