Thème et personnalisation

Le thème de Tailwind est un ensemble plat de variables CSS. Vous pouvez l’étendre ou le remplacer avec un bloc @theme { … } dans votre CSS d’entrée, référencer ces valeurs dans CSS à l’aide des fonctions de thème, puis récupérer les valeurs résolues depuis PHP. Aucun fichier de configuration JavaScript n’est nécessaire : le thème se trouve entièrement dans CSS.

Le bloc @theme

Un bloc @theme déclare des jetons de conception sous forme de propriétés personnalisées CSS. Le préfixe d’espace de noms de chaque variable (--color-*, --font-*, --breakpoint-*, --spacing-*, …) indique à Tailwind quels utilitaires et variantes le jeton alimente.

use TailwindPHP\tw;

$css = tw::generate('<div class="bg-brand text-brand xs:flex">', '
    @import "tailwindcss";

    @theme {
        --color-brand: #3b82f6;
        --font-heading: "Inter", sans-serif;
        --breakpoint-xs: 20rem;
        --spacing-huge: 10rem;
    }
');

Chaque jeton enregistre des utilitaires sous son espace de noms. L’exemple ci-dessus rend disponibles bg-brand, text-brand, border-brand, la famille font-heading, une variante réactive xs: et les espacements p-huge/m-huge — générés uniquement si la classe apparaît dans votre contenu.

/* bg-brand resolves to the theme variable */
:root, :host {
  --color-brand: #3b82f6;
}
.bg-brand {
  background-color: var(--color-brand);
}

Le jeton --breakpoint-xs enregistre directement la variante xs: :

@media (min-width: 20rem) {
  .xs\:flex {
    display: flex;
  }
}

Espaces de noms courants

Effacer un espace de noms

Définir le joker d’un espace de noms sur initial supprime les valeurs par défaut de Tailwind pour cet espace avant l’ajout de vos propres jetons. Vous pouvez ainsi partir d’une palette vierge :

@theme {
    /* Drop every default color, then define only what you need */
    --color-*: initial;
    --color-brand: #3b82f6;
    --color-ink: #111827;
}

--*: initial; efface tout le thème. La valeur initial appliquée à une clé sans joker (--color-red-500: initial;) supprime uniquement ce jeton. Seul initial est accepté comme valeur d’un joker -* ; toute autre valeur provoque une erreur.

Lire les valeurs de thème dans CSS

theme()

La fonction héritée theme() lit une valeur à l’aide de la notation par points dans les espaces de noms de type v3. Elle résout la valeur du jeton lors de la compilation ; elle peut donc être utilisée partout où une valeur est attendue, y compris dans les règles personnalisées et les autres déclarations.

$css = tw::generate('<div class="callout">', '
    @import "tailwindcss";
    .callout { color: theme(colors.red.500); }
');

.callout {
  color: oklch(63.7% .237 25.331);
}

Les chemins par points correspondent aux variables sous-jacentes (colors.red.500 → --color-red-500, fontFamily.sans → la famille sans empattement). Un modificateur d’opacité est pris en charge : theme(colors.red.500 / 50%). Une valeur de repli peut être transmise en deuxième argument : theme(colors.brand, #000). Si un chemin ne peut pas être résolu et qu’aucune valeur de repli n’est fournie, la valeur candidate qui l’utilise est abandonnée.

--theme()

--theme() lit une variable de thème à partir de son nom de propriété personnalisée CSS et renvoie par défaut une référence var(), afin que la valeur reste modifiable à l’exécution :

.btn { color: --theme(--color-brand); }
/* → color: var(--color-brand); */

Ajoutez inline pour substituer la valeur résolue à une référence var() : --theme(--color-brand inline). Le deuxième argument correspond à une valeur de repli (--theme(--color-brand, #000)), et une valeur de repli initial est traitée spécialement : elle est injectée dans les références var() imbriquées qui se résolvent elles-mêmes en initial. Dans une règle at (@media, @container), --theme() est toujours résolu en ligne, car var() n’est pas valide dans ces préambules.

--spacing()

--spacing(n) multiplie l’unité d’espacement de base du thème (--spacing) par n :

@utility my-gap { gap: --spacing(4); }
/* → gap: calc(var(--spacing) * 4); */

Un multiplicateur de 1 se résout en la variable de base elle-même (--spacing(1) → var(--spacing), ce que produit aussi p-1), tandis que 0 se résout en une longueur nulle simple.

C’est le même calcul que celui utilisé par les utilitaires d’espacement intégrés ; les valeurs personnalisées restent donc cohérentes avec p-4, m-4 et les autres.

--alpha()

--alpha(color / opacity) applique une opacité à une couleur à l’aide d’un color-mix() dans l’espace colorimétrique oklab :

@utility tint { color: --alpha(var(--color-red-500) / 50%); }

.tint {
  color: #fb2c3680;
}
@supports (color: color-mix(in lab, red, red)) {
  .tint {
    color: color-mix(in oklab, var(--color-red-500) 50%, transparent);
  }
}

La forme color-mix() reste modifiable à l’exécution ; la valeur de repli statique qui la précède, calculée à partir de la valeur du thème, prend en charge les navigateurs sans color-mix(). Désactivez cette valeur de repli avec l’option polyfills de tw::compile().

Combiner l’opacité et color-mix() → oklab()

Les modificateurs d’opacité se composent. Appliquer 50 % à une valeur qui comporte déjà 50 % donne 25 %, calculé dans oklab. Lorsqu’un modificateur d’opacité s’applique à une couleur statique, TailwindPHP réduit l’expression color-mix(in oklab, …) à une valeur oklab() concrète — comme le fait lightningcss dans la chaîne d’outils Tailwind en amont — tandis que les couleurs dynamiques (celles qui sont toujours enveloppées dans var()) conservent la forme color-mix() afin de rester modifiables à l’exécution.

Lire les valeurs du thème depuis PHP

Trois accesseurs renvoient les valeurs résolues du thème sous forme de tableaux PHP. Chacun accepte une chaîne d’entrée CSS facultative (@import "tailwindcss"; par défaut) et est également disponible sur une instance du compilateur.

use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']

Transmettez une chaîne CSS pour lire les valeurs d’un thème personnalisé :

tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']

TailwindCSS 4 utilise une seule valeur de base --spacing au lieu d’une échelle --spacing-* ; tw::spacing() ne renvoie donc que les jetons personnalisés --spacing-* que vous définissez. Les mêmes méthodes existent sur une instance du compilateur : $compiler->colors(), $compiler->breakpoints(), $compiler->spacing(). Consultez les API pour les signatures complètes.

Étapes suivantes

• Directives — @apply, @utility, @custom-variant, @layer.
• Imports — @import, modules virtuels et Preflight.
• API — tous les accesseurs et toutes les méthodes d’inspection.