Tema y personalización

La directiva @theme

Tailwind CSS 4 traslada toda la personalización del tema al propio CSS mediante la directiva @theme. Esta directiva sustituye al archivo tailwind.config.js de versiones anteriores y permite definir tokens de diseño como variables CSS que Tailwind reconoce automáticamente para generar clases de utilidad.

La configuración básica parte de importar Tailwind CSS y declarar un bloque @theme con las variables personalizadas:

@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
  --color-brand-light: #93c5fd;
  --color-brand-dark: #1e40af;
}

Las variables definidas dentro de @theme se exponen como propiedades personalizadas CSS en el selector :root, lo que significa que están disponibles en todo el documento. Además, Tailwind genera automáticamente las clases de utilidad correspondientes: bg-brand, text-brand-light, border-brand-dark, entre otras.

Cada variable dentro de @theme sigue un patrón de namespace: el prefijo (--color-, --font-, --spacing-) indica a Tailwind qué tipo de utilidad debe generar a partir de ese valor.

Colores personalizados con --color-*

El namespace --color-* permite definir paletas de colores completas que se integran con todas las utilidades que trabajan con color: bg-*, text-*, border-*, ring-* y más.

@import "tailwindcss";

@theme {
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-accent: #f59e0b;
  --color-success: #10b981;
  --color-danger: #ef4444;
}

Con esta configuración, las clases bg-primary-500, text-primary-700, border-accent, ring-danger quedan disponibles en el HTML:

<button class="bg-primary-600 hover:bg-primary-700 text-white px-6 py-2 rounded-lg">
  Acción principal
</button>

<span class="bg-success/10 text-success px-3 py-1 rounded-full text-sm font-medium">
  Activo
</span>

La sintaxis bg-success/10 aplica el color success con un 10% de opacidad, funcionando de forma nativa con los colores definidos en @theme.

Tipografía, espaciado y breakpoints

Tipografía con --font-*

El namespace --font-* define familias tipográficas que se utilizan con la clase font-*.

@theme {
  --font-display: "Playfair Display", serif;
  --font-body: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;
}

<h1 class="font-display text-4xl font-bold">Título con tipografía Display</h1>
<p class="font-body text-base text-gray-700">Texto del cuerpo con Inter.</p>

Espaciado con --spacing

El token --spacing define la unidad base del sistema de espaciado. Tailwind CSS 4 utiliza esta unidad para calcular todos los valores de margin, padding, gap, width y height.

@theme {
  --spacing: 0.25rem;
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
}

Con --spacing: 0.25rem, la clase p-4 genera un padding de 1rem (4 x 0.25rem). Los valores individuales como --spacing-18 habilitan clases específicas: p-18, m-18, w-18, gap-18.

Breakpoints con --breakpoint-*

Los puntos de corte responsive se configuran mediante el namespace --breakpoint-*:

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

Al añadir --breakpoint-3xl: 1920px, la variante 3xl: queda disponible para pantallas de alta resolución.

Sombras y animaciones personalizadas

Sombras con --shadow-*

El namespace --shadow-* permite definir sombras personalizadas que se aplican con la clase shadow-{nombre}.

@theme {
  --shadow-soft: 0 2px 8px rgba(0, 0, 0, 0.08);
  --shadow-elevated: 0 8px 24px rgba(0, 0, 0, 0.12);
  --shadow-glow: 0 0 20px rgba(59, 130, 246, 0.4);
}

<div class="shadow-soft rounded-lg bg-white p-6">Tarjeta con sombra suave</div>
<div class="shadow-glow rounded-lg bg-white p-6">Tarjeta con efecto glow</div>

Animaciones con --animate-*

Las animaciones personalizadas combinan el namespace --animate-* con un bloque @keyframes:

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

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

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

<div class="animate-fade-in">Este elemento aparece con fade</div>
<div class="animate-slide-up">Este elemento sube deslizándose</div>

Reiniciar namespaces con initial

Para eliminar los valores predeterminados de un namespace y partir de cero, se aplica initial al namespace con comodín:

@import "tailwindcss";

@theme {
  --color-*: initial;

  --color-white: #ffffff;
  --color-black: #000000;
  --color-gray-500: #6b7280;
  --color-brand: #2563eb;
}

Con --color-*: initial, todas las paletas de color predeterminadas de Tailwind se eliminan. Solo quedan disponibles los colores definidos explícitamente. Esto resulta útil para proyectos con un sistema de diseño cerrado donde se quiere evitar el uso accidental de colores no aprobados.

Se puede aplicar initial a cualquier namespace: --shadow-*: initial, --font-*: initial, --spacing-*: initial. Incluso --*: initial descarta todos los tokens del tema predeterminado.

@theme inline frente a @theme

La variante @theme inline modifica la forma en que Tailwind CSS inyecta los valores en el CSS generado. Con @theme estándar, los valores se exponen como variables CSS y las utilidades los referencian mediante var(). Con @theme inline, los valores se insertan directamente en las propiedades CSS sin crear variables intermedias.

/* Los valores se exponen como var(--color-brand) */
@theme {
  --color-brand: #2563eb;
}

/* Los valores se inyectan literalmente: color: #ff6b00 */
@theme inline {
  --color-highlight: #ff6b00;
}

La opción inline resulta útil para valores que no necesitan ser reutilizados como variables CSS, o cuando se busca un CSS final más compacto.

La directiva @source y la función theme()

La directiva @source registra rutas adicionales que Tailwind debe escanear para detectar clases utilizadas. Resulta necesaria cuando parte del codigo esta fuera de las rutas por defecto:

@import "tailwindcss";

@source "../components/**/*.html";
@source inline("bg-red-500 text-white p-4");

Los valores definidos en @theme son variables CSS estándar accesibles con var(). La función theme() también permite acceder a los tokens del tema dentro de CSS personalizado:

.gradient-hero {
  background: linear-gradient(135deg, theme(--color-brand), white);
  font-family: var(--font-body);
}

Ejemplo completo de tema personalizado

Una configuración de tema completa para un proyecto con identidad visual propia:

@import "tailwindcss";

@theme {
  --color-*: initial;
  --color-white: #ffffff;
  --color-black: #0a0a0a;
  --color-gray-50: #fafafa;
  --color-gray-200: #e4e4e7;
  --color-gray-500: #71717a;
  --color-gray-900: #18181b;
  --color-primary-500: #6366f1;
  --color-primary-600: #4f46e5;
  --color-secondary-500: #ec4899;

  --font-sans: "Inter", system-ui, sans-serif;
  --font-heading: "Cal Sans", "Inter", sans-serif;

  --shadow-card: 0 1px 3px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
  --animate-enter: enter 0.2s ease-out;
}

@keyframes enter {
  from { opacity: 0; transform: scale(0.95); }
  to { opacity: 1; transform: scale(1); }
}

<div class="bg-gray-50 font-sans min-h-screen">
  <header class="bg-primary-600 text-white px-6 py-4">
    <h1 class="font-heading text-2xl">Mi Aplicación</h1>
  </header>
  <div class="bg-white shadow-card rounded-xl p-8 animate-enter max-w-5xl mx-auto mt-6">
    <h2 class="font-heading text-xl text-gray-900">Panel principal</h2>
    <p class="text-gray-500 mt-2">Contenido del panel personalizado.</p>
  </div>
</div>