Tailwind CSS v4: una reescritura completa

Tailwind CSS v4 no es una actualizacion incremental: es una reescritura desde cero. El nuevo motor, basado en el proyecto Oxide escrito en Rust, ofrece compilación hasta 10x más rápida, configuración nativa en CSS y un modelo más alineado con los estandares web.

Los cambios principales

1. Configuración en CSS, no en JavaScript

El cambio más significativo es que la configuración se realiza directamente en CSS usando la directiva @theme, eliminando el archivo tailwind.config.js.

@import "tailwindcss";

@theme {
  --color-primary: #ffc400;
  --color-secondary: #e6286a;
  --font-sans: "Inter", system-ui, sans-serif;
  --radius-lg: 1rem;
}

Esto significa que:

  • Tu configuración es CSS estandar
  • Las variables del tema son CSS custom properties reales
  • Puedes acceder a los valores del tema desde cualquier CSS

2. Deteccion automática de contenido

En v3, necesitabas configurar manualmente los paths de archivos a escanear:

// v3 - configuración manual
content: ['./src/**/*.{html,ts,tsx}']

En v4, Tailwind detecta automaticamente los archivos de tu proyecto analizando la estructura del repositorio. Solo necesitas excluir archivos si es necesario:

/* v4 - exclusion opcional */
@source not "./src/legacy/**";

3. CSS-first, no utility-first

Tailwind v4 se apoya más en CSS nativo. Muchas funcionalidades que antes requeran configuración especial ahora usan estandares CSS:

/* Variables del tema son CSS custom properties reales */
.custom-element {
  background: var(--color-primary);
  font-family: var(--font-sans);
  border-radius: var(--radius-lg);
}

Nuevas utilidades y sintaxis

Container queries nativas

<!-- Definir un contenedor -->
<div class="@container">
  <!-- Responder al tamaño del contenedor -->
  <div class="@sm:grid @sm:grid-cols-2 @lg:grid-cols-3">
    <!-- contenido -->
  </div>
</div>

También puedes nombrar contenedores:

<div class="@container/sidebar">
  <div class="@sm/sidebar:flex @md/sidebar:grid">
    <!-- contenido -->
  </div>
</div>

Variantes de campo abierto

<!-- Estilos basados en el estado de inputs hijos -->
<fieldset class="has-[:focus]:ring-2 has-[:invalid]:border-red-500">
  <input type="email" required />
</fieldset>

<!-- Variante not -->
<div class="not-[:first-child]:border-t">
  <!-- todos excepto el primer hijo tienen borde superior -->
</div>

Gradientes mejorados

<!-- Interpolacion en oklch para gradientes más naturales -->
<div class="bg-linear-to-r/oklch from-blue-500 to-green-500">
  <!-- gradiente con interpolación perceptual -->
</div>

<!-- Angulos personalizados -->
<div class="bg-linear-[135deg] from-amber-400 to-rose-500">
  <!-- gradiente a 135 grados -->
</div>

3D transforms

<div class="rotate-x-45 rotate-y-12 perspective-800">
  <!-- Transformaciones 3D directas -->
</div>

Cambios de sintaxis: v3 vs v4

Concepto v3 v4
Import principal @tailwind base; @tailwind components; @tailwind utilities; @import "tailwindcss";
Configuración tailwind.config.js @theme { } en CSS
Custom colors theme.extend.colors --color-* en @theme
Custom spacing theme.extend.spacing --spacing-* en @theme
Custom breakpoints theme.screens --breakpoint-* en @theme
Custom fonts theme.fontFamily --font-* en @theme
Plugins plugins: [require('...')] @plugin "..." en CSS
Container queries Plugin necesario Nativo con @container
Content paths content: [...] Deteccion automática

Utilidades renombradas

Algunas utilidades cambiaron de nombre para ser más consistentes:

v3 v4 Motivo
shadow-sm shadow-xs Escala más lógica
shadow shadow-sm Consistencia
drop-shadow-sm drop-shadow-xs Misma escala que shadow
blur-sm blur-xs Consistencia
rounded-sm rounded-xs Misma lógica
outline-none outline-hidden Más descriptivo
ring ring-3 Ancho explícito
flex-grow grow Simplificacion
flex-shrink shrink Simplificacion
bg-opacity-50 bg-black/50 Sintaxis de modificador

Guia de migración paso a paso

Paso 1: Actualizar dependencias

# Instalar Tailwind v4
npm install tailwindcss@4

# Para Angular, instalar el plugin de PostCSS
npm install @tailwindcss/postcss@4

Paso 2: Migrar la configuración

Reemplazar tailwind.config.js con un bloque @theme en tu CSS principal:

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

@theme {
  /* Mover tus colores custom */
  --color-brand: #ffc400;
  --color-brand-hover: #ff9100;

  /* Mover tus fuentes */
  --font-sans: "Inter", system-ui, sans-serif;

  /* Mover tus breakpoints si los personalizaste */
  --breakpoint-sm: 40rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
}

Paso 3: Usar la herramienta de migración automática

Tailwind v4 incluye un codemod para migrar automaticamente:

npx @tailwindcss/upgrade

Este comando:

  • Convierte tailwind.config.js a @theme en CSS
  • Renombra utilidades obsoletas
  • Actualiza la sintaxis de importacion
  • Migra plugins compatibles

Paso 4: Actualizar clases renombradas

Buscar y reemplazar las clases que cambiaron de nombre. El codemod hace la mayoria, pero verifica manualmente:

# Buscar clases potencialmente obsoletas
grep -r "shadow-sm\|rounded-sm\|blur-sm\|ring " src/

Paso 5: Verificar dark mode

/* v4 usa la media query por defecto */
/* Para usar clase, configurar: */
@variant dark (&:where(.dark, .dark *));

Rendimiento: los números

El motor Oxide (Rust) de Tailwind v4 ofrece mejoras dramaticas:

Metrica v3 v4 Mejora
Build completo ~350ms ~35ms ~10x
Build incremental ~180ms ~8ms ~22x
Tamano del CSS Variable Menor Mejor tree-shaking

Conclusion

Tailwind CSS v4 es un salto generacional. La configuración en CSS puro, la detección automática de contenido, y el motor Oxide hacen que el flujo de trabajo sea más rápido y más natural. La herramienta de migración automática facilita la transición, pero toma tiempo para familiarizarte con la nueva sintaxis de temas y las utilidades renombradas. Si estas empezando un proyecto nuevo, no hay razon para no usar v4.