Tailwind CSS v4 en 2026: La guia completa con ejemplos practicos

Tailwind CSS v4 representa la mayor renovacion que el framework ha experimentado desde su creacion. Lanzado a principios de 2025 y completamente maduro en 2026, v4 introduce un sistema de configuracion CSS-first, un motor completamente reescrito llamado Oxide, mejoras dramaticas de rendimiento y un conjunto modernizado de utilities. Si ha estado usando Tailwind v3, actualizar a v4 cambia la forma en que piensa sobre la configuracion y los temas. Esta guia le lleva a traves de todo lo que necesita saber.

Que cambio en Tailwind CSS v4

Tailwind v4 no es solo una actualizacion incremental. Es un replanteamiento fundamental de como funciona el framework internamente. Estos son los cambios principales:

• Configuracion CSS-first: No mas tailwind.config.js. Los valores del tema, utilities personalizados y variantes se definen directamente en CSS usando @theme y otras directivas.
• Motor Oxide: Un nuevo motor de alto rendimiento escrito en Rust que maneja el parsing, la compilacion y la deteccion de clases ordenes de magnitud mas rapido que v3.
• Caracteristicas CSS modernas: Soporte incorporado para @layer, cascade layers, color-mix(), oklch(), container queries y @starting-style para animaciones.
• Instalacion simplificada: Solo un paquete sin configuracion requerida para comenzar.
• Nuevo tema por defecto: Una paleta de colores ampliada usando OKLCH, escala de espaciado actualizada y valores tipograficos por defecto mejorados.

Primeros pasos con Tailwind CSS v4

Instalacion

Configurar Tailwind v4 es mas simple que nunca. No se necesita un plugin PostCSS separado ni un archivo de configuracion.

# Instalar Tailwind CSS v4
npm install tailwindcss @tailwindcss/vite

# O con la CLI
npm install tailwindcss @tailwindcss/cli

Para un proyecto basado en Vite, agregue el plugin a su configuracion de Vite:

// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

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

Luego importe Tailwind en su archivo CSS principal:

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

Esa es toda la configuracion. Sin tailwind.config.js, sin postcss.config.js, sin rutas de contenido que configurar. El motor Oxide detecta automaticamente sus archivos fuente y los escanea en busca de nombres de clases.

Uso de la CLI

Si no esta usando Vite, la CLI funciona igual de bien:

npx @tailwindcss/cli -i app.css -o output.css --watch

Configuracion CSS-first con @theme

El cambio conceptual mas grande en v4 es que toda la personalizacion ocurre en CSS, no en JavaScript. La directiva @theme reemplaza el antiguo objeto de tema de tailwind.config.js.

Definir colores personalizados

@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
  --color-brand-light: #818cf8;
  --color-brand-dark: #3730a3;
  --color-surface: #f8fafc;
  --color-surface-dark: #1e293b;
}

Estas variables CSS se convierten automaticamente en utilities de Tailwind disponibles:

<div class="bg-brand text-white">
  <h1 class="text-brand-light">Hello, Tailwind v4</h1>
</div>

Espaciado y dimensionamiento personalizado

@theme {
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
  --width-content: 72rem;
  --width-sidebar: 20rem;
}

Fuentes personalizadas

@theme {
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;
  --font-display: "Cal Sans", "Inter", sans-serif;
}

Sobreescribir vs extender el tema por defecto

Por defecto, @theme extiende el tema incorporado. Si desea reemplazar completamente un namespace, use el reinicio con comodin --*:

@theme {
  /* Eliminar todos los colores por defecto, usar solo estos */
  --color-*: initial;
  --color-white: #ffffff;
  --color-black: #000000;
  --color-primary: #2563eb;
  --color-secondary: #7c3aed;
  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-900: #111827;
}

El motor Oxide

Internamente, Tailwind v4 usa un nuevo motor llamado Oxide, escrito en Rust y compilado a codigo nativo. La diferencia de rendimiento es sustancial.

Mejoras de rendimiento

El motor Oxide ofrece mejoras de velocidad dramaticas en comparacion con el motor basado en JavaScript de v3:

• Los tiempos de compilacion inicial son tipicamente 3-10x mas rapidos, dependiendo del tamano del proyecto.
• Las recompilaciones incrementales durante el desarrollo son casi instantaneas, a menudo por debajo de 5 milisegundos.
• El uso de memoria es significativamente menor ya que Rust gestiona la memoria sin un recolector de basura.

Para proyectos monorepo grandes con cientos de miles de clases, la diferencia es especialmente notable. Donde v3 podia tardar varios segundos para una recompilacion completa, v4 completa en cientos de milisegundos.

Deteccion automatica de contenido

Una de las mejores mejoras de calidad de vida es que ya no necesita especificar rutas de contenido. El motor Oxide detecta y escanea automaticamente los archivos de su proyecto. Usa heuristicas para encontrar archivos de plantilla, componentes JSX/TSX y otras fuentes de nombres de clases.

Si necesita incluir o excluir archivos explicitamente, puede usar la directiva @source:

@import "tailwindcss";

/* Agregar rutas fuente adicionales */
@source "../shared-components/**/*.tsx";

/* Excluir una ruta */
@source not "../node_modules";

Clases de utility nuevas y actualizadas

Tailwind v4 introduce varios nuevos utilities y refina los existentes para aprovechar las caracteristicas CSS modernas.

Container Queries

Los container queries le permiten estilizar elementos basandose en el tamano de su contenedor padre en lugar del viewport. Tailwind v4 tiene soporte de primera clase.

<div class="@container">
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
    <div class="p-4 bg-white rounded-lg">Card 1</div>
    <div class="p-4 bg-white rounded-lg">Card 2</div>
    <div class="p-4 bg-white rounded-lg">Card 3</div>
  </div>
</div>

La clase @container establece un contexto de contencion, y los prefijos @md:, @lg: aplican estilos basados en el ancho del contenedor.

Funciones de color modernas

Tailwind v4 usa colores OKLCH por defecto, lo que proporciona un espacio de color perceptualmente uniforme. Tambien puede usar color-mix() para manipulacion dinamica de colores:

@theme {
  --color-primary: oklch(0.6 0.25 265);
  --color-primary-hover: oklch(0.5 0.25 265);
}

<button class="bg-primary hover:bg-primary-hover text-white px-4 py-2 rounded">
  Haga clic
</button>

Transformaciones 3D

<div class="perspective-500">
  <div class="rotate-y-12 hover:rotate-y-0 transition-transform duration-300">
    <img src="/card.jpg" alt="Tarjeta 3D" class="rounded-xl shadow-lg" />
  </div>
</div>

Nuevos utilities de gradiente

V4 extiende el soporte de gradientes con caracteristicas adicionales:

<!-- Gradiente con interpolacion en OKLCH para transiciones mas suaves -->
<div class="bg-linear-to-r from-blue-500 to-purple-500 bg-interpolate-oklch">
  Gradiente suave
</div>

<!-- Gradiente conico -->
<div class="bg-conic from-red-500 via-yellow-500 to-green-500">
  Rueda de colores
</div>

La variante not-

La variante not- invierte cualquier otra variante, impulsada por CSS :not():

<div class="opacity-50 not-hover:opacity-100">
  Se desvanece al pasar el cursor en lugar de aparecer
</div>

<input class="border-gray-300 not-focus:border-transparent" />

Starting Style para animaciones

La variante starting le permite definir estilos para la regla @starting-style, que habilita animaciones de entrada en elementos que aparecen en el DOM:

<dialog class="opacity-0 starting:opacity-0 open:opacity-100 transition-opacity">
  <p>Este dialogo se desvanece al abrirse</p>
</dialog>

Diseno responsive en v4

El diseno responsive funciona de la misma manera conceptualmente, con la sintaxis familiar de prefijo de breakpoint. Sin embargo, v4 usa caracteristicas CSS modernas internamente.

Breakpoints por defecto

Los breakpoints por defecto siguen siendo practicos:

Prefijo	Ancho minimo	Uso comun
sm	640px	Telefonos grandes, horizontal
md	768px	Tablets
lg	1024px	Laptops pequenas
xl	1280px	Escritorios
2xl	1536px	Pantallas grandes

Breakpoints personalizados

@theme {
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

<div class="grid grid-cols-1 xs:grid-cols-2 md:grid-cols-3 3xl:grid-cols-4">
  <!-- Grid responsive -->
</div>

Ejemplo de layout responsive

<header class="flex flex-col sm:flex-row items-center justify-between p-4 lg:px-8">
  <a href="/" class="text-xl font-bold">Brand</a>
  <nav class="hidden md:flex gap-6 text-sm font-medium">
    <a href="/features" class="hover:text-brand">Caracteristicas</a>
    <a href="/pricing" class="hover:text-brand">Precios</a>
    <a href="/docs" class="hover:text-brand">Documentacion</a>
  </nav>
  <button class="md:hidden p-2" aria-label="Menu">
    <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
    </svg>
  </button>
</header>

Dark Mode

Tailwind v4 continua soportando dark mode con la variante dark:. Por defecto, usa la media query prefers-color-scheme, pero puede cambiar a conmutacion basada en clases o selectores.

Dark Mode basico

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100 min-h-screen">
  <h1 class="text-2xl font-bold">Bienvenido</h1>
  <p class="text-gray-600 dark:text-gray-400">Esto se adapta al tema de su sistema.</p>
</div>

Dark Mode basado en clases

Para alternar el dark mode con JavaScript en lugar de depender de la configuracion del sistema:

@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

Ahora el dark mode se activa cuando un elemento padre tiene la clase dark:

<html class="dark">
  <body class="bg-white dark:bg-gray-950">
    <!-- Dark mode activo -->
  </body>
</html>

// Alternar dark mode con JavaScript
function toggleDarkMode() {
  document.documentElement.classList.toggle('dark');
}

Construir un componente con conciencia de tema

<div class="rounded-xl border border-gray-200 dark:border-gray-800
            bg-white dark:bg-gray-900
            shadow-sm dark:shadow-gray-950/50
            p-6">
  <h3 class="text-lg font-semibold text-gray-900 dark:text-white">
    Configuracion
  </h3>
  <p class="mt-2 text-sm text-gray-500 dark:text-gray-400">
    Administre las preferencias de su cuenta.
  </p>
  <button class="mt-4 px-4 py-2 rounded-lg
                 bg-brand text-white
                 hover:bg-brand-dark
                 focus:outline-none focus:ring-2 focus:ring-brand/50">
    Guardar cambios
  </button>
</div>

Utilities de animacion

Tailwind v4 expande considerablemente el soporte de animaciones, facilitando la creacion de interacciones pulidas sin CSS personalizado.

Utilities de transicion

<!-- Efecto hover suave -->
<button class="bg-blue-600 hover:bg-blue-700
               transform hover:scale-105
               transition-all duration-200 ease-out
               text-white px-6 py-3 rounded-lg">
  Pase el cursor
</button>

<!-- Transicion de propiedades especificas -->
<div class="transition-colors duration-300 bg-gray-100 hover:bg-blue-100">
  Solo transicion de color
</div>

Animaciones incorporadas

<!-- Animacion de giro para indicadores de carga -->
<svg class="animate-spin h-5 w-5 text-white" viewBox="0 0 24 24">
  <!-- SVG del spinner -->
</svg>

<!-- Animacion de pulso -->
<div class="animate-pulse bg-gray-200 rounded h-4 w-3/4"></div>

<!-- Rebote -->
<div class="animate-bounce">Desplacese hacia abajo</div>

Animaciones personalizadas con @theme

@theme {
  --animate-slide-in: slide-in 0.3s ease-out;
  --animate-fade-up: fade-up 0.5s ease-out;
}

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

@keyframes fade-up {
  from {
    opacity: 0;
    transform: translateY(1rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

<div class="animate-slide-in">Se desliza desde la izquierda</div>
<div class="animate-fade-up">Aparece hacia arriba</div>

Migracion de Tailwind v3 a v4

La migracion de v3 a v4 requiere algo de esfuerzo, pero el equipo de Tailwind proporciona una herramienta codemod que maneja la mayoria de los cambios automaticamente.

Ejecutar la herramienta de actualizacion

npx @tailwindcss/upgrade

Esta herramienta escaneara su proyecto y convertira automaticamente la mayoria de los patrones de v3 a equivalentes de v4. Maneja el renombramiento de utilities, la migracion de configuracion y la actualizacion de imports.

Cambios clave de migracion

v3	v4	Notas
tailwind.config.js	@theme en CSS	La configuracion se mueve a CSS
@tailwind base/components/utilities	@import "tailwindcss"	Import unico
bg-opacity-50	bg-black/50	Sintaxis de modificador de opacidad
text-opacity-75	text-white/75	Sintaxis de modificador de opacidad
decoration-clone	box-decoration-clone	Renombrado
flex-shrink-0	shrink-0	Simplificado (ya funcionaba en v3)
flex-grow	grow	Simplificado
overflow-clip	overflow-clip	Igual
Rutas content en config	Deteccion automatica	Sin configuracion necesaria
darkMode: 'class' en config	@variant dark (...) en CSS	Basado en CSS

Pasos manuales

Despues de ejecutar la herramienta de actualizacion, revise estas areas manualmente:

1. Plugins personalizados: Los plugins JavaScript de v3 necesitan ser reescritos como CSS usando las directivas @utility y @variant.
2. Valores de tema personalizados: Muevalos de tailwind.config.js a bloques @theme en CSS.
3. Plugins de terceros: Verifique que hayan sido actualizados para compatibilidad con v4.

Convertir un plugin de v3 a v4

Plugin v3 (JavaScript):

// v3: plugin de tailwind.config.js
const plugin = require('tailwindcss/plugin');

module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      addUtilities({
        '.text-balance': {
          'text-wrap': 'balance',
        },
      });
    }),
  ],
};

Equivalente v4 (CSS):

/* v4: definido directamente en CSS */
@utility text-balance {
  text-wrap: balance;
}

Convertir una variante personalizada de v3

v3 (JavaScript):

// v3
plugin(function({ addVariant }) {
  addVariant('hocus', ['&:hover', '&:focus']);
});

v4 (CSS):

/* v4 */
@variant hocus (&:hover, &:focus);

Construir un componente completo

Pongamos todo junto y construyamos un componente de tarjeta de precios que demuestra las caracteristicas de v4:

<div class="@container max-w-sm mx-auto">
  <div class="rounded-2xl border border-gray-200 dark:border-gray-800
              bg-white dark:bg-gray-900
              shadow-xl shadow-gray-900/5 dark:shadow-gray-950/50
              p-8
              transition-all duration-300
              hover:shadow-2xl hover:-translate-y-1">

    <h3 class="text-sm font-semibold text-brand uppercase tracking-wider">
      Plan Pro
    </h3>

    <div class="mt-4 flex items-baseline gap-1">
      <span class="text-5xl font-bold text-gray-900 dark:text-white">$29</span>
      <span class="text-gray-500 dark:text-gray-400">/mes</span>
    </div>

    <p class="mt-4 text-sm text-gray-600 dark:text-gray-400">
      Todo lo que necesita para construir y entregar mas rapido.
    </p>

    <ul class="mt-8 space-y-3 text-sm">
      <li class="flex items-center gap-3 text-gray-700 dark:text-gray-300">
        <svg class="w-5 h-5 text-brand shrink-0" fill="currentColor" viewBox="0 0 20 20">
          <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
        </svg>
        Proyectos ilimitados
      </li>
      <li class="flex items-center gap-3 text-gray-700 dark:text-gray-300">
        <svg class="w-5 h-5 text-brand shrink-0" fill="currentColor" viewBox="0 0 20 20">
          <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
        </svg>
        Soporte prioritario
      </li>
      <li class="flex items-center gap-3 text-gray-700 dark:text-gray-300">
        <svg class="w-5 h-5 text-brand shrink-0" fill="currentColor" viewBox="0 0 20 20">
          <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
        </svg>
        Analiticas avanzadas
      </li>
    </ul>

    <button class="mt-8 w-full rounded-lg bg-brand py-3 text-sm font-semibold text-white
                   hover:bg-brand-dark
                   focus:outline-none focus:ring-2 focus:ring-brand/50 focus:ring-offset-2
                   dark:focus:ring-offset-gray-900
                   transition-colors duration-200">
      Comenzar ahora
    </button>
  </div>
</div>

Conclusion

Tailwind CSS v4 es un gran paso adelante para el framework. El paso a la configuracion CSS-first hace que los proyectos sean mas simples de configurar y razonar. El motor Oxide elimina el rendimiento de compilacion como una preocupacion. Y los nuevos utilities, construidos sobre caracteristicas CSS modernas como container queries y colores OKLCH, le dan herramientas mas poderosas mientras escribe menos CSS personalizado.

Si esta comenzando un nuevo proyecto, no hay razon para no usar v4. Si esta manteniendo un proyecto v3, la herramienta de actualizacion hace que la migracion sea sencilla para la mayoria de las bases de codigo. La comunidad y el ecosistema han adoptado completamente v4, y la experiencia del desarrollador es mejor que nunca.

Use nuestro Convertidor de CSS a Tailwind para convertir rapidamente CSS existente.

Comience a experimentar con las nuevas caracteristicas, especialmente los container queries y la directiva @theme. Cambian fundamentalmente como puede abordar el diseno de componentes, y una vez que los adopte, volver atras se siente como un retroceso.