tailwind-hue-theme

Why This Exists

Tailwind has excellent color semantics, but its palette is static. You pick your colors at build time and ship them. If a client needs a rebrand — or if you're building a tool where every user gets their own color — you're either regenerating a CSS file, maintaining parallel configs, or reaching for a CSS-in-JS solution that adds runtime overhead.

The deeper problem is that it's not just one color. A brand palette needs a full range — backgrounds, borders, text, interactive states, accents. Getting those to look consistent across hues is where traditional approaches fall apart.

The OKLCH Advantage

Traditional hsl() is convenient but perceptually inconsistent. A yellow at hsl(60 100% 50%) looks blazingly bright; a blue at hsl(240 100% 50%) looks comparatively dim — same "lightness", very different perception. OKLCH fixes this.

Because L in OKLCH is perceptually calibrated, pinning lightness and chroma and sweeping H across the spectrum produces colors of equal perceived brightness and saturation — that's what makes the single-variable approach work correctly.

How It Works

The plugin calls Tailwind's addBase() API to inject 33 CSS custom properties into :root. Every token is an oklch() expression that references --brand-h. The L and C values are fixed per-scale; only the hue is variable.

:root {
  --brand-h: 250; /* default indigo hue */

  /* slate — low chroma, dark backgrounds stay dark */
  --color-slate-50:  oklch(0.984 0.004 var(--brand-h, 250));
  --color-slate-950: oklch(0.13  0.028 var(--brand-h, 250));

  /* indigo — full chroma, follows brand hue directly */
  --color-indigo-500: oklch(0.585 0.18  var(--brand-h, 250));

  /* cyan — offset hue for a complementary secondary */
  --color-cyan-500:   oklch(0.585 0.18  calc(var(--brand-h, 250) + 40));
}

API Reference

Two exports from the main entry point.

import { buildTokens } from 'tailwind-hue-theme'

const tokens = buildTokens({ defaultHue: 155 })
// tokens['--color-indigo-500']
// → 'oklch(0.585 0.18 var(--brand-h, 155))'

Integration Patterns

Four ways to use the plugin — pick the one that fits your stack.

@import "tailwindcss";
@plugin "tailwind-hue-theme";

// tailwind.config.js
import { createHuePlugin } from 'tailwind-hue-theme'

export default {
  plugins: [createHuePlugin({ defaultHue: 155 })],
}

<script type="module">
  import { HuePicker } from 'tailwind-hue-theme/widget'
  new HuePicker()
</script>

<style>
  :root { --brand-h: <%= user.brandHue %>; }
</style>
<!-- No JS, no flash, no extra request -->

HuePicker Options

Imported from tailwind-hue-theme/widget. Completely optional — the plugin itself has no DOM dependency.

import { HuePicker, DEFAULT_PRESETS } from 'tailwind-hue-theme/widget'

const picker = new HuePicker({
  defaultHue: 250,
  presets: [
    ...DEFAULT_PRESETS,
    { label: 'Brand Blue', hue: 220 },
  ],
  onChange: (hue) => {
    fetch('/api/preferences', {
      method: 'POST',
      body: JSON.stringify({ brandHue: hue }),
    })
  },
})

TypeScript

The package is fully typed. All interfaces are exported from their respective entry points.

import {
  createHuePlugin,
  buildTokens,
  type HuePluginOptions,
} from 'tailwind-hue-theme'

import {
  HuePicker,
  DEFAULT_PRESETS,
  getWidgetCSS,
  type HuePickerOptions,
  type HuePreset,
} from 'tailwind-hue-theme/widget'

getWidgetCSS() returns the raw CSS string injected by the widget — useful for SSR environments that pre-inject styles rather than letting the widget self-inject its <style> tag.