Tailwind CSS v4
Este skill cubre Tailwind CSS v4.x según se documenta en https://tailwindcss.com/docs. v4 se configura en CSS, no en JavaScript, y muchos nombres de clase y valores por defecto de v3 han cambiado. El skill recoge lo que se diferencia de los hábitos: la configuración CSS-first, los valores por defecto sorprendentes, las utilidades renombradas y los patrones que recomienda la documentación. Cada afirmación en los archivos de referencia termina con la página de la que proviene.
Cómo navegar
- Lee las reglas a continuación. Capturan los hábitos de v3 más frecuentes que se rompen en v4.
- Abre el archivo de referencia que coincida con la tarea, de la tabla al final.
- Cuando el proyecto tenga un
tailwind.config.js, directivas@tailwindo nombres de clase de v3, o al revisar código que pueda arrastrar hábitos de v3, leereferences/upgrade-from-v3.mdprimero. La ruta de migración por defecto esnpx @tailwindcss/upgradeen una nueva rama, luego una revisión de su diff y una prueba en el navegador. https://tailwindcss.com/docs/upgrade-guide#using-the-upgrade-tool
Inicio rápido (CSS-first, Vite)
npm install tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [tailwindcss()] })
/* app.css */
@import "tailwindcss";
@theme {
--color-midnight: #121063;
--font-display: "Oswald", sans-serif;
}
@custom-variant dark (&:where(.dark, .dark *));
- Toda la configuración consiste en un paquete, un plugin y una sola
@import "tailwindcss";. Los pasos de instalación no usantailwind.config.jsni un arraycontent. https://tailwindcss.com/docs/installation/using-vite - Tailwind escanea los archivos fuente por sí mismo. Los archivos en
.gitignore,node_modules, archivos CSS y archivos de bloqueo se omiten. https://tailwindcss.com/docs/detecting-classes-in-source-files#which-files-are-scanned - Next.js, Angular y otros bundlers que no sean Vite usan el plugin de PostCSS:
npm install tailwindcss @tailwindcss/postcss postcss, luegoplugins: { "@tailwindcss/postcss": {} }. https://tailwindcss.com/docs/installation/using-postcss - Una
@importde URL de fuente (Google Fonts y similares) va primero, encima de@import "tailwindcss", luego la familia se declara en@theme. https://tailwindcss.com/docs/font-family#customizing-your-theme - Las variables de
@themecrean utilidades:--color-midnightdabg-midnight,text-midnight,fill-midnight, y--font-displaydafont-display. https://tailwindcss.com/docs/theme#what-are-theme-variables
Las reglas que más importan
Configuración y ajustes
- El plugin de PostCSS es
@tailwindcss/postcss, notailwindcss. No agreguesautoprefixeropostcss-import: las importaciones y los prefijos de proveedor están integrados. https://tailwindcss.com/docs/upgrade-guide#using-postcss - En una configuración de Vite, las guías de framework listan
tailwindcss()primero enplugins, antes del plugin del framework (React Router, SvelteKit, SolidJS, Qwik). Los docs no indican ningún requisito de orden. https://tailwindcss.com/docs/installation/framework-guides/react-router https://tailwindcss.com/docs/installation/framework-guides/sveltekit - Personaliza en CSS con
@theme. Una configuración JS ya no se detecta y solo se carga a través de@config "../../tailwind.config.js";, sincorePlugins,safelistoseparator. https://tailwindcss.com/docs/upgrade-guide#using-a-javascript-config-file - Safelist con
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");. https://tailwindcss.com/docs/detecting-classes-in-source-files#safelisting-specific-utilities - Una librería construida con Tailwind dentro de
node_modulesno se escanea: añade@source "../node_modules/@acmecorp/ui-lib";(ruta relativa a la hoja de estilo). https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources - Nunca construyas nombres de clase dinámicamente (
`bg-${color}-600`). Mapea los valores a cadenas de clase completas. https://tailwindcss.com/docs/detecting-classes-in-source-files#dynamic-class-names - Un bloque
<style>de Vue, Svelte o Astro y un módulo CSS se compilan por separado. Antes de@applyallí, añade@reference "../app.css";, o usavar(--color-blue-500)en su lugar. https://tailwindcss.com/docs/compatibility#explicit-context-sharing https://tailwindcss.com/docs/compatibility#vue-svelte-and-astro - Tailwind v4 no está diseñado para usarse con preprocesadores CSS como Sass, Less o Stylus, por lo que no se pueden usar para hojas de estilo o bloques
<style>en Vue, Svelte o Astro. https://tailwindcss.com/docs/compatibility#sass-less-and-stylus - v4 necesita Safari 16.4+, Chrome 111+, Firefox 128+. Quédate con v3.4 para navegadores más antiguos. https://tailwindcss.com/docs/upgrade-guide#browser-requirements
Tema y CSS personalizado
- Cuando una variable de tema referencia a otra variable, escribe
@theme inline { --font-sans: var(--font-inter); }, de lo contrario el valor se resuelve donde se define--font-sans. https://tailwindcss.com/docs/theme#referencing-other-variables - Elimina un espacio de nombres por defecto con
--color-*: initial;, todo el tema con--*: initial;. https://tailwindcss.com/docs/theme#overriding-the-default-theme - Declara utilidades personalizadas con
@utility name { ... }, no@layer utilities, para que las variantes funcionen sobre ellas. https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities - Lee los valores del tema en CSS personalizado y JS como variables CSS (
var(--color-red-500)), no contheme(colors.red.500)oresolveConfig. https://tailwindcss.com/docs/upgrade-guide#theme-values-in-javascript - Usa la misma unidad para cada breakpoint (rem como los valores por defecto), o los breakpoints se sobrescribirán entre sí. https://tailwindcss.com/docs/responsive-design#customizing-your-theme
Sintaxis de clases
- La abreviatura de variables CSS usa paréntesis:
bg-(--brand-color), nobg-[--brand-color]. https://tailwindcss.com/docs/upgrade-guide#variables-in-arbitrary-values text-(--my-var)es ambiguo (tamaño de fuente o color), por lo que se debe añadir una sugerencia de tipo:text-(length:--my-var)otext-(color:--my-var). Las mismas sugerencias existen enfont-(family-name:--f),border-(length:--w),bg-(image:--img)yshadow-(color:--c). https://tailwindcss.com/docs/adding-custom-styles#resolving-ambiguities https://tailwindcss.com/docs/font-family https://tailwindcss.com/docs/border-width https://tailwindcss.com/docs/background-image https://tailwindcss.com/docs/box-shadow- El modificador de importancia va al final:
bg-red-500!. https://tailwindcss.com/docs/upgrade-guide#the-important-modifier - Las variantes apiladas se aplican de izquierda a derecha:
*:first:pt-0, nofirst:*:pt-0. https://tailwindcss.com/docs/upgrade-guide#variant-stacking-order - Las clases sin prefijo apuntan a todos los tamaños.
sm:no significa móvil: escribetext-center sm:text-left. https://tailwindcss.com/docs/responsive-design#targeting-mobile-screens hover:solo se aplica en dispositivos que pueden hacer hover (@media (hover: hover)). Trata el hover como una mejora. https://tailwindcss.com/docs/upgrade-guide#hover-styles-on-mobile
Valores por defecto cambiados
- Los colores de borde y división por defecto son
currentColor: siempre establece un color conborder. https://tailwindcss.com/docs/upgrade-guide#default-border-color ringes 1pxcurrentColor. Escribering-3 ring-blue-500para el aspecto de v3. https://tailwindcss.com/docs/upgrade-guide#default-ring-width-and-color- Oculta los outlines de enfoque con
outline-hidden(se mantiene en el modo forced-colors): elfocus:outline-nonede v3 se convierte enfocus:outline-hidden.outline-noneahora elimina el outline por completo. https://tailwindcss.com/docs/upgrade-guide#renamed-outline-utility - Las escalas cambiaron:
shadow-sm,rounded-sm,blur-smde v3 ahora son-xs, yshadow,rounded,blursimples de v3 ahora son-sm. https://tailwindcss.com/docs/upgrade-guide#updated-shadow-radius-and-blur-scales - Los degradados son
bg-linear-to-r, además debg-radialybg-conic-<angle>. https://tailwindcss.com/docs/background-image#adding-a-linear-gradient containerno centra ni añade relleno: escribecontainer mx-auto px-4. https://tailwindcss.com/docs/max-width#using-breakpoints-container- Para cuadrículas, layouts envolventes o hijos en un orden personalizado, usa
gapen lugar despace-x-*yspace-y-*. https://tailwindcss.com/docs/margin#limitations - Los botones tienen
cursor: default. https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor - Los placeholders usan el color de texto actual con un 50% de opacidad. https://tailwindcss.com/docs/upgrade-guide#new-default-placeholder-color
- Las clases de visualización ya no anulan el atributo
hidden: eliminahiddenpara mostrar el elemento. https://tailwindcss.com/docs/upgrade-guide#hidden-attribute-takes-priority
Modo oscuro con una clase
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
// inline en <head>, antes de que la página se renderice
document.documentElement.classList.toggle(
"dark",
localStorage.theme === "dark" ||
(!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
Establece localStorage.theme = "dark" o "light", y localStorage.removeItem("theme") para seguir el sistema. https://tailwindcss.com/docs/dark-mode#with-system-theme-support
Archivos de referencia
| Archivo | Léelo cuando |
|---|---|
| references/installation-and-frameworks.md | Instalar Tailwind, elegir Vite, PostCSS o CLI, pasos específicos del framework, módulos CSS, herramientas de editor |
| references/upgrade-from-v3.md | Migrar un proyecto de v3, revisar código con nombres de clase o configuración de v3 |
| references/utilities-and-variants.md | Escribir clases: valores arbitrarios, conflictos, variantes de estado, group y peer, responsive, consultas de contenedor, modo oscuro |
| references/theme-and-colors.md | Añadir o sobrescribir colores, fuentes, breakpoints, espaciado, animaciones, namespaces de tema |
| references/custom-styles.md | Estilos base, Preflight, clases de componentes, @utility, utilidades funcionales, @custom-variant, @variant |
| references/directives-and-source-detection.md | @apply, @reference, --alpha(), --spacing(), @config, @plugin, @source, opciones de importación (prefix, important, source) |
| references/layout-flexbox-grid.md | Display, position, inset, z-index, columns, flex, grid, alineación y alineación -safe |
| references/spacing-and-sizing.md | Padding, margin, space, width, height, size, escala de contenedor, unidades de viewport, tamaños lógicos |
| references/typography.md | Fuentes, tamaño de fuente y altura de línea, espaciado entre letras, text wrap, overflow wrap, decoración, content |
| references/backgrounds-and-borders.md | Degradados, imagen de fondo, tamaño y posición, radio, ancho de borde y color, outlines |
| references/effects-and-filters.md | Sombras, rings, text shadow, opacidad, modos de mezcla, máscaras, filtros y backdrop filters |
| references/transitions-transforms-tables.md | Transiciones, transiciones discretas, animaciones, rotate, scale, translate, 3D, zoom, tablas |
| references/interactivity-and-svg.md | Esquema de colores, field sizing, scrollbars, scroll snap, cursor, will-change, SVG fill y stroke, colores forzados |