Node.js 18+ required for Oxide engine Skill

Overview

Tailwind CSS v4 is a complete rewrite of the framework, built on a new Rust-based Oxide engine that's 10x faster. The biggest change: configuration is now done in CSS, not JavaScript. No more tailwind.config.js for most projects.

Browser support: Safari 16.4+, Chrome 111+, Firefox 128+

The Oxide Engine (Performance)

Tailwind v4 uses a new Rust-based Oxide engine with dramatically improved performance:

| Operation | v3 Speed | v4 Speed (Oxide) | Improvement | |-----------|----------|-----------------|-------------| | Cold build | 8s | 2.1s | 3.78x faster | | Incremental | 450ms | 51ms | 8.8x faster | | HMR (Hot Module Reload) | 350ms | 12ms | 28x faster | | Memory usage | Higher | Lower | ~50% reduction |

Why It's Faster

Rust-native: Core processing in Rust, not JavaScript
Parallel processing: Uses all CPU cores efficiently
Better caching: Improved incremental build detection
Optimized CSS generation: Less overhead in utility generation

Requirements

# Node.js 18+ required for Oxide engine
node --version  # Should be 18 or higher

# Install with Vite (recommended for best performance)
npm install tailwindcss @tailwindcss/vite

# Or PostCSS (also fast)
npm install tailwindcss @tailwindcss/postcss

Installation

Vite (Recommended)

npm install tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from "@tailwindcss/vite";

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

PostCSS

npm install -D tailwindcss @tailwindcss/postcss

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

CLI

npm install -D @tailwindcss/cli
npx @tailwindcss/cli -i input.css -o output.css --watch

Basic Setup

The CSS File

/* input.css */
@import "tailwindcss";

/* Your custom styles below */

That's it. No @tailwind base/components/utilities directives—they're gone.

Theme Configuration with @theme

Customize your design tokens directly in CSS using the @theme directive:

@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand: oklch(65% 0.25 250);
  --color-brand-light: oklch(75% 0.25 250);
  --color-brand-dark: oklch(55% 0.25 250);
  
  /* Custom fonts */
  --font-display: "Clash Display", "sans-serif";
  --font-body: "Satoshi", "sans-serif";
  
  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
  
  /* Custom breakpoints */
  --breakpoint-3xl: 120rem;
  
  /* Custom animations */
  --animate-fade-in: fade-in 0.5s ease-out;
  
  /* Shadow customization */
  --shadow-card: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(10px); }
  to { opacity: 1; transform: translateY(0); }
}

Using Theme Values

All theme values become CSS variables automatically:

/* These are automatically generated from @theme */
.btn {
  background-color: var(--color-brand);
  font-family: var(--font-display);
}

In your HTML, use them directly as utility values:

<button class="bg-brand hover:bg-brand-dark font-display px-4 py-2">
  Click me
</button>

Dark Mode

In v4, dark mode uses @media (prefers-color-scheme) by default—no config needed.

<!-- Automatically responds to OS preference -->
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  Hello, dark mode!
</div>

For manual toggle, add .dark class to <html> element:

<html class="dark">
  <div class="bg-white dark:bg-gray-900">...</div>
</html>

No darkMode config option needed—it just works.

Custom Utilities with @utility

Create reusable utilities directly in CSS:

@utility container {
  margin-inline: auto;
  padding-inline: 1.5rem;
}

@utility tab-4 {
  tab-size: 4;
}

@utility btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 0.5rem;
  padding: 0.5rem 1rem;
  font-weight: 600;
  transition: background-color 0.2s;
  
  &:hover {
    filter: brightness(1.1);
  }
}

Usage in HTML:

<button class="btn bg-blue-600 text-white">Button</button>
<div class="tab-4">Code block</div>
<div class="container">Centered content</div>

Custom Variants with @variant

Define your own variants:

/* Custom variant for external links */
@custom-variant external (&[rel="external"]);

/* Custom variant for touch devices */
@custom-variant touch (&:hover@media (hover: none));

Usage:

<a href="https://example.com" rel="external" class="external:text-blue-600">
  External link
</a>

Built-in Variants

Common variants work the same as v3:

<button class="hover:bg-blue-600 focus:ring-2 active:scale-95 disabled:opacity-50">
  Interactive Button
</button>

Variant Stacking Order

In v4, stacked variants apply left-to-right (CSS-like order):

<!-- v3 (right-to-left): -->
<div class="first:*:pt-0 last:*:pb-0">

<!-- v4 (left-to-right): -->
<div class="*:first:pt-0 *:last:pb-0">
</div>

Arbitrary Values

CSS Variables (New Syntax)

Variables now use parentheses, not brackets:

<!-- v3 -->
<div class="bg-[--brand-color]">

<!-- v4 -->
<div class="bg-(--brand-color)">

Grid Values

Use underscores for spaces, not commas:

<!-- v3 -->
<div class="grid-cols-[max-content,auto]">

<!-- v4 -->
<div class="grid-cols-[max-content_auto]">

The Important Modifier

The ! now goes at the end of the utility:

<!-- v3 -->
<div class="!bg-red-500">

<!-- v4 -->
<div class="bg-red-500!">

Both work in v4, but the new syntax is preferred.

Automatic Content Detection

No more content array in config. Tailwind v4 automatically scans for classes in your project.

Backward Compatibility with @config

Need to keep your old tailwind.config.js? Use @config:

@import "tailwindcss";
@config "../../tailwind.config.js";

Note: corePlugins, safelist, and separator options are not supported in v4.

The @theme Directive (Complete Reference)

The @theme directive is the heart of v4 configuration. It defines design tokens that become CSS variables and utility classes.

Color System

@theme {
  /* Brand colors using OKLCH - recommended for P3 gamut */
  --color-brand: oklch(65% 0.25 250);
  --color-brand-50: oklch(98% 0.02 250);
  --color-brand-100: oklch(95% 0.05 250);
  --color-brand-200: oklch(90% 0.1 250);
  --color-brand-300: oklch(80% 0.15 250);
  --color-brand-400: oklch(70% 0.2 250);
  --color-brand-500: oklch(65% 0.25 250);
  --color-brand-600: oklch(55% 0.25 250);
  --color-brand-700: oklch(45% 0.25 250);
  --color-brand-800: oklch(35% 0.25 250);
  --color-brand-900: oklch(25% 0.25 250);
  --color-brand-950: oklch(15% 0.2 250);

  /* Semantic colors */
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: #3b82f6;
  
  /* Extend existing colors */
  --color-blue-950: oklch(20% 0.15 240);
}

OKLCH Color Syntax

v4 uses OKLCH by default for better color accuracy:

/* Syntax: oklch(lightness chroma hue [opacity]) */
--color-primary: oklch(60% 0.18 250);
--color-translucent: oklch(60% 0.18 250 / 50%);

Benefits of OKLCH:

P3 color gamut support (more vibrant colors)
Predictable interpolation (no more gray shifts in gradients)
CSS native (no runtime conversion)

Spacing Scale

@theme {
  /* Add custom spacing */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
  --spacing-26: 6.5rem;
  --spacing-72: 18rem;
  --spacing-84: 21rem;
  --spacing-96: 24rem;
  
  /* Spacing for specific use cases */
  --spacing-header: 4rem;
  --spacing-card: 1.5rem;
}

Breakpoints

@theme {
  /* Add custom breakpoints */
  --breakpoint-3xl: 120rem;
  --breakpoint-4xl: 140rem;
  
  /* Modify existing */
  --breakpoint-sm: 30rem;  /* 480px */
  --breakpoint-md: 40rem;  /* 640px */
}

Shadows

@theme {
  /* Custom shadows */
  --shadow-card: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-elevated: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  --shadow-glow: 0 0 20px oklch(65% 0.25 250 / 50%);
  --shadow-inner-lg: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
}

Typography

@theme {
  /* Custom fonts */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-display: "Clash Display", sans-serif;
  --font-mono: "JetBrains Mono", monospace;
  
  /* Font sizes */
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;
  --text-4xl: 2.25rem;
  --text-5xl: 3rem;
  --text-6xl: 3.75rem;
  --text-7xl: 4.5rem;
  --text-8xl: 6rem;
  --text-9xl: 8rem;
  
  /* Line heights */
  --leading-none: 1;
  --leading-tight: 1.25;
  --leading-snug: 1.375;
  --leading-normal: 1.5;
  --leading-relaxed: 1.625;
  --leading-loose: 2;
  
  /* Letter spacing */
  --tracking-tighter: -0.05em;
  --tracking-tight: -0.025em;
  --tracking-normal: 0em;
  --tracking-wide: 0.025em;
  --tracking-wider: 0.05em;
  --tracking-widest: 0.1em;
}

Animations

@theme {
  /* Custom animations */
  --animate-fade-in: fade-in 0.5s ease-out;
  --animate-fade-out: fade-out 0.5s ease-out;
  --animate-slide-in-up: slide-in-up 0.3s ease-out;
  --animate-slide-in-down: slide-in-down 0.3s ease-out;
  --animate-scale-in: scale-in 0.2s ease-out;
  --animate-spin-slow: spin 2s linear infinite;
  --animate-pulse-slow: pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite;
  --animate-bounce-slow: bounce 2s infinite;
  --animate-shake: shake 0.5s ease-in-out;
  
  /* Keyframes are still needed */
  --animate-enter: enter 0.3s ease-out;
  --animate-leave: leave 0.2s ease-in;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-in-up {
  from { transform: translateY(100%); }
  to { transform: translateY(0); }
}

@keyframes scale-in {
  from { transform: scale(0.9); opacity: 0; }
  to { transform: scale(1); opacity: 1; }
}

@theme Flags

You can use CSS-wide keywords as values:

@theme {
  /* Use initial to not extend the default */
  --color-gray-500: initial;  /* Removes the default gray-500 */
  
  /* Use inherit when needed */
  --color-inherit: inherit;
  
  /* Use unset to reset */
  --font-family: unset;
}

Inline Theme Values

Use --inline-* to generate values that don't create CSS variables:

@theme {
  --animate-bounce: bounce 1s infinite;
  --animate-spin: spin 1s linear infinite;
  
  /* These create variables but utilities also use them */
}

Migration from v3

Complete Breaking Changes Table

| Feature | v3 | v4 | Action Required | |---------|----|----|----| | Import | @tailwind base/components/utilities | @import "tailwindcss" | Replace all directives | | Config | tailwind.config.js | @theme in CSS | Rewrite to @theme | | Ring | ring (3px default) | ring-3 | Add -3 suffix | | Shadow | shadow | shadow-sm | Shift all shadows down | | Shadow | shadow-sm | shadow-xs | Shift down | | Shadow | shadow-md | shadow | Remove -md | | Shadow | shadow-lg | shadow-md | Remove -lg | | Shadow | shadow-xl | shadow-lg | Remove -xl | | Shadow | shadow-2xl | shadow-xl | Remove -2xl | | Outline | outline-none | outline-hidden | Rename utility | | Border | gray-200 default | currentColor | Add explicit colors | | Blur | blur | blur-sm | Add -sm suffix | | Blur | blur-sm | blur-xs | Shift down | | Blur | blur-md | blur | Remove -md | | Blur | blur-lg | blur-md | Remove -lg | | Blur | blur-xl | blur-lg | Remove -xl | | Opacity | bg-opacity-50 | bg-red-500/50 | Use / modifier | | Arbitrary | bg-[--var] | bg-(--var) | Change [] to () | | Grid | grid-cols-[a,b] | grid-cols-[a_b] | Use _ not , | | Important | !bg-red-500 | bg-red-500! | Move ! to end | | Theme fn | theme('colors.red') | var(--color-red-500) | Use CSS variables | | Dark mode | Config option | Automatic | Remove config | | Separator | _ in arbitrary | _ | Same, but fewer cases | | Preflight | Various resets | Updated | Check dialog/button |

Upgrade Tool

Run the official upgrade tool:

npx @tailwindcss/upgrade

This handles most migration automatically.

Manual Changes Needed

Rename shadow utilities:

<!-- Change these -->
<div class="shadow"></div>   <!-- now shadow-sm -->
<div class="shadow-sm"></div> <!-- now shadow-xs -->

Update ring utilities:

<!-- Change these -->
<input class="ring">        <!-- now ring-3 -->

Fix outline:

<!-- Change these -->
<input class="outline-none"> <!-- now outline-hidden -->

Update border colors:

<!-- Need to specify color now -->
<div class="border">         <!-- no longer gray-200 by default -->
<div class="border border-gray-200"> <!-- explicit -->

Space-between changes:

<!-- The selector changed -->
<div class="space-y-4">...   <!-- now uses :not(:last-child) -->

New Features in v4

Field Sizing

<textarea class="field-sizing-content" placeholder="Auto-grows"></textarea>

Container Queries

<div class="@container">
  <div class="@xs:bg-red-500 @lg:bg-blue-500">
    Responsive to container, not viewport
  </div>
</div>

3D Transforms

<div class="transform-style-3d perspective-1000 rotate-x-45">
  3D content
</div>

@starting-style

<div class="open:animate-fade-in" style="view-transition-name: modal">
  Modal content
</div>

Linear Gradients (Improved)

<div class="bg-linear-to-r from-red-500 via-orange-400 to-yellow-400">
  Gradient with stops
</div>

Gradient Variants

Variants now preserve gradient values properly:

<!-- Dark mode now preserves all gradient stops -->
<div class="bg-linear-to-r from-red-500 to-yellow-400 dark:from-blue-500 dark:to-teal-400">

To reset a gradient stop in a variant:

<div class="bg-linear-to-r from-red-500 via-orange-400 to-yellow-400 dark:via-none">

Preflight Changes

Default Placeholder Color

Now uses currentColor at 50% opacity instead of gray-400.

Button Cursor

Buttons now use cursor: default (browser default) instead of pointer.

Dialog Margins

Margins on <dialog> elements are now reset to 0.

Using with Vue, Svelte, CSS Modules

In v4, styles in separate files (Vue <style>, Svelte, CSS modules) don't see theme variables by default. Use @reference:

<template>
  <h1>Hello</h1>
</template>

<style>
@reference "../app.css";

h1 {
  @apply text-2xl font-bold text-red-500;
}
</style>

Common Issues and Solutions

Missing classes after build

Run npx @tailwindcss/upgrade to set up v4 correctly
Ensure CSS is processed by the v4 plugin

Dark mode not applying

Use automatic mode (no config needed in v4)
Add class="dark" to <html> for manual toggle

Custom utilities not working

Use @utility directive instead of @layer utilities
Ensure the CSS file with @theme definitions is imported

Performance issues

v4 is 10x faster with the Oxide engine
Ensure you're using the latest @tailwindcss/vite or @tailwindcss/postcss

Prefix changes

Prefixes now work like variants—always at the beginning:

<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">

Utility Classes Reference (v4)

Layout

Display: block, inline-block, flex, grid, inline-flex, inline-grid, hidden
Position: static, relative, absolute, fixed, sticky
Container: container (customize with @utility container)

Flexbox & Grid

Flex: flex-row, flex-col, flex-wrap, flex-1, flex-auto, flex-none
Justify: justify-start, justify-center, justify-between, justify-around, justify-end
Align: items-start, items-center, items-stretch, items-end
Gap: gap-4, gap-x-4, gap-y-4, gap-4
Grid: grid-cols-3, grid-rows-2, col-span-2, row-span-2

Sizing

Width/Height: w-full, w-auto, w-screen, h-full, h-screen
Max/Min: max-w-lg, max-w-screen-md, min-h-screen
Container queries: @container, @xs:, @sm:, @md:, @lg:, @xl:

Spacing

Margin: m-4, mx-4, my-4, mt-4, mr-4, mb-4, ml-4, -m-4
Padding: p-4, px-4, py-4, pt-4, pr-4, pb-4, pl-4

Typography

Size: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-4xl
Weight: font-thin, font-light, font-normal, font-medium, font-bold, font-black
Style: italic, not-italic, uppercase, lowercase, capitalize
Leading: leading-none, leading-tight, leading-normal, leading-relaxed, leading-loose
Tracking: tracking-tighter, tracking-tight, tracking-normal, tracking-wide

Colors

Background: bg-red-500, bg-[--custom-color], bg-(--variable)
Text: text-gray-700, text-transparent
Border: border, border-2, border-gray-200, border-t-2, border-b
Gradient: bg-linear-to-r, bg-radial-gradient, bg-conic-gradient

Visual Effects

Shadow: shadow-xs, shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl
Opacity: opacity-0 through opacity-100, opacity-50/
Blend: mix-blend-multiply, mix-blend-screen, mix-blend-overlay
Filter: blur, blur-sm, blur-xs, brightness-50, contrast-50, grayscale, sepia

Transitions & Animation

Transition: transition, transition-all, transition-colors, transition-opacity, transition-transform
Duration: duration-75, duration-100, duration-200, duration-300, duration-500
Easing: ease-linear, ease-in, ease-out, ease-in-out
Animation: animate-spin, animate-pulse, animate-bounce, animate-none

Transform

Scale: scale-0, scale-50, scale-75, scale-90, scale-95, scale-100, scale-105, scale-110, scale-125, scale-150
Rotate: rotate-0, rotate-1, rotate-2, rotate-12, rotate-45, rotate-90, rotate-180
Translate: translate-x-0, translate-x-4, translate-y-4, translate-x-1/2
Perspective: perspective-0, perspective-1000, perspective-3d

Interactivity

Cursor: cursor-pointer, cursor-not-allowed, cursor-text, cursor-move
Pointer: pointer-events-none, pointer-events-auto
Select: select-none, select-text, select-all, select-auto
Resize: resize, resize-none, resize-y, resize-x
Field sizing: field-sizing-content, field-sizing-fixed

State Variants

Interaction: hover:, focus:, active:, visited:, focus-within:, focus-visible:
Disabled: disabled:, disabled:opacity-50, disabled:cursor-not-allowed
Group: group, group-hover:, group-focus:, peer, peer-hover:
Motion: motion-reduce:, motion-safe:
Media: dark:, @media (prefers-reduced-motion):
Structural: first:, last:, odd:, even:, first-child:, last-child:, only:, empty:

Best Practices

Do:

Use @theme for all custom design tokens
Use @utility for reusable patterns
Leverage the CSS variables (var(--color-*)) in JavaScript
Let dark mode be automatic
Use @config only for legacy projects

Don't:

Create a tailwind.config.js for new projects
Use Sass/Less/Stylus—they don't work with v4
Use the old theme() function—use CSS variables instead
Use brackets for CSS variables—use parentheses: bg-(--var)

Migration Checklist

[ ] Run npx @tailwindcss/upgrade
[ ] Replace @tailwind directives with @import "tailwindcss"
[ ] Convert tailwind.config.js to @theme in CSS
[ ] Replace ring with ring-3
[ ] Replace shadow with shadow-sm, shadow-sm with shadow-xs
[ ] Replace outline-none with outline-hidden
[ ] Add explicit border colors where needed
[ ] Update variant stacking order
[ ] Update arbitrary value syntax ([...] → (...))
[ ] Update grid syntax (, → _)
[ ] Move ! to end of utility for important
[ ] Test dark mode
[ ] Verify custom utilities work with @utility
[ ] Update Vue/Svelte components with @reference if needed

Agent Skills: Node.js 18+ required for Oxide engine

Install this agent skill to your local

Skill Files

Overview

The Oxide Engine (Performance)

Why It's Faster

Requirements

Installation

Vite (Recommended)

PostCSS

CLI

Basic Setup

The CSS File

Theme Configuration with @theme

Using Theme Values

Dark Mode

Custom Utilities with @utility

Custom Variants with @variant

Built-in Variants

Variant Stacking Order

Arbitrary Values

CSS Variables (New Syntax)

Grid Values

The Important Modifier

Automatic Content Detection

Backward Compatibility with @config

The @theme Directive (Complete Reference)

Color System

OKLCH Color Syntax

Spacing Scale

Breakpoints

Shadows

Typography

Animations

@theme Flags

Inline Theme Values

Migration from v3

Complete Breaking Changes Table

Upgrade Tool

Manual Changes Needed

New Features in v4

Field Sizing

Container Queries

3D Transforms

@starting-style

Linear Gradients (Improved)

Gradient Variants

Preflight Changes

Default Placeholder Color

Button Cursor

Dialog Margins

Using with Vue, Svelte, CSS Modules

Common Issues and Solutions

Missing classes after build

Dark mode not applying

Custom utilities not working

Performance issues

Prefix changes

Utility Classes Reference (v4)

Layout

Flexbox & Grid

Sizing

Spacing

Typography

Colors

Visual Effects

Transitions & Animation

Transform

Interactivity

State Variants

Best Practices

Do:

Don't:

Migration Checklist