Tailwind CSS v4 Architecture & CSS-First Config

Tailwind CSS v4 represents the most radical and powerful evolution in the framework's history. Built from scratch on top of Oxide (a high-speed Rust-based compiler engine), Tailwind v4 delivers 10x to 100x faster build times, zero-configuration setups, and replaces the legacy tailwind.config.js JavaScript file with a CSS-First Configuration Architecture.

┌─────────────────────────────────────────────────────────────┐
│                 Tailwind v3 vs Tailwind v4 Comparison       │
├──────────────────────────────┬──────────────────────────────┤
│ Tailwind v3 (Legacy)         │ Tailwind v4 (Modern Standard)│
├──────────────────────────────┼──────────────────────────────┤
│ - tailwind.config.js (JS)    │ - Pure CSS Config (@theme)   │
│ - PostCSS & JavaScript JIT   │ - Rust-based Oxide Engine    │
│ - Manual content[] glob cfg  │ - Automatic file scanning    │
│ - @tailwind base/components  │ - @import "tailwindcss";     │
│ - Complex plugin JavaScript  │ - @utility & @variant in CSS │
└──────────────────────────────┴──────────────────────────────┘

1. The Modern CSS-First `@theme` Directive

In Tailwind v4, you configure custom design tokens directly inside your CSS file without creating a JavaScript config:

/* src/app.css */
@import "tailwindcss";

@theme {
  --color-brand-500: #6366f1;
  --color-brand-600: #4f46e5;
  --color-surface: #0f172a;

  --font-display: "Cabinet Grotesk", sans-serif;
  --font-body: "Inter", sans-serif;

  --spacing-18: 4.5rem;
  --radius-4xl: 2rem;
}

Every variable defined inside @theme automatically generates corresponding utility classes (bg-brand-600, font-display, p-18, rounded-4xl) with zero extra configuration!

2. Defining Custom Utilities with `@utility`

@utility tab-highlight-none {
  -webkit-tap-highlight-color: transparent;
}

@utility text-glow {
  text-shadow: 0 0 12px rgba(99, 102, 241, 0.6);
}

3. Custom Variants with `@variant`

@variant pointer-coarse {
  @media (pointer: coarse) {
    & { @slot; }
  }
}

Now you can write pointer-coarse:p-6 to enlarge touch targets on touchscreens!

Summary & Key Takeaways

Tailwind v4 is powered by the ultra-fast Rust-based Oxide compiler.
Replaces tailwind.config.js with CSS-native @theme declarations.
@utility and @variant define custom classes directly in stylesheets.
Automatic content detection removes the need for manual content array glob patterns.

Best Practices & Senior Guidance

Adopt Tailwind v4 for New Projects: Enjoy instant build times and clean CSS-native design token management.

Tailwind CSS v4 Architecture & CSS-First Config

1. The Modern CSS-First @theme Directive

2. Defining Custom Utilities with @utility

3. Custom Variants with @variant

Summary & Key Takeaways

Best Practices & Senior Guidance

1. The Modern CSS-First `@theme` Directive

2. Defining Custom Utilities with `@utility`

3. Custom Variants with `@variant`