6.8 KiB
6.8 KiB
name, description, allowed-tools
| name | description | allowed-tools |
|---|---|---|
| using-theme-variables | 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. | 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
@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:
| 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:
@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
- Use semantic names instead of scales (primary vs blue-500)
- Use oklch() for color definitions
- Define variables at :root for performance
- Group related variables (colors, spacing, typography)
- Reference other variables with inline theme
- Share themes across projects using imports
See Also
- references/color-conversion.md - Hex to oklch conversion table
- references/namespace-reference.md - Complete namespace documentation