claude-mods/skills/tailwind-ops/references/v4-migration.md

Tailwind CSS v4 Migration Guide

Comprehensive guide for migrating from Tailwind CSS v3 to v4. Tailwind v4 is a ground-up rewrite with CSS-first configuration, new engine, and native support for modern CSS features.

What Changed: Overview

Architecture Shift

Tailwind v4 replaces JavaScript-based configuration with CSS-first configuration. The tailwind.config.js file is no longer required (but supported via compatibility layer).

Concept	v3	v4
Config	tailwind.config.js (JS)	@theme {} block in CSS
Entry point	@tailwind base/components/utilities	@import "tailwindcss"
Plugins	JS plugin() API	@plugin "package" in CSS
PostCSS	tailwindcss package	@tailwindcss/postcss
Vite	PostCSS plugin	@tailwindcss/vite (faster)
Content detection	content: [...] in config	Automatic (scans project)
Theme values	JS objects	CSS custom properties
Directives	@tailwind, @screen, @variants	@import, @theme, @variant

@theme Directive

The @theme directive replaces theme.extend in tailwind.config.js. Values defined here become both CSS custom properties and Tailwind utilities.

Basic Usage

/* v4: CSS-first configuration */
@import "tailwindcss";

@theme {
  /* Colors: creates bg-brand, text-brand, border-brand, etc. */
  --color-brand: #3b82f6;
  --color-brand-light: #60a5fa;
  --color-brand-dark: #1d4ed8;

  /* Semantic colors */
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-danger: #ef4444;

  /* Typography */
  --font-display: "Inter", "system-ui", sans-serif;
  --font-body: "Source Sans Pro", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;
  --spacing-128: 32rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Animations */
  --animate-fade-in: fade-in 0.3s ease-out;
  --animate-slide-up: slide-up 0.4s ease-out;
}

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

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

Overriding vs Extending

/* EXTENDING: add to existing scale (use --color-* namespace) */
@theme {
  --color-brand: #3b82f6;
  /* All default colors (slate, gray, red, etc.) still available */
}

/* OVERRIDING: replace entire namespace */
@theme {
  --color-*: initial;  /* Clear all default colors */
  --color-primary: #3b82f6;
  --color-secondary: #6b7280;
  --color-accent: #f59e0b;
  /* Only these 3 colors available now */
}

Accessing Theme Values in CSS

/* Theme values are CSS custom properties, usable anywhere */
.custom-element {
  color: var(--color-brand);
  font-family: var(--font-display);
  padding: var(--spacing-18);
}

@config: Compatibility Layer

For projects with existing tailwind.config.js files, v4 provides a compatibility layer.

@import "tailwindcss";

/* Load existing JS config */
@config "./tailwind.config.js";

/* Can combine with @theme (theme overrides config) */
@theme {
  --color-brand: #3b82f6;
}

Migration path: Start with @config, then gradually move values into @theme, then remove the JS config.

@plugin Directive

Plugins are now imported directly in CSS.

@import "tailwindcss";

/* v4: Import plugins in CSS */
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/container-queries";

/* Local plugin */
@plugin "./plugins/my-custom-plugin.js";

Plugin API Changes

// v4 plugin API (similar to v3 but with changes)
export default function ({ addUtilities, addComponents, matchUtilities, theme }) {
  addUtilities({
    '.content-auto': { 'content-visibility': 'auto' },
    '.content-hidden': { 'content-visibility': 'hidden' },
  })
}

New Default Scales

Spacing

v4 uses a simplified spacing scale based on multiples of 0.25rem (4px). The existing numeric scale (0-96) remains, but new scales are rationalized.

Colors

v4 retains the same color palette names but adds:

• OKLCH color support for more perceptually uniform colors
• Automatic color opacity via bg-blue-500/75 (unchanged syntax, improved output)

Typography

@theme {
  /* v4 uses --text-* for font-size + line-height combos */
  --text-base: 1rem;           /* 16px */
  --text-base--line-height: 1.5rem;  /* 24px */

  /* Custom text scale */
  --text-hero: 4rem;
  --text-hero--line-height: 1.1;
  --text-hero--letter-spacing: -0.02em;
  --text-hero--font-weight: 800;
}

Removed Utilities and Replacements

v3 Utility	Status in v4	Replacement
bg-opacity-*	Removed	bg-blue-500/75 (opacity modifier)
text-opacity-*	Removed	text-blue-500/75
border-opacity-*	Removed	border-blue-500/75
divide-opacity-*	Removed	divide-blue-500/75
ring-opacity-*	Removed	ring-blue-500/75
placeholder-opacity-*	Removed	placeholder:text-gray-400/75
flex-shrink	Renamed	shrink (already available in v3)
flex-grow	Renamed	grow (already available in v3)
overflow-ellipsis	Renamed	text-ellipsis
decoration-slice	Renamed	box-decoration-slice
decoration-clone	Renamed	box-decoration-clone

Opacity Modifier Migration

<!-- v3: Separate opacity utilities -->
<div class="bg-blue-500 bg-opacity-75">

<!-- v4: Opacity modifier on the color -->
<div class="bg-blue-500/75">

<!-- Both opacity and color in one -->
<div class="bg-blue-500/50 text-white/90 border-gray-300/30">

Variant Changes

New Variants

Variant	Usage	Description
@sm: / @md: / @lg:	@md:flex	Container query breakpoints
@min-*: / @max-*:	@min-[400px]:flex	Arbitrary container queries
starting:	starting:opacity-0	@starting-style for entry animations
not-*:	not-last:mb-4	Negation pseudo-class
in-*:	in-[.dark]:text-white	Match within ancestor
has-*:	has-[input:focus]:ring-2	:has() pseudo-class
nth-*:	nth-3:bg-gray-100	:nth-child()
nth-last-*:	nth-last-2:mb-0	:nth-last-child()

Removed / Changed Variants

v3	v4	Notes
@screen sm	@sm or @media (width >= 640px)	@screen directive removed
@variants hover, focus	Removed	Not needed, variants auto-generated

Container Query Variants

<!-- v4: Native container queries -->
<div class="@container">
  <div class="flex flex-col @sm:flex-row @md:grid @md:grid-cols-2 @lg:grid-cols-3 gap-4">
    <div>Card</div>
  </div>
</div>

<!-- Named containers -->
<div class="@container/main">
  <div class="@sm/main:flex">Responds to main container</div>
</div>

<!-- Arbitrary container query values -->
<div class="@container">
  <div class="@min-[400px]:flex @max-[800px]:flex-col">
    Custom breakpoints
  </div>
</div>

@starting-style: Entry Animations

v4 supports @starting-style for CSS-native entry animations, eliminating the need for JavaScript animation libraries in many cases.

/* Dialog with entry animation */
dialog[open] {
  opacity: 1;
  transform: scale(1);
  transition: opacity 0.3s ease, transform 0.3s ease,
              display 0.3s ease allow-discrete,
              overlay 0.3s ease allow-discrete;

  @starting-style {
    opacity: 0;
    transform: scale(0.95);
  }
}

/* Popover entry */
[popover]:popover-open {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 0.2s, transform 0.2s,
              display 0.2s allow-discrete,
              overlay 0.2s allow-discrete;

  @starting-style {
    opacity: 0;
    transform: translateY(-8px);
  }
}

Using with Tailwind v4 Classes

<!-- The starting: variant maps to @starting-style -->
<dialog class="opacity-100 scale-100 transition-all duration-300
               starting:opacity-0 starting:scale-95
               backdrop:bg-black/50">
  <div class="p-6">Dialog content</div>
</dialog>

Anchor Positioning

v4 supports CSS Anchor Positioning for tooltips, popovers, and dropdowns without JavaScript positioning libraries.

/* Anchor a tooltip to a button */
.trigger {
  anchor-name: --my-trigger;
}

.tooltip {
  position: absolute;
  position-anchor: --my-trigger;
  top: anchor(bottom);
  left: anchor(center);
  transform: translateX(-50%);
}

PostCSS Changes

v3 PostCSS Setup

// postcss.config.js (v3)
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

v4 PostCSS Setup

// postcss.config.js (v4)
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    // autoprefixer no longer needed - handled by Tailwind v4
  },
}

Package Changes

# Remove v3 packages
npm uninstall tailwindcss postcss autoprefixer

# Install v4 packages
npm install @tailwindcss/postcss

Vite Plugin

v4 provides a dedicated Vite plugin that is significantly faster than the PostCSS plugin.

npm install @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite'

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

/* app.css - no postcss config needed */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
}

CSS Entry Point Changes

v3 Entry Point

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Custom styles */
@layer base { ... }
@layer components { ... }
@layer utilities { ... }

v4 Entry Point

/* v4 */
@import "tailwindcss";

/* Layers still work the same way */
@layer base {
  body {
    font-family: var(--font-body);
  }
}

@layer components {
  .card {
    @apply rounded-lg bg-white p-6 shadow-md dark:bg-gray-800;
  }
}

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

Migration Steps

1. Automated Migration Tool

# Run the official migration tool
npx @tailwindcss/upgrade

This tool will:

• Update package.json dependencies
• Convert tailwind.config.js to @theme block (where possible)
• Update CSS entry points (@tailwind to @import)
• Replace removed utilities with modern equivalents
• Update PostCSS config

2. Manual Migration Checklist

[ ] Update packages: tailwindcss -> @tailwindcss/postcss (or @tailwindcss/vite)
[ ] Remove autoprefixer (built into v4)
[ ] Replace @tailwind directives with @import "tailwindcss"
[ ] Move tailwind.config.js theme values to @theme block
    OR use @config "./tailwind.config.js" as compatibility layer
[ ] Update opacity utilities: bg-opacity-50 -> bg-blue-500/50
[ ] Update deprecated utility names (flex-shrink -> shrink, etc.)
[ ] Replace @screen with @media or container queries
[ ] Update plugins: require() -> @plugin directive
[ ] Test dark mode (default is now media-based)
[ ] Verify content detection (automatic in v4, no content config needed)
[ ] Remove postcss.config.js if using @tailwindcss/vite

3. Testing Checklist

[ ] All pages render correctly
[ ] Dark mode toggle works
[ ] Responsive breakpoints behave correctly
[ ] Custom colors / spacing / typography render
[ ] Animations and transitions work
[ ] Form styles render (if using @tailwindcss/forms)
[ ] Prose/typography content renders (if using @tailwindcss/typography)
[ ] No missing classes in production build
[ ] No console errors related to CSS
[ ] Accessibility: focus rings, sr-only text still work

Breaking Changes by Category

Configuration

Change	Impact	Migration
tailwind.config.js no longer auto-detected	Config not loaded	Add @config "./tailwind.config.js" or migrate to @theme
content paths removed	Not needed	v4 automatically detects template files
safelist moved	Classes not preserved	Use @source directive or CSS comments
prefix option	Not directly supported	Use CSS layers or namespacing
important option	Changed behavior	Use @layer strategy instead

Utilities

Change	Impact	Migration
bg-opacity-* removed	Transparent backgrounds break	Use / opacity modifier: bg-blue-500/75
flex-shrink-* renamed	Warning/removal	Use shrink-*
flex-grow-* renamed	Warning/removal	Use grow-*
Default border color	Was gray-200, now currentColor	Explicitly set border-gray-200
Default ring width	Was 3px, now 1px	Explicitly set ring-3
Shadow color handling	Different cascade behavior	Test shadow utilities

Variants

Change	Impact	Migration
@screen removed	Compilation error	Use @media (width >= Xpx)
@variants removed	Compilation error	Remove directive (auto-generated)
@responsive removed	Compilation error	Remove directive (auto-generated)
Dark mode default	Was opt-in, now media by default	Set @custom-variant dark if using class strategy

Plugins

Change	Impact	Migration
require() not supported in CSS	Plugin not loaded	Use @plugin "package"
Some plugin APIs changed	Plugin errors	Check plugin compatibility with v4
addBase() behavior	Different layer ordering	Test base styles
theme() function	Returns CSS custom properties	Update if doing string comparison