Agent skill

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/using-theme-variables

SKILL.md

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

Didn't find tool you were looking for?

Be as detailed as possible for better results