Tailwind CSS v4: Guía Completa y Migración desde v3 (2026)

Tailwind CSS v4 no es una actualización más. Es una reescritura completa con un nuevo motor, nueva sintaxis de configuración y un cambio de filosofía: Tailwind se convierte en un motor CSS nativo, sin Node.js en runtime.

Si llevas proyectos con v3 o estás empezando uno nuevo, esto te afecta. Vamos al grano.

¿Qué cambia de verdad en Tailwind v4?

1. El motor Oxide — builds 100x más rápidos

El mayor cambio técnico. El nuevo motor está escrito en Rust usando Lightning CSS por debajo, en vez de PostCSS.

Benchmarks reales:

Proyecto	v3 build	v4 build
Proyecto mediano (500 clases)	1.2s	50ms
Proyecto grande (3000+ clases)	4.8s	120ms
HMR (cambio en desarrollo)	200ms	5ms

En dev, el cambio es brutal. HMR casi instantáneo.

2. Adiós a tailwind.config.js (en proyectos nuevos)

En v3, toda la configuración iba en tailwind.config.js:

// v3 — tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#6366f1',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      }
    }
  }
}

En v4, la configuración va en tu CSS con @theme:

/* v4 — styles.css */
@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --font-family-sans: 'Inter', sans-serif;
  --spacing-128: 32rem;
}

Ventaja: tus tokens de diseño son variables CSS nativas. Puedes usarlos en cualquier parte, no solo en clases de Tailwind.

3. Variables CSS de primera clase

Todo en v4 genera variables CSS automáticamente. El color brand que defines en @theme está disponible como:

• Clase Tailwind: bg-brand, text-brand, border-brand
• Variable CSS: var(--color-brand) en cualquier style inline o CSS custom

<!-- Usando la clase -->
<button class="bg-brand text-white">Botón</button>

<!-- Usando la variable directamente -->
<div style="border-left: 3px solid var(--color-brand)">...</div>

4. Clases que cambian o desaparecen

Las diferencias más importantes entre v3 y v4:

v3	v4	Nota
shadow-sm	shadow-xs	Renombrado
shadow	shadow-sm	Renombrado
rounded	rounded-sm	Renombrado
blur	blur-sm	Renombrado
ring	ring-3	Ahora explícito
basis-1/2	igual	Sin cambio
bg-opacity-50	bg-black/50	Nueva sintaxis
text-opacity-75	text-black/75	Nueva sintaxis

La regla de los *-sm / *-xs: en v4, la escala de tamaños se ajusta. Lo que antes era el valor “default” (sin sufijo) ahora tiene nombre explícito.

5. Variantes de nueva sintaxis

<!-- v3 -->
<div class="hover:bg-blue-500 focus:ring-2 dark:bg-gray-900">

<!-- v4 — igual, pero con nuevas variantes añadidas -->
<div class="hover:bg-blue-500 starting:opacity-0 in-[.modal]:block **:text-sm">

Nuevas variantes en v4:

• starting: — para animaciones de entrada (antes necesitabas JS)
• in-[.selector]: — aplica estilo cuando el elemento está dentro de ese selector
• **: — aplica a todos los descendientes (como * pero recursivo)
• not-[.active]: — cuando NO tiene esa clase

Cómo instalar Tailwind v4

En proyecto nuevo con Vite

npm create vite@latest mi-proyecto -- --template vanilla
cd mi-proyecto
npm install -D tailwindcss @tailwindcss/vite

En vite.config.js:

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

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

En tu src/style.css:

@import "tailwindcss";

/* Tu configuración aquí */
@theme {
  --color-brand: #6366f1;
}

Sin tailwind.config.js. Sin content: []. Sin PostCSS. Tailwind v4 detecta las clases automáticamente.

En proyecto Next.js

npm install -D tailwindcss @tailwindcss/postcss

En postcss.config.mjs:

const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
export default config;

En proyecto Astro

npx astro add tailwind
# Selecciona v4 cuando pregunte

O manualmente:

npm install -D @tailwindcss/vite

Y en astro.config.mjs:

import tailwind from "@tailwindcss/vite";

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

Cómo migrar desde v3: paso a paso

Opción 1: Migración automática (recomendada)

npx @tailwindcss/upgrade

Este comando:

1. Actualiza las dependencias en package.json
2. Migra tailwind.config.js a @theme en tu CSS
3. Renombra las clases que cambiaron (shadow → shadow-sm, etc.)
4. Convierte bg-opacity-50 a bg-black/50, etc.

Cubre ~80-90% de los casos. Revisa el diff después.

Opción 2: Migración manual

Paso 1 — Actualizar dependencias:

npm install -D tailwindcss@next @tailwindcss/vite
npm uninstall autoprefixer

Paso 2 — Borrar tailwind.config.js y mover la config a CSS:

/* Antes (tailwind.config.js) */
/* theme.extend.colors.brand = '#6366f1' */

/* Ahora en globals.css */
@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --color-brand-dark: #4f46e5;
}

Paso 3 — Actualizar vite.config.js o postcss.config.js:

Elimina los plugins de PostCSS para Tailwind y usa el plugin de Vite en su lugar.

Paso 4 — Renombrar clases con búsqueda/reemplazo:

Las más comunes:

shadow → shadow-sm
shadow-sm → shadow-xs
rounded → rounded-sm
blur → blur-sm
ring → ring-3

Usa este regex en VS Code para encontrarlos: \b(shadow|rounded|blur)\b(?!-)

Paso 5 — Migrar opacidades:

bg-{color}-{shade}/opacity → bg-{color}-{shade}/{opacity}
bg-black bg-opacity-50 → bg-black/50
text-white text-opacity-75 → text-white/75

Problemas comunes en la migración

Error: Cannot find module 'tailwindcss/plugin'

En v4 los plugins se importan diferente:

// v3
const plugin = require('tailwindcss/plugin')

// v4
import plugin from 'tailwindcss/plugin'
// o en CSS:
// @plugin "./mi-plugin.js"

Las clases de componentes de terceros se rompen

Si usas Flowbite, DaisyUI, Shadcn, etc., pueden necesitar actualización. Comprueba la compatibilidad con v4 en sus docs.

El dark mode no funciona igual

En v3 podías usar darkMode: 'class' en config. En v4:

@import "tailwindcss";

/* Activar dark mode por clase */
@variant dark (&:where(.dark, .dark *));

Las funcionalidades que más me gustan de v4

@utility — crea clases personalizadas reales

@utility container {
  max-width: 1280px;
  margin-inline: auto;
  padding-inline: 1.5rem;
}

Ahora container es una clase de Tailwind real, con variantes responsivas: sm:container, md:container…

starting: para animaciones sin JavaScript

<dialog class="
  opacity-0 scale-95
  starting:opacity-0 starting:scale-95
  open:opacity-100 open:scale-100
  transition-all duration-200
">

Animas el estado inicial de un dialog o popover sin escribir ni una línea de JS.

Gradientes dinámicos con variables

<div class="bg-gradient-to-r from-[var(--color-brand)] to-purple-600">
  Gradiente dinámico
</div>

¿Vale la pena migrar ahora?

Migra ahora si:

• Es un proyecto nuevo — usa v4 directamente
• Tu build tarda más de 2s — la ganancia de rendimiento es enorme
• Quieres CSS moderno sin PostCSS
• Usas muchas animaciones — starting: y in-out: son un game changer

Espera si:

• Usas muchos plugins de terceros que aún no son compatibles con v4
• Tu proyecto tiene cientos de archivos y no puedes dedicar tiempo a revisar el diff
• Dependes de Tailwind UI (la versión v4 está en roadmap)

Conclusión: Para proyectos nuevos, v4 es la elección obvia. Para migrar proyectos existentes, usa npx @tailwindcss/upgrade y reserva 2-4 horas para revisar los casos que no migra automáticamente.

La ganancia de rendimiento y la config en CSS nativo hacen que valga la pena.