Personnaliser le thème avec @theme

Ce que tu vas apprendre

• Déclarer tes propres couleurs, polices et seuils avec @theme.
• Remplacer les valeurs par défaut au lieu de les compléter.
• Piloter le mode sombre avec une classe ou un attribut.

Où se règle le thème

Avec Tailwind CSS 4, le thème se configure dans ton fichier CSS, juste après l'import. Plus besoin d'un fichier tailwind.config.js par défaut.

@import "tailwindcss";

@theme {
  --color-mint-500: oklch(0.72 0.11 178);
}

La directive @theme déclare des variables de thème : des variables CSS que Tailwind transforme en classes. Ici, --color-mint-500 rend disponibles bg-mint-500, text-mint-500 et fill-mint-500.

Le nom de la variable décide de la classe

Le début du nom, appelé espace de noms, indique quelles classes sont créées :

Si tu écris --color-tomate-600, tu obtiens bg-tomate-600. Tu choisis le nom, Tailwind fabrique les classes.

Ajouter une police et un seuil

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
}

La première ligne crée la classe font-display. La seconde crée le préfixe 3xl:, utilisable comme 3xl:grid-cols-6.

Tu peux aussi changer un seuil existant, par exemple --breakpoint-2xl: 100rem;. Garde la même unité (la rem) pour tous les seuils, sinon l'ordre des classes générées peut se mélanger.

Ajouter ou remplacer

Par défaut, @theme complète le thème existant : bg-red-500 marche toujours. Pour repartir de zéro, vide d'abord l'espace de noms avec initial :

@theme {
  --color-*: initial;
  --color-white: #fff;
  --color-tomate: #d6402b;
  --color-creme: #f5e6d3;
}

Il ne reste alors que bg-white, bg-tomate et bg-creme. Les couleurs par défaut comme bg-red-500 disparaissent.

Changer l'unité d'espacement

L'unité de base des espacements est la variable --spacing, qui vaut 0.25rem par défaut. Tu peux la modifier :

@theme {
  --spacing: 1px;
}

Avec cette valeur, p-4 donnerait 4 px au lieu de 1 rem. Cette réécriture est rare : change-la seulement si tu sais ce que tu fais.

Utiliser une variable existante : inline

Une police chargée par une autre variable CSS peut poser problème. Ajoute le mot inline pour que la classe utilise directement la valeur :

@import "tailwindcss";

@theme inline {
  --font-sans: var(--font-inter);
}

Avec inline, la classe font-sans produit font-family: var(--font-inter);. Sans lui, la valeur peut se résoudre de façon inattendue, à cause de la manière dont les variables CSS se transmettent dans l'arbre HTML.

Utiliser tes variables en CSS

Les variables de thème sont de vraies variables CSS. Tu peux les lire dans ton propre CSS :

.bandeau {
  background-color: var(--color-mint-500);
}

C'est utile pour une règle qui ne se réduit pas à une classe.

Piloter le mode sombre

Par défaut, dark: suit le réglage du système. Pour le déclencher avec une classe dark posée sur la page, redéfinis la variante :

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

Les classes dark: s'appliquent alors quand dark est présente sur l'élément ou sur l'un de ses parents :

<html class="dark">
  <body>
    <div class="bg-white dark:bg-black">...</div>
  </body>
</html>

Un petit script ou un bouton ajoute ou retire cette classe. Pour utiliser un attribut à la place, écris :

@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

À retenir

• Le thème se règle dans le CSS avec @theme, après @import "tailwindcss";.
• Le début du nom de la variable (--color-, --font-, --breakpoint-) détermine les classes créées.
• --color-*: initial; retire les couleurs par défaut avant d'ajouter les tiennes.
• @theme inline fait utiliser la valeur directement, utile pour référencer une autre variable.
• @custom-variant dark permet de piloter le mode sombre par une classe ou un attribut.