Tailwind CSS v4
Cette compétence couvre Tailwind CSS v4.x telle que documentée sur https://tailwindcss.com/docs. La v4 est configurée en CSS, pas en JavaScript, et de nombreux noms de classes et valeurs par défaut de la v3 ont changé. La compétence met en évidence ce qui diffère des habitudes : la configuration CSS-first, les valeurs par défaut surprenantes, les utilitaires renommés et les modèles recommandés par la documentation. Chaque affirmation dans les fichiers de référence se termine par la page dont elle est issue.
Comment naviguer
- Lisez les règles ci-dessous. Elles identifient les habitudes v3 les plus fréquentes qui cassent en v4.
- Ouvrez le fichier de référence correspondant à la tâche, depuis le tableau à la fin.
- Lorsque le projet comporte un
tailwind.config.js, des directives@tailwindou des noms de classes v3, ou lors de la révision de code pouvant contenir des habitudes v3, lisez d'abordreferences/upgrade-from-v3.md. Le chemin de migration par défaut estnpx @tailwindcss/upgradedans une nouvelle branche, puis une révision de son diff et un test dans le navigateur. https://tailwindcss.com/docs/upgrade-guide#using-the-upgrade-tool
Démarrage rapide (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 *));
- La configuration complète est un package, un plugin et un seul
@import "tailwindcss";. Les étapes d'installation n'utilisent nitailwind.config.jsni le tableaucontent. https://tailwindcss.com/docs/installation/using-vite - Tailwind analyse lui-même les fichiers sources. Les fichiers dans
.gitignore,node_modules, les fichiers CSS et les fichiers de verrouillage sont ignorés. https://tailwindcss.com/docs/detecting-classes-in-source-files#which-files-are-scanned - Next.js, Angular et autres bundlers non Vite utilisent le plugin PostCSS à la place :
npm install tailwindcss @tailwindcss/postcss postcss, puisplugins: { "@tailwindcss/postcss": {} }. https://tailwindcss.com/docs/installation/using-postcss - Un
@importd'une URL de police (Google Fonts et assimilés) se place en premier, au-dessus de@import "tailwindcss", puis la famille est déclarée dans@theme. https://tailwindcss.com/docs/font-family#customizing-your-theme - Les variables
@themecréent des utilitaires :--color-midnightdonnebg-midnight,text-midnight,fill-midnight, et--font-displaydonnefont-display. https://tailwindcss.com/docs/theme#what-are-theme-variables
Les règles les plus importantes
Configuration et paramétrage
- Le plugin PostCSS est
@tailwindcss/postcss, pastailwindcss. N'ajoutez pasautoprefixeroupostcss-import: les imports et les préfixes vendeurs sont intégrés. https://tailwindcss.com/docs/upgrade-guide#using-postcss - Dans une configuration Vite, les guides des frameworks listent
tailwindcss()en premier dansplugins, avant le plugin du framework (React Router, SvelteKit, SolidJS, Qwik). La documentation ne spécifie aucune exigence d'ordre. https://tailwindcss.com/docs/installation/framework-guides/react-router https://tailwindcss.com/docs/installation/framework-guides/sveltekit - Personnalisez en CSS avec
@theme. Une configuration JS n'est plus détectée et se charge uniquement via@config "../../tailwind.config.js";, sanscorePlugins,safelistouseparator. https://tailwindcss.com/docs/upgrade-guide#using-a-javascript-config-file - Utilisez la liste de sécurité avec
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");. https://tailwindcss.com/docs/detecting-classes-in-source-files#safelisting-specific-utilities - Une bibliothèque construite avec Tailwind et située dans
node_modulesn'est pas analysée : ajoutez@source "../node_modules/@acmecorp/ui-lib";(chemin relatif à la feuille de style). https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources - Ne construisez jamais de noms de classes dynamiquement (
`bg-${color}-600`). Mappez les valeurs vers des chaînes de classes complètes. https://tailwindcss.com/docs/detecting-classes-in-source-files#dynamic-class-names - Un bloc
<style>Vue, Svelte ou Astro et un module CSS sont compilés séparément. Avant@applydans ce contexte, ajoutez@reference "../app.css";, ou utilisezvar(--color-blue-500)à la place. https://tailwindcss.com/docs/compatibility#explicit-context-sharing https://tailwindcss.com/docs/compatibility#vue-svelte-and-astro - Tailwind v4 n'est pas conçu pour être utilisé avec des préprocesseurs CSS comme Sass, Less ou Stylus, ils ne peuvent donc pas être utilisés pour les feuilles de style ou les blocs
<style>dans Vue, Svelte ou Astro. https://tailwindcss.com/docs/compatibility#sass-less-and-stylus - v4 nécessite Safari 16.4+, Chrome 111+, Firefox 128+. Restez sur v3.4 pour les navigateurs plus anciens. https://tailwindcss.com/docs/upgrade-guide#browser-requirements
Thème et CSS personnalisé
- Lorsqu'une variable de thème en référence une autre, écrivez
@theme inline { --font-sans: var(--font-inter); }, sinon la valeur est résolue là où--font-sansest définie. https://tailwindcss.com/docs/theme#referencing-other-variables - Supprimez un espace de noms par défaut avec
--color-*: initial;, tout le thème avec--*: initial;. https://tailwindcss.com/docs/theme#overriding-the-default-theme - Déclarez des utilitaires personnalisés avec
@utility name { ... }, pas@layer utilities, afin que les variantes fonctionnent sur eux. https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities - Lisez les valeurs du thème dans le CSS personnalisé et le JS comme des variables CSS (
var(--color-red-500)), pas avectheme(colors.red.500)ouresolveConfig. https://tailwindcss.com/docs/upgrade-guide#theme-values-in-javascript - Utilisez la même unité pour chaque point d'arrêt (rem comme les valeurs par défaut), sinon les points d'arrêt se remplacent les uns les autres. https://tailwindcss.com/docs/responsive-design#customizing-your-theme
Syntaxe des classes
- La notation abrégée des variables CSS utilise des parenthèses :
bg-(--brand-color), pasbg-[--brand-color]. https://tailwindcss.com/docs/upgrade-guide#variables-in-arbitrary-values text-(--my-var)est ambigu (taille de police ou couleur), ajoutez donc un indicateur de type :text-(length:--my-var)outext-(color:--my-var). Les mêmes indicateurs existent pourfont-(family-name:--f),border-(length:--w),bg-(image:--img)etshadow-(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- Le modificateur important se place à la fin :
bg-red-500!. https://tailwindcss.com/docs/upgrade-guide#the-important-modifier - Les variantes empilées s'appliquent de gauche à droite :
*:first:pt-0, pasfirst:*:pt-0. https://tailwindcss.com/docs/upgrade-guide#variant-stacking-order - Les classes non préfixées ciblent toutes les tailles.
sm:ne signifie pas mobile : écriveztext-center sm:text-left. https://tailwindcss.com/docs/responsive-design#targeting-mobile-screens hover:ne s'applique que sur les appareils capables de survol (@media (hover: hover)). Traitez le survol comme une amélioration. https://tailwindcss.com/docs/upgrade-guide#hover-styles-on-mobile
Valeurs par défaut modifiées
- Les couleurs de bordure et de séparation par défaut sont
currentColor: définissez toujours une couleur avecborder. https://tailwindcss.com/docs/upgrade-guide#default-border-color ringfait 1pxcurrentColor. Écrivezring-3 ring-blue-500pour l'aspect v3. https://tailwindcss.com/docs/upgrade-guide#default-ring-width-and-color- Masquez les contours de focus avec
outline-hidden(conservé en mode forced-colors) : v3focus:outline-nonedevientfocus:outline-hidden.outline-nonesupprime désormais complètement le contour. https://tailwindcss.com/docs/upgrade-guide#renamed-outline-utility - Les échelles ont été décalées : v3
shadow-sm,rounded-sm,blur-smsont maintenant-xs, et v3shadow,rounded,blursimples sont maintenant-sm. https://tailwindcss.com/docs/upgrade-guide#updated-shadow-radius-and-blur-scales - Les dégradés sont
bg-linear-to-r, plusbg-radialetbg-conic-<angle>. https://tailwindcss.com/docs/background-image#adding-a-linear-gradient containerne centre ni ne padde : écrivezcontainer mx-auto px-4. https://tailwindcss.com/docs/max-width#using-breakpoints-container- Pour les grilles, les dispositions enveloppantes ou les enfants dans un ordre personnalisé, utilisez
gapau lieu despace-x-*etspace-y-*. https://tailwindcss.com/docs/margin#limitations - Les boutons ont
cursor: default. https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor - Les espaces réservés utilisent la couleur de texte courante à 50% d'opacité. https://tailwindcss.com/docs/upgrade-guide#new-default-placeholder-color
- Les classes d'affichage ne remplacent plus l'attribut
hidden: supprimezhiddenpour afficher l'élément. https://tailwindcss.com/docs/upgrade-guide#hidden-attribute-takes-priority
Mode sombre avec une classe
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
// en ligne dans <head>, avant le rendu de la page
document.documentElement.classList.toggle(
"dark",
localStorage.theme === "dark" ||
(!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
Définissez localStorage.theme = "dark" ou "light", et localStorage.removeItem("theme") pour suivre le système. https://tailwindcss.com/docs/dark-mode#with-system-theme-support
Fichiers de référence
| Fichier | À lire quand |
|---|---|
| references/installation-and-frameworks.md | Installation de Tailwind, choix entre Vite, PostCSS ou CLI, étapes spécifiques au framework, modules CSS, outils d'édition |
| references/upgrade-from-v3.md | Migration d'un projet v3, révision de code avec des noms de classes v3 ou une configuration |
| references/utilities-and-variants.md | Écriture de classes : valeurs arbitraires, conflits, variantes d'état, group et peer, responsive, requêtes de conteneur, mode sombre |
| references/theme-and-colors.md | Ajout ou remplacement de couleurs, polices, points d'arrêt, espacements, animations, espaces de noms de thème |
| references/custom-styles.md | Styles de base, Preflight, classes de composants, @utility, utilitaires fonctionnels, @custom-variant, @variant |
| references/directives-and-source-detection.md | @apply, @reference, --alpha(), --spacing(), @config, @plugin, @source, options d'import (préfixe, important, source) |
| references/layout-flexbox-grid.md | Affichage, position, inset, z-index, colonnes, flex, grille, alignement et alignement -safe |
| references/spacing-and-sizing.md | Remplissage, marge, espace, largeur, hauteur, taille, échelle de conteneur, unités de viewport, tailles logiques |
| references/typography.md | Polices, taille de police et hauteur de ligne, espacement des lettres, habillage du texte, overflow wrap, décoration, contenu |
| references/backgrounds-and-borders.md | Dégradés, image de fond, taille et position, rayon, largeur et couleur de bordure, contours |
| references/effects-and-filters.md | Ombres, anneaux, ombre de texte, opacité, modes de fusion, masques, filtres et filtres d'arrière-plan |
| references/transitions-transforms-tables.md | Transitions, transitions discrètes, animations, rotation, échelle, translation, 3D, zoom, tableaux |
| references/interactivity-and-svg.md | Schéma de couleurs, dimensionnement des champs, barres de défilement, défilement magnétique, curseur, will-change, remplissage et contour SVG, couleurs forcées |