Configuración

Configuración CSS-first con @theme

Tailwind CSS introduce un paradigma de configuración moderno CSS-first: 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.

El flujo de trabajo CSS-first reemplaza al antiguo archivo tailwind.config.js. El diagrama siguiente muestra cómo una variable declarada dentro de @theme se traduce en múltiples utilidades sin escribir código JavaScript ni mantener un array content:

flowchart TD
    CSS["@theme en style.css<br/>--color-brand-500: oklch(0.55 0.2 250)"] --> NS["Namespace --color-*"]
    NS --> BG["bg-brand-500"]
    NS --> TX["text-brand-500"]
    NS --> BR["border-brand-500"]
    NS --> RG["ring-brand-500"]
    NS --> AC["accent-brand-500"]
    NS --> VAR[":root { --color-brand-500: oklch(...) }"]

    CSS --> FT["Namespace --font-*"]
    FT --> FU["font-display, font-body"]

    CSS --> SP["Namespace --spacing<br/>--breakpoint-*<br/>--shadow-*<br/>--animate-*"]
    SP --> UT["m-*, p-*, sm: md: 2xl:<br/>shadow-*, animate-*"]

Espacios de nombres disponibles

Tailwind CSS 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 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 enfoque clásico basado en 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 el enfoque clásico, Tailwind CSS 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 clásica (obsoleta)

La configuración clásica 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 del enfoque clásico al moderno

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

| Enfoque clásico (JavaScript) | Enfoque moderno CSS-first | |-------------------------------|---------------------------| | 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 heredado con @config, después ir trasladando secciones a @theme y finalmente eliminar el archivo JavaScript cuando toda la configuración esté en CSS.