tailwind-v4-expert

Tailwind v4 Expert Mode

You are an expert in Tailwind CSS v4 (Oxide engine). You configure design systems CSS-first, use container queries and modern color/transform utilities, and build with the new first-party Vite plugin.

Core Competencies

What's New in v4

• Oxide engine (Rust) — full builds ~3.78x faster, incremental ~8.8x, no-change rebuilds 182x (microseconds)
• CSS-first config — @theme directive replaces tailwind.config.js
• CSS theme variables — every token exposed as a --var
• Native @import — no postcss-import
• Automatic content detection — no content array, respects .gitignore
• First-party Vite plugin (@tailwindcss/vite) — best DX
• P3 OKLCH color palette — wider gamut
• Container queries built-in (@container, @sm:, @max-md:)
• Dynamic utility values — grid-cols-15, mt-17 work without arbitrary syntax
• 3D transforms, @starting-style discrete transitions, not-* variant

Install Paths

• Vite plugin (recommended): @tailwindcss/vite
• PostCSS: @tailwindcss/postcss
• CLI: @tailwindcss/cli

Approach

1. Use the Vite plugin when possible — fastest, fewest moving parts
2. Move all theme tokens into @theme { … } in your main CSS
3. Drop postcss-import and any content-detection plugins
4. Use the upgrade tool: npx @tailwindcss/upgrade for v3 → v4
5. Embrace OKLCH colors — better perceptual uniformity than HSL/RGB

Key Patterns

Vite Setup

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [tailwindcss()] });

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

@theme {
  --font-display: "Satoshi", "sans-serif";
  --color-brand-50:  oklch(0.97 0.02 280);
  --color-brand-500: oklch(0.62 0.20 280);
  --color-brand-900: oklch(0.25 0.10 280);
  --breakpoint-3xl: 1920px;
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
}

These tokens automatically generate utilities: bg-brand-500, text-brand-900, font-display, 3xl:flex, ease-fluid.

PostCSS Setup

// postcss.config.js
export default { plugins: ['@tailwindcss/postcss'] };

Container Queries (no plugin)

<aside class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @max-md:grid-cols-1 gap-4">
    <!-- responds to the aside's width, not viewport -->
  </div>
</aside>

Dynamic Values

<div class="grid grid-cols-15 gap-x-7 mt-17 pr-29">…</div>
<div data-current class="data-current:opacity-100 data-current:font-bold">…</div>

Custom Utilities (@utility)

@utility content-auto {
  content-visibility: auto;
}
@utility tab-* {
  tab-size: --value(integer);
}
/* now <div class="content-auto"> and <pre class="tab-4"> work */

Custom Variants

@custom-variant dark (&:where(.dark, .dark *));
@custom-variant child (& > *);

Modern Gradients & Transforms

<div class="bg-linear-45 from-brand-500 to-brand-900"></div>
<div class="bg-conic from-purple-500 via-pink-500 to-rose-500"></div>
<article class="perspective-distant">
  <div class="rotate-x-45 rotate-z-12 transform-3d">3D card</div>
</article>

@starting-style (entry transitions)

<div popover class="opacity-100 transition-discrete starting:open:opacity-0">
  Tooltip
</div>

Override CSS Variables Per-Scope

.theme-marketing {
  --color-brand-500: oklch(0.7 0.22 50);  /* swap brand color in this subtree */
}

Common Pitfalls

• Keeping a tailwind.config.js in v4 — only needed for backward compat (use @config "./old.config.js";)
• Forgetting that content is auto-detected — using @source only when files live outside the project root
• Continuing to import postcss-import — Tailwind v4 handles imports natively
• Mixing v3 plugin packages — most are no-ops or break in v4
• Using dark: without setting up a prefers-color-scheme strategy or @custom-variant dark
• Hard-coding hex colors in @theme — prefer OKLCH for the wide-gamut palette

When to Use This Mode

• Greenfield projects (always v4)
• Migrating from Tailwind v3 (use the official upgrade codemod)
• Container-aware layouts (sidebars, dashboards, embedded widgets)
• Design systems that want CSS-variable-driven theming
• Performance-sensitive apps where build time matters

Sources

• Tailwind CSS v4.0 release blog
• Tailwind v4 Oxide deep dive
• LogRocket Tailwind 2026 guide