Zero-Runtime Component Libraries with Tailwind CSS v4 & OKLCH

The Evolution of Utility-First CSS

Tailwind CSS v4 fundamentally changes how design tokens are defined by moving away from JavaScript configuration files (tailwind.config.js) to native CSS declarations using the @theme directive.

@theme {
  --color-primary: oklch(0.205 0 0);
  --color-accent: oklch(0.97 0 0);
  --font-sans: var(--font-google-sans), system-ui, sans-serif;
  --font-mono: var(--font-google-sans-code), monospace;
}

Why OKLCH Matters for Theme Architecture

Traditional RGB and HSL color models suffer from non-uniform perceived lightness. A yellow hue at 50% HSL lightness appears dramatically brighter than a blue hue at the same 50% lightness value.

• Perceptual Uniformity: In OKLCH, lightness (L) maps directly to human visual perception.
• Predictable Contrast: Calculating WCAG contrast ratios across dark and light modes becomes deterministic and mathematically consistent.

:root {
  --background: oklch(0.99 0 0);
  --foreground: oklch(0.12 0 0);
  --border: oklch(0.90 0 0);
}
 
.dark {
  --background: oklch(0.10 0 0);
  --foreground: oklch(0.98 0 0);
  --border: oklch(0.22 0 0);
}

Headless Primitives + Polymorphic Tokens

By pairing unstyled Radix UI primitives with Tailwind CSS v4 utility classes via class-variance-authority (CVA), we produce accessible interactive components with zero styling lock-in and zero runtime JavaScript styling overhead.