Using Theme Variables

Purpose

Define custom design tokens using the @theme directive with CSS variables. Tailwind v4 uses modern color formats (oklch) and namespace-based utility generation.

Basic Theme Variables

@import 'tailwindcss';

@theme {
  --font-display: 'Satoshi', 'sans-serif';
  --font-body: 'Inter', 'sans-serif';

  --color-brand-primary: oklch(0.65 0.25 270);
  --color-brand-accent: oklch(0.75 0.22 320);

  --breakpoint-3xl: 120rem;
  --breakpoint-4xl: 160rem;

  --spacing-18: 4.5rem;
  --spacing-72: 18rem;

  --radius-4xl: 2rem;

  --shadow-brutal: 8px 8px 0 0 rgb(0 0 0);
}

Color Format: oklch()

Tailwind v4 uses OkLCh color space instead of RGB for wider gamut and more vivid colors on modern displays.

oklch() syntax:

oklch(Lightness Chroma Hue)

• Lightness: 0 (black) to 1 (white)
• Chroma: 0 (gray) to ~0.4 (vivid)
• Hue: 0-360 degrees

Examples:

@theme {
  --color-blue: oklch(0.65 0.25 270);
  --color-green: oklch(0.72 0.15 142);
  --color-red: oklch(0.65 0.22 25);
  --color-purple: oklch(0.75 0.22 320);
  --color-orange: oklch(0.78 0.18 60);
}

Theme Variable Namespaces

Tailwind generates utilities based on variable name prefixes:

Example usage:

@theme {
  --color-brand: oklch(0.65 0.25 270);
  --spacing-18: 4.5rem;
  --radius-4xl: 2rem;
}

Generates utilities:

<div class="bg-brand text-brand border-brand"></div>
<div class="p-18 m-18 w-18"></div>
<div class="rounded-4xl"></div>

Semantic Naming

Use meaningful names instead of generic scales:

@theme {
  --color-primary: oklch(0.65 0.25 270);
  --color-secondary: oklch(0.75 0.22 320);
  --color-success: oklch(0.72 0.15 142);
  --color-warning: oklch(0.78 0.18 60);
  --color-error: oklch(0.65 0.22 25);

  --color-text: oklch(0.21 0 0);
  --color-text-muted: oklch(0.51 0 0);
  --color-background: oklch(0.99 0 0);
}

Usage:

<button class="bg-primary text-white hover:opacity-90">Primary Button</button>
<div class="text-error">Error message</div>
<p class="text-text-muted">Muted text</p>

Extending Default Theme

Add new values without removing defaults:

@theme {
  --color-lagoon: oklch(0.72 0.11 221.19);
  --color-coral: oklch(0.74 0.17 40.24);
  --font-script: 'Great Vibes', cursive;
  --breakpoint-3xl: 120rem;
}

All default Tailwind utilities remain available (blue-500, gray-200, etc.).

Replacing Default Theme

Remove all defaults and define only custom variables:

@theme {
  --*: initial;

  --spacing: 4px;
  --font-body: 'Inter', sans-serif;
  --color-lagoon: oklch(0.72 0.11 221.19);
  --color-coral: oklch(0.74 0.17 40.24);
}

Only utilities based on custom variables will be generated.

Inline Theme Variables

Reference other variables using the inline option:

@theme inline {
  --font-sans: var(--font-inter);
  --color-primary: var(--color-red-500);
  --spacing-gutter: var(--spacing-4);
}

Variables defined in @theme inline can reference variables from main @theme.

Static Theme Variables

Generate all CSS variables even if unused:

@theme static {
  --color-primary: var(--color-red-500);
  --color-secondary: var(--color-blue-500);
}

Useful for runtime JavaScript access:

const styles = getComputedStyle(document.documentElement);
const primaryColor = styles.getPropertyValue('--color-primary');

Accessing Variables in JavaScript

const styles = getComputedStyle(document.documentElement);
const shadow = styles.getPropertyValue('--shadow-xl');
const color = styles.getPropertyValue('--color-blue-500');

Setting variables dynamically:

document.documentElement.style.setProperty('--color-primary', 'oklch(0.70 0.20 180)');

In animation libraries:

<motion.div animate={{ backgroundColor: 'var(--color-blue-500)' }} />

Sharing Themes Across Projects

Create shared theme file:

packages/brand/theme.css:

@theme {
  --*: initial;

  --spacing: 4px;
  --font-body: 'Inter', sans-serif;
  --color-lagoon: oklch(0.72 0.11 221.19);
  --color-coral: oklch(0.74 0.17 40.24);
}

Import in projects:

@import 'tailwindcss';
@import '@my-company/brand/theme.css';

Complex Theme Example

@import 'tailwindcss';

@theme {
  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;

  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;

  --color-white: #ffffff;
  --color-black: #000000;

  --color-gray-50: oklch(0.99 0 0);
  --color-gray-100: oklch(0.97 0 0);
  --color-gray-900: oklch(0.21 0 0);

  --color-primary: oklch(0.65 0.25 270);
  --color-secondary: oklch(0.75 0.22 320);
  --color-success: oklch(0.72 0.15 142);

  --spacing: 0.25rem;
  --spacing-px: 1px;
  --spacing-1: calc(var(--spacing) * 1);
  --spacing-4: calc(var(--spacing) * 4);

  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-full: 9999px;

  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);

  --breakpoint-sm: 40rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
}

Best Practices

1. Use semantic names instead of scales (primary vs blue-500)
2. Use oklch() for color definitions
3. Define variables at :root for performance
4. Group related variables (colors, spacing, typography)
5. Reference other variables with inline theme
6. Share themes across projects using imports

See Also

• references/color-conversion.md - Hex to oklch conversion table
• references/namespace-reference.md - Complete namespace documentation