Tailwind CSS v4 Best Practices

Quick Reference

Vite Plugin Setup:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

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

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