Configuración

Configuración CSS-first con @theme

Tailwind CSS 4 introduce un paradigma de configuración completamente nuevo: toda la personalización del tema se define directamente en CSS mediante la directiva @theme. Este enfoque elimina la necesidad del archivo tailwind.config.js y acerca la configuración al lugar donde se aplican los estilos.

Importación y directiva @theme

El punto de partida es la importación de Tailwind seguida del bloque @theme donde se definen los tokens de diseño personalizados:

@import "tailwindcss";

@theme {
  --color-brand-50: oklch(0.97 0.01 250);
  --color-brand-500: oklch(0.55 0.2 250);
  --color-brand-900: oklch(0.25 0.1 250);

  --font-display: "Satoshi", sans-serif;
  --font-body: "Inter", system-ui, sans-serif;

  --breakpoint-3xl: 1920px;
}

Cada variable CSS definida dentro de @theme genera automáticamente las clases de utilidad correspondientes. La variable --color-brand-500 produce utilidades como bg-brand-500, text-brand-500 y border-brand-500.

Espacios de nombres disponibles

Tailwind CSS 4 organiza los tokens de diseño en espacios de nombres que determinan qué utilidades se generan:

@import "tailwindcss";

@theme {
  /* Colores: genera bg-*, text-*, border-*, accent-*, etc. */
  --color-primary: #3b82f6;
  --color-success: #10b981;
  --color-danger: #ef4444;

  /* Fuentes: genera font-* */
  --font-heading: "Playfair Display", serif;

  /* Espaciado base: afecta a m-*, p-*, gap-*, etc. */
  --spacing: 0.25rem;

  /* Breakpoints: genera sm:, md:, etc. */
  --breakpoint-xs: 475px;

  /* Sombras: genera shadow-* */
  --shadow-soft: 0 4px 20px rgba(0, 0, 0, 0.08);
  --shadow-card: 0 2px 8px rgba(0, 0, 0, 0.12);

  /* Animaciones: genera animate-* */
  --animate-wiggle: wiggle 1s ease-in-out infinite;

  @keyframes wiggle {
    0%, 100% { transform: rotate(-3deg); }
    50% { transform: rotate(3deg); }
  }

  /* Bordes redondeados: genera rounded-* */
  --radius-pill: 9999px;

  /* Easing: genera ease-* */
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
}

Las utilidades personalizadas se usan directamente en el HTML:

<div class="bg-primary font-heading shadow-card rounded-pill">
  <h2 class="text-white animate-wiggle">Contenido personalizado</h2>
</div>

Sobrescribir el tema por defecto

Por defecto, @theme extiende el tema existente de Tailwind. Para reemplazar un espacio de nombres completo y usar solo los valores propios, se establece el namespace a initial:

@import "tailwindcss";

@theme {
  --color-*: initial;

  --color-white: #ffffff;
  --color-black: #000000;
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-accent: #8b5cf6;
}

Con --color-*: initial se eliminan todos los colores predeterminados de Tailwind (slate, gray, red, blue, etc.) y solo quedan disponibles los colores definidos explícitamente.

Variables CSS en el HTML

Los tokens definidos en @theme están disponibles como variables CSS nativas en todo el documento. Se pueden usar directamente con var() o en valores arbitrarios de Tailwind:

<div class="bg-[var(--color-primary)]">
  Usando la variable CSS directamente
</div>

<div style="color: var(--color-accent)">
  Variable CSS en atributo style
</div>

Directiva @source

Tailwind CSS 4 detecta automáticamente los archivos fuente del proyecto. La directiva @source permite añadir rutas adicionales que el motor debe analizar para encontrar clases utilizadas:

@import "tailwindcss";

@source "../node_modules/@my-ui/components";
@source "../shared/templates";

También se puede excluir contenido de la detección automática:

@source not "../src/legacy";

La directiva @source inline(...) permite indicar clases que se generan dinámicamente y que el motor no puede detectar por análisis estático:

@source inline("bg-red-500 bg-blue-500 bg-green-500");

Directiva @plugin

Los plugins de Tailwind se cargan en CSS mediante la directiva @plugin, reemplazando el array plugins del antiguo tailwind.config.js:

@import "tailwindcss";

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

Los plugins se instalan previamente con npm (npm install @tailwindcss/typography) y se referencian por su nombre de paquete.

Compatibilidad con tailwind.config.js

Para proyectos que migran desde Tailwind 3, la versión 4 mantiene compatibilidad con el archivo JavaScript de configuración mediante la directiva @config:

@import "tailwindcss";

@config "../tailwind.config.js";

Esta directiva carga la configuración del archivo JavaScript y la fusiona con los valores de @theme. Se recomienda como paso intermedio durante la migración, con el objetivo final de trasladar toda la configuración a @theme.

Configuración heredada de Tailwind 3

La configuración tradicional en Tailwind 3 se basaba en el archivo tailwind.config.js, un archivo JavaScript ubicado en la raíz del proyecto.

Estructura del archivo de configuración

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    './pages/**/*.{html,js}',
  ],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        secondary: '#64748b',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
        serif: ['Georgia', 'serif'],
      },
      spacing: {
        '72': '18rem',
        '84': '21rem',
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
  ],
}

Los aspectos principales de esta configuración eran:

• content: array de rutas donde Tailwind buscaba las clases utilizadas para la purga de CSS no usado
• theme: objeto de personalización del sistema de diseño
• theme.extend: extensión del tema sin sobrescribir los valores por defecto
• plugins: array de plugins cargados mediante require()

Migración de v3 a v4

La correspondencia entre la configuración JavaScript y la nueva configuración CSS es directa:

| Tailwind 3 (JavaScript) | Tailwind 4 (CSS) | |--------------------------|-------------------| | theme.colors.primary | --color-primary en @theme | | theme.fontFamily.sans | --font-sans en @theme | | theme.spacing[18] | --spacing base en @theme | | content: [...] | Detección automática + @source | | plugins: [require(...)] | @plugin "..." | | theme.screens.xs | --breakpoint-xs en @theme |

La migración se puede realizar de forma incremental: primero cargar el archivo legacy con @config, después ir trasladando secciones a @theme y finalmente eliminar el archivo JavaScript cuando toda la configuración esté en CSS.