Migrar de Tailwind 3 a 4: guía práctica para dar el salto sin complicaciones

¿Por qué este cambio importa tanto?

Cada vez que aparece una nueva versión mayor de Tailwind es normal pensar: “¿qué se va a romper ahora?”. Con v4 la historia cambia: en lugar de añadir complejidad, la reduce.

Lo esencial es que ya no dependes de tailwind.config.js. Ahora toda la configuración de tu sistema visual se define directamente en el CSS con la directiva @theme. Esto significa menos archivos, menos dependencias y un flujo más natural para cualquier equipo, uses WordPress, Bricks, Gutenberg o un stack distinto.

En otras palabras:

• Sigues trabajando con utilidades como siempre.
• Pero la forma de declarar colores, tipografías, breakpoints o spacing pasa a ser más clara y cercana al CSS estándar.
• Además, el build es más rápido y ligero porque Tailwind 4 reduce capas intermedias.

En este artículo vamos a ver:

• Un checklist final para asegurar que tu migración está lista, junto con prompts prácticos para automatizar parte del proceso y validar la sintaxis.
• Qué cambia realmente de v3 a v4 y qué ventajas aporta.
• Cómo traducir tu configuración de JS a @theme, paso a paso.
• Ejemplos antes → después para los casos más comunes (colores, tipografías, breakpoints, container).
• Consejos específicos para WordPress + WindPress y el patrón sección → contenedor.

Cómo cargar Tailwind 4. Primer paso de la migración

Lo primero en v4 es cargar Tailwind desde tu CSS. No necesitas tailwind.config.js. En WordPress (con WindPress o extractor similar) basta con editar tu CSS principal (por ejemplo, main.css del tema o el CSS que uses en WindPress) y seguir uno de estos dos enfoques:

Opción A — Importación simple (recomendada)

Una sola línea trae preflight + utilidades. Perfecta para la mayoría de migraciones.

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

/* Tus tokens van antes de usarlos */
@theme {
  /* pega aquí lo migrado desde v3: colores, fuentes, breakpoints… */
}

/* Si usabas plugins en v3, ahora van en CSS */
@plugin "tailwindcss/plugin/forms";
@plugin "tailwindcss/plugin/typography";

/* El resto de tu CSS queda igual (base, components, utilities…) */


Opción B — Importar por capas (si ya trabajabas con un orden de capas)

Útil si tu proyecto separa explícitamente capas o si prefieres controlar el orden.

/* main.css */
@import "tailwindcss/theme.css"      layer(theme) theme(static);
@import "tailwindcss/preflight.css"  layer(base);
@import "tailwindcss/utilities.css"  layer(utilities);

/* Declara tokens ANTES de base/components/utilities */
@theme {
  /* tokens migrados */
}

/* Plugins (si aplican) */
@plugin "tailwindcss/plugin/forms";
@plugin "tailwindcss/plugin/typography";

/* Tus capas existentes (respeta tu arquitectura actual) */
/* @layer base { … }
   @layer components { … }
   @layer utilities { … } */


Orden recomendado (muy importante)

1. @import de Tailwind
2. @theme (tus tokens)
3. @plugin (si los usas)
4. Tu CSS existente (@layer base, @layer components, @layer utilities)

Notas rápidas

• No usamos PostCSS adicional si no lo necesitas: en WordPress con WindPress/Extractor basta con el CSS.
• Si no usabas plugins en v3, puedes omitir @plugin.
• No cambies tu arquitectura: solo añade @import + @theme (y @plugin si procede) al inicio de tu CSS principal.

Qué cambia de Tailwind 3 a 4

La actualización a v4 no te obliga a reaprender Tailwind: sigues usando utilidades como siempre. Lo que cambia es dónde y cómo declaras tu sistema visual y cómo se simplifica el flujo.

De configurar en JS a declarar en CSS
En v3 definías colores, tipografías o breakpoints en tailwind.config.js. En v4 esa configuración pasa a CSS con @theme.

• Lo que antes era theme.colors.brand.500 ahora es --color-brand-500.
• theme.fontFamily.sans ahora es --font-sans.
• theme.screens.md ahora es --breakpoint-md.
  No cambian tus clases de utilidad; cambia el lugar donde viven los valores.

Tokens como “fuente de verdad”
@theme convierte tu configuración en tokens (--color-*, --font-*, --breakpoint-*, --spacing-*, --radius-*, --shadow-*).

• Puedes declarar sólo lo que usas (no hace falta “extender” como en v3).
• Los tokens son fáciles de versionar y de comprender por perfiles no técnicos.

Importación y orden más directos
En v4 lo normal es importar Tailwind desde el CSS y colocar @theme antes de tus reglas base, componentes y utilidades. No tienes que cambiar tu arquitectura: basta con que el bloque @theme esté disponible antes de que lo necesites.

Container: adiós a la opción de config
La configuración theme.container de v3 desaparece. Si dependías de .container para centrar y limitar ancho, recréalo como componente (o aplica tu patrón de layout) con el max-width y el padding que ya usabas. Nada más.
(En la sección de “Container” del artículo verás cómo migrarlo en dos líneas.)

Plugins

En Tailwind 3 los plugins se añadían en tailwind.config.js con require().
En v4 pasan a declararse directamente en el CSS con la directiva @plugin.

Antes (Tailwind 3 con tailwind.config.js):

// tailwind.config.js
plugins: [
  require('@tailwindcss/forms'),
  require('@tailwindcss/typography'),
]

Después (Tailwind 4):

/* main.css */
@plugin "tailwindcss/plugin/forms";
@plugin "tailwindcss/plugin/typography";

👉 Así, todos los ajustes (tokens + plugins) viven en tu CSS, sin depender de un archivo JS externo.

Spacing y escalas
Si en v3 no modificaste la escala de espaciado, no declares nada: v4 te da las utilidades estándar.
Si sí la personalizaste, declara sólo los valores que quieras conservar como tokens (--spacing-*) o, si tu pauta lo usa, un “paso” global (--spacing).

Clases dinámicas
La mayoría de utilidades siguen funcionando.
Si generas clases dinámicamente (p. ej., desde plantillas), revisa tu método de extracción o añade una safelist mínima para evitar purgas accidentales.

Qué ventajas obtienes

• Menos fricción y menos archivos: tu sistema visual vive en el CSS, junto a donde trabajas a diario.
• Aprendizaje más suave para el equipo: tokens CSS en lugar de objetos JS.
• Configuración más clara y versionable: @theme actúa como fuente única de verdad.
• Rendimiento y build más predecibles: menos capas intermedias y menos dependencias.
• Migración incremental: puedes trasladar tus valores por bloques (colores → tipografías → breakpoints…) sin romper las plantillas.
• Mejor mantenimiento: cambiar un token (--color-primary) actualiza el sitio entero sin perseguir configuraciones dispersas.

Cambios en utilidades (a tener en cuenta al migrar)

Además de la configuración, en Tailwind 4 se han eliminado algunas utilidades que estaban deprecadas y otras se han renombrado.

Si en tu proyecto aparecen estas clases y al migrar ves que algo deja de aplicarse, revisa esta tabla y usa el reemplazo indicado.

Utilidades eliminadas

Utilidades renombradas

👉 Esta tabla es solo de referencia: si notas que alguna clase de tu CSS ya no funciona, aquí tienes el reemplazo moderno.

Ejemplos antes y después: de config.js a @theme

La configuración de cada proyecto puede variar mucho: no todos usan las mismas paletas de colores, tipografías o breakpoints. Los siguientes ejemplos no son recetas que debas copiar tal cual, sino modelos ilustrativos que te ayudan a reconocer el patrón de cambio entre v3 y v4.

Colores personalizados

Antes (Tailwind 3 con tailwind.config.js):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: "#f5faff",
          500: "#1e40af",
          900: "#1e3a8a",
        },
      },
    },
  },
}

Después (Tailwind 4 con @theme):

@theme {
  --color-brand-50: #f5faff;
  --color-brand-500: #1e40af;
  --color-brand-900: #1e3a8a;
}

👉 Identifica: lo que antes era un objeto JS anidado (brand.500) ahora se convierte en tokens CSS (--color-brand-500).

Tipografías

Antes (Tailwind 3 con tailwind.config.js):

theme: {
  extend: {
    fontFamily: {
      sans: ["Inter", "sans-serif"],
      display: ["Poppins", "sans-serif"],
    },
  },
}

Después (Tailwind 4 con @theme):

@theme {
  --font-sans: "Inter", sans-serif;
  --font-display: "Poppins", sans-serif;
}

👉 Identifica: cada familia se convierte en un token CSS legible, sin necesidad de extender en JS.

Breakpoints (responsive)

Antes (Tailwind 3 con tailwind.config.js):

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    },
  },
}

Después (Tailwind 4 con @theme):

@theme {
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
}

👉 Identifica: cada breakpoint pasa a ser un token que mantiene el mismo nombre (sm, md, lg, xl), pero definido en CSS.

Container

Antes (Tailwind 3 con tailwind.config.js):

theme: {
  container: {
    center: true,
    padding: '1rem',
    screens: {
      lg: '1024px',
      xl: '1280px',
    },
  },
}

Después (Tailwind 4 con @theme):

• La opción theme.container ya no existe.
• Si dependías de .container, recrea el patrón como componente CSS con max-width y padding equivalentes.
• Si usas Flowtitude, recuerda que ya aplica el patrón sección → contenedor de forma automática.

👉 Conclusión de esta sección:
Los ejemplos muestran el cambio de sintaxis (JS → tokens CSS). Tu trabajo en la migración será mapear tus valores reales siguiendo estas equivalencias.

Migración paso a paso

La clave para migrar de Tailwind 3 a 4 es hacerlo en orden y sin prisa: primero identificar lo que usas, después traducirlo a @theme y al final comprobar que todo funciona.

Paso 0 — Preparación mínima

• Haz una copia de seguridad de tu archivo tailwind.config.js.
• Si ya tienes un CSS principal en tu tema (ej. main.css con WindPress), guarda también una copia.
  👉 Con eso es suficiente para volver atrás si algo falla.

Paso 1 — Inventario

Abre tu tailwind.config.js y apunta solo lo que personalizaste:

• Colores (theme.extend.colors)
• Tipografías (theme.extend.fontFamily)
• Breakpoints (theme.screens)
• Escalas tocadas (spacing, radius, sombras, etc.)
• Container (si lo tenías configurado)
• Plugins y safelist

👉 Anota únicamente lo que de verdad usas en el proyecto.

Paso 2 — De config.js a @theme

En v4 ya no existe tailwind.config.js. Todo se define como tokens CSS dentro de @theme.

Para traducir, usa esta tabla oficial de referencia:

• --color-* → Colores (bg-, text-, border-*)
• --font-* → Familias tipográficas (font-sans)
• --text-* → Tamaños de texto (text-xl)
• --font-weight-* → Pesos (font-bold)
• --tracking-* → Letter spacing (tracking-wide)
• --leading-* → Line height (leading-tight)
• --breakpoint-* → Breakpoints responsive (sm:, md:)
• --container-* → Container queries / tamaños (max-w-md)
• --spacing-* → Espaciado y tamaños (p-4, w-64, h-16)
• --radius-* → Border radius (rounded-md)
• --shadow-* → Sombras (shadow-md)
• --animate-*, --ease-*, --aspect-* → Animaciones, timings, ratios…

👉 Ejemplo ilustrativo (usa tus valores reales):

Antes (Tailwind 3 con tailwind.config.js):

theme: {
  extend: {
    colors: {
      primary: "#1e40af",
    },
    fontFamily: {
      sans: ["Inter", "sans-serif"],
    },
    screens: {
      md: "768px",
    },
  },
}

Después (Tailwind 4 con @theme):

@theme {
  --color-primary: #1e40af;
  --font-sans: "Inter", sans-serif;
  --breakpoint-md: 768px;
}

Paso 3 — Migrar plugins

Si en tu tailwind.config.js de v3 usabas plugins (forms, typography, line-clamp, etc.), conviértelos a directivas @plugin en tu CSS.

@plugin "tailwindcss/plugin/forms";
@plugin "tailwindcss/plugin/typography";


• Colócalos junto a tu bloque @theme, al inicio del CSS.
• Asegúrate de tener instalados los paquetes (npm install @tailwindcss/forms, etc.).
• Si no usabas plugins en v3, puedes saltarte este paso.

Paso 4 — Coloca el bloque en tu CSS

Abre tu CSS principal (por ejemplo main.css en WindPress) y pega al inicio el bloque @theme.

@theme {
  /* aquí van tus tokens migrados */
}

Después deja tus capas (@layer base, @layer components, @layer utilities) tal como ya las tenías.

Paso 5 — Revisión rápida

En una página de prueba verifica:

• Colores (bg-primary, text-primary).
• Tipografías (clases font-sans, font-display).
• Breakpoints (ejemplo: que el grid responda en md o lg).
• Container (si lo usabas en v3, recréalo como componente con max-width + padding).

Paso 5 — Limpieza

• Borra el tailwind.config.js si ya no lo usas.
• Elimina tokens que no tengan uso real.
• Revisa compatibilidad de plugins (forms, typography, etc.).
• Si generas clases dinámicas (desde ACF, JetEngine, PHP), asegúrate de que tu extractor las detecta o añade una safelist mínima.

👉 Con estos pasos ya tienes tu configuración migrada de Tailwind 3 a 4 en WordPress, sin necesidad de herramientas extra ni complicaciones.

Checklist final

Antes de dar la migración por terminada, comprueba que:

• Hiciste copia de seguridad de tu configuración original.
• Trasladaste a @theme solo los valores que realmente usas.
• El CSS compila sin errores y aplica los colores, fuentes y breakpoints como antes.
• Tus layouts responden bien y el container está resuelto (si lo usabas).
• Los plugins siguen funcionando o los reemplazaste en @layer utilities.
• Si generas clases dinámicas, están cubiertas (safelist o extractor).
• Eliminaste configuraciones huérfanas y tokens innecesarios.

👉 Si todo está marcado, tu proyecto ya está en Tailwind 4 listo para producción.

Por qué este cambio es estratégico para WordPress y Flowtitude

Migrar a Tailwind 4 no es solo “traducir un archivo de configuración”. Es una oportunidad para ordenar tu sistema visual, reducir fricción y acelerar entregas en proyectos con WordPress, Bricks o Gutenberg.

Razones clave:

• Menos piezas, más foco
  Con @theme, el núcleo de tu diseño vive en un único CSS. Esto reduce dudas de “¿dónde estaba definido esto?” y simplifica la comunicación entre perfiles de diseño y desarrollo.
• Onboarding más fácil
  Diseñadores que vienen de Figma o Sketch entienden mejor variables CSS que un objeto JS. La curva de aprendizaje baja y la autonomía sube.
• Arquitectura más clara
  Con un solo archivo @theme como fuente de verdad, todo tu sistema (tipografía, colores, breakpoints) queda ordenado y es fácil de versionar o documentar.
• Rendimiento y mantenimiento
  Builds más rápidos y predecibles. Si mañana cambias --color-primary, todo el sitio se actualiza sin tocar varias configuraciones dispersas.
• Compatibilidad natural con WordPress
  Con WindPress o extractores similares, @theme encaja perfecto: las clases se siguen generando a partir del contenido y tus tokens viven cerca del CSS real.
  Si alternas entre Bricks y Gutenberg, reduces diferencias y trabajas con un sistema común que no depende del builder.

👉 En resumen: migrar a v4 te deja más ligero que antes y con un sistema que piensa en equipo, no solo en código.

Prompts útiles para facilitar la migración

La migración de Tailwind 3 a 4 es sobre todo un trabajo de traducción de configuraciones. Aunque no conviene automatizarlo todo a ciegas, puedes apoyarte en ChatGPT para acelerar las partes más mecánicas. Estos prompts te ayudan a convertir, validar y limpiar tu configuración. Úsalos con criterio: revisa siempre los resultados antes de aplicar cambios en producción.

1. Convertir tailwind.config.js → @theme

Convierte tu configuración de v3 a tokens de v4, respetando nombres y valores.

Convierte este `tailwind.config.js` de Tailwind v3 a un bloque `@theme` de Tailwind v4 sin inventar valores.

Reglas:
- Usa el namespace correcto según la doc oficial (`--color-*`, `--font-*`, `--breakpoint-*`, etc.).
- Copia los valores tal cual, no inventes ni cambies unidades.
- Devuelve solo un bloque `@theme`.

Aquí tienes mi configuración:
[PEGA AQUÍ TU CONFIG v3]

2. Migrar configuración de container

Si en v3 usabas theme.container, pide que lo traduzca a tokens o a un componente.

A partir de este `tailwind.config.js` de v3, extrae únicamente lo relacionado con `theme.container` y conviértelo en tokens o reglas CSS equivalentes para v4. 
No inventes nada, solo usa los valores originales de max-width y padding.

Aquí tienes mi configuración:
[PEGA AQUÍ TU CONFIG v3]

3. Revisión sintáctica del CSS

Para detectar errores en tu CSS migrado (llaves sin cerrar, nombres de token mal escritos, etc.).

Revisa este CSS y dime:
- Si hay errores de sintaxis que puedan romper Tailwind.
- Si los nombres de tokens están bien escritos según la doc (`--color-*`, `--font-*`, etc.).
- Dame una versión corregida si hay fallos.

CSS:
[PEGA AQUÍ TU CSS]


👉 Con estos prompts puedes mecanizar gran parte del trabajo pesado de conversión, pero recuerda: la revisión manual es imprescindible para asegurarte de que tu sistema visual sigue siendo el mismo.

Errores comunes al migrar

Aunque la migración a Tailwind 4 es sencilla y normalmente no lleva más de unos minutos, hay ciertos tropiezos que conviene evitar:

• Copiar el config.js tal cual a @theme
  No es una conversión 1:1. En v4 solo necesitas los tokens que realmente usas. Si arrastras todo, acabarás con variables innecesarias que complican el mantenimiento.
• Olvidar el orden de carga
  @theme debe ir antes de tus capas (@layer base, @layer components, @layer utilities). Si no, tus tokens no estarán disponibles cuando intentes aplicarlos.
• No revisar el container
  La opción theme.container desapareció. Si dependías de .container, tienes que recrearlo como componente CSS con max-width y padding. Si ya usas un patrón sección → contenedor, no hace falta hacer nada.
• Clases dinámicas sin cubrir
  Si generas clases desde PHP, ACF o JetEngine, asegúrate de que tu extractor o WindPress las detecta. Si no, define una safelist mínima o crea un “playground” oculto donde estén incluidas.

👉 Con ChatGPT y los prompts adecuados, el 90% de migraciones se resuelve en menos de 15 minutos. Lo importante no es el tiempo, sino revisar que los tokens migrados reflejan tu configuración real y que el frontend se ve igual que antes.

FAQ rápidas

¿Necesito reescribir todo mi CSS?
No. Solo mueves tu configuración (tokens) a @theme. Tus clases de utilidad siguen funcionando igual.

¿Qué pasa con los plugins de Tailwind 3?
Muchos siguen funcionando, pero revisa su compatibilidad. En caso de problemas, lo esencial lo puedes cubrir en @layer utilities.

¿WindPress y Tailwind 4 se llevan bien?
Sí. Mientras el extractor detecte tus clases en el contenido, no tendrás problemas. @theme solo define tokens.

En resumen: migrar como excusa para profesionalizar

Dar el salto de Tailwind 3 a 4 no es un cambio traumático: en la mayoría de proyectos solo lleva unos minutos. Lo importante es que esta migración no se quede en un trámite técnico, sino que sea una oportunidad para ordenar tu sistema visual y simplificar tu flujo de trabajo.

• Con @theme, tu configuración pasa a vivir directamente en el CSS.
• Ganas en claridad, mantenimiento y velocidad de build.
• Si usas WordPress (con Bricks, Gutenberg o WindPress), el encaje es natural: sigues trabajando con utilidades, pero con menos piezas que mantener.
• Y lo mejor: puedes apoyarte en ChatGPT para mecanizar parte de la conversión y validar tu CSS, reduciendo el riesgo de errores.

👉 La mejor migración es la que te deja más ligero y con un sistema más claro que antes. Ese es el verdadero beneficio de Tailwind 4.

¿Quieres ir más allá y aprender a trabajar con Tailwind 4 dentro de WordPress de forma ordenada y sin fricciones?
En Flowtitude hemos creado un curso práctico donde verás cómo aplicar este sistema en Bricks y Gutenberg, paso a paso y con ejemplos reales.

👉 Descubre el curso “Descubre Tailwind” y empieza hoy mismo