# 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.

```php
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.

```css
/* 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:` :

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

### Espaces de noms courants

| Espace de noms | Utilitaires associés |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | utilitaires de la famille `font-*` |
| `--text-*` | utilitaires de taille de police `text-*` |
| `--breakpoint-*` | variantes réactives (`sm:`, `md:`, personnalisées `xs:`) |
| `--spacing-*` | valeurs d’espacement nommées (`p-huge`, `m-huge`) |
| `--radius-*` | utilitaires `rounded-*` |
| `--shadow-*` | utilitaires `shadow-*` |

### 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 :

```css
@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.

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

```css
.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 :

```css
.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` :

```css
@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 :

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

```css
.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()`](https://tailwindphp.inline0.dev/fr/docs/api#twcompile).

### 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](https://tailwindphp.inline0.dev/fr/docs/api).

```php
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é :

```php
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](https://tailwindphp.inline0.dev/fr/docs/api) pour les signatures complètes.

## Étapes suivantes

- [Directives](https://tailwindphp.inline0.dev/fr/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Imports](https://tailwindphp.inline0.dev/fr/docs/usage/imports) — `@import`, modules virtuels et Preflight.
- [API](https://tailwindphp.inline0.dev/fr/docs/api) — tous les accesseurs et toutes les méthodes d’inspection.