tailwind-v4

$2a

CSS Entry Point:

/* src/index.css */

@import 'tailwindcss';

@theme Inline Directive:

@theme inline {

  --color-primary: oklch(60% 0.24 262);

  --color-surface: oklch(98% 0.002 247);

}

Key Differences from v3

Feature

v3

v4

Configuration

tailwind.config.js

@theme in CSS

Build Tool

PostCSS plugin

@tailwindcss/vite

Colors

rgb() / hsl()

oklch() (default)

Theme Extension

extend: {} in JS

CSS variables

Dark Mode

darkMode config option

CSS variants

@theme Directive Modes

default (standard mode)

Generates CSS variables that can be referenced elsewhere:

@theme {

  --color-brand: oklch(60% 0.24 262);

}

/* Generates: :root { --color-brand: oklch(...); } */

/* Usage: text-brand → color: var(--color-brand) */

Note: You can also use @theme default explicitly to mark theme values that can be overridden by non-default @theme declarations.

inline

Inlines values directly without CSS variables (better performance):

@theme inline {

  --color-brand: oklch(60% 0.24 262);

}

/* Usage: text-brand → color: oklch(60% 0.24 262) */

reference

Inlines values as fallbacks without emitting CSS variables:

@theme reference {

  --color-internal: oklch(50% 0.1 180);

}

/* No :root variable, but utilities use fallback */

/* Usage: bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) */

OKLCH Color Format

OKLCH provides perceptually uniform colors with better consistency across hues:

oklch(L% C H)

• L (Lightness): 0% (black) to 100% (white)

• C (Chroma): 0 (gray) to ~0.4 (vibrant)

• H (Hue): 0-360 degrees (red → yellow → green → blue → magenta)

Examples:

--color-sky-500: oklch(68.5% 0.169 237.323);  /* Bright blue */

--color-red-600: oklch(57.7% 0.245 27.325);   /* Vibrant red */

--color-zinc-900: oklch(21% 0.006 285.885);   /* Near-black gray */

CSS Variable Naming

Tailwind v4 uses double-dash CSS variable naming conventions:

@theme {

  /* Colors: --color-{name}-{shade} */

  --color-primary-500: oklch(60% 0.24 262);

  /* Spacing: --spacing multiplier */

  --spacing: 0.25rem;  /* Base unit for spacing scale */

  /* Fonts: --font-{family} */

  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* Breakpoints: --breakpoint-{size} */

  --breakpoint-lg: 64rem;

  /* Custom animations: --animate-{name} */

  --animate-fade-in: fade-in 0.3s ease-out;

}

No Config Files Needed

Tailwind v4 eliminates configuration files:

• **No tailwind.config.js** - Use @theme in CSS instead

• **No postcss.config.js** - Use @tailwindcss/vite plugin

• TypeScript support - Add @types/node for path resolution

{

  "devDependencies": {

    "@tailwindcss/vite": "^4.0.0",

    "@types/node": "^22.0.0",

    "tailwindcss": "^4.0.0",

    "vite": "^6.0.0"

  }

}

Progressive Disclosure

• Setup & Installation: See references/setup.md for Vite plugin configuration, package setup, TypeScript config

• Theming & Design Tokens: See references/theming.md for @theme modes, color palettes, custom fonts, animations

• Dark Mode Strategies: See references/dark-mode.md for media queries, class-based, attribute-based approaches

Gates (setup verification)

Before recommending @theme choices, OKLCH tokens, or v4 utilities, confirm the project is actually on the v4 integration path:

• Build wiring: The Vite config loads tailwindcss() from @tailwindcss/vite, and the CSS entry uses @import 'tailwindcss'. If this fails, stop — fix wiring per references/setup.md first.

• Major versions: package.json lists tailwindcss (and @tailwindcss/vite when using Vite) at major 4, not a v3 PostCSS-only toolchain.

• Theme source: New theme tokens live in @theme / @theme inline in CSS — not tailwind.config.js extend (v3). If a v3 config still drives the theme, migrating wiring takes precedence over token tweaks.

Decision Guide

When to use @theme inline vs default

**Use @theme inline**:

• Better performance (no CSS variable overhead)

• Static color values that won't change

• Animation keyframes with multiple values

• Utilities that need direct value inlining

**Use @theme (default)**:

• Dynamic theming with JavaScript

• CSS variable references in custom CSS

• Values that change based on context

• Better debugging (inspect CSS variables in DevTools)

When to use @theme reference

**Use @theme reference**:

• Provide fallback values without CSS variable overhead

• Values that should work even if variable isn't defined

• Reducing :root bloat while maintaining utility support

• Combining with inline for direct value substitution

Common Patterns

Two-Tier Variable System

Semantic variables that map to design tokens:

@theme {

  /* Design tokens (OKLCH colors) */

  --color-blue-600: oklch(54.6% 0.245 262.881);

  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* Semantic mappings */

  --color-primary: var(--color-blue-600);

  --color-surface: var(--color-slate-800);

}

/* Usage: bg-primary, bg-surface */

Custom Font Configuration

@theme {

  --font-display: 'Inter Variable', system-ui, sans-serif;

  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --font-display--font-variation-settings: 'wght' 400;

  --font-display--font-feature-settings: 'cv02', 'cv03', 'cv04';

}

/* Usage: font-display, font-mono */

Animation Keyframes

@theme inline {

  --animate-beacon: beacon 2s ease-in-out infinite;

  @keyframes beacon {

    0%, 100% {

      opacity: 1;

      transform: scale(1);

    }

    50% {

      opacity: 0.5;

      transform: scale(1.05);

    }

  }

}

/* Usage: animate-beacon */