---
name: using-theme-variables
description: Define and use theme variables with @theme directive, oklch() color format, semantic naming, and namespaced utilities. Use when customizing design tokens or creating design systems.
allowed-tools: Read, Write, Edit, Grep, Glob
---

# 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

```css
@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:**

```css
@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:

| Namespace         | Utilities Generated                        |
| ----------------- | ------------------------------------------ |
| `--color-*`       | bg-, text-, fill-, stroke-, border-, ring- |
| `--font-*`        | font-family utilities                      |
| `--text-*`        | font-size utilities                        |
| `--font-weight-*` | font-weight utilities                      |
| `--tracking-*`    | letter-spacing utilities                   |
| `--leading-*`     | line-height utilities                      |
| `--breakpoint-*`  | responsive breakpoint variants             |
| `--spacing-*`     | padding, margin, sizing utilities          |
| `--radius-*`      | border-radius utilities                    |
| `--shadow-*`      | box-shadow utilities                       |
| `--animate-*`     | animation utilities                        |

**Example usage:**

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

Generates utilities:

```html
<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:

```css
@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:**

```html
<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:

```css
@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:

```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);
}
```

Only utilities based on custom variables will be generated.

## Inline Theme Variables

Reference other variables using the inline option:

```css
@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:

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

Useful for runtime JavaScript access:

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

## Accessing Variables in JavaScript

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

**Setting variables dynamically:**

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

**In animation libraries:**

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

## Sharing Themes Across Projects

**Create shared theme file:**

**packages/brand/theme.css:**

```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:**

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

## Complex Theme Example

```css
@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