# Directives

Les directives sont les règles at préfixées par `@` que vous écrivez dans votre CSS d’entrée pour composer, étendre et ordonner la sortie de Tailwind. Cette page présente `@apply`, `@utility`, `@variant`, `@custom-variant` et `@layer`. `@theme` est présenté dans [Thème](https://tailwindphp.inline0.dev/fr/docs/usage/theme) ; `@plugin` dans [Plugins](https://tailwindphp.inline0.dev/fr/docs/plugins) ; et `@source` dans [@source](https://tailwindphp.inline0.dev/fr/docs/usage/source).

## `@apply`

`@apply` insère les déclarations d’utilitaires existants dans votre propre sélecteur. Utilisez-le pour associer des styles d’utilitaires à une classe sémantique, y compris dans des sélecteurs imbriqués et des requêtes média.

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');
```

Les variantes fonctionnent dans une liste `@apply` : `@apply bg-blue-500 hover:bg-blue-600;` développe l’état `:hover` et les préfixes adaptatifs tels que `@apply px-4 md:px-6 lg:px-8;` émettent les règles `@media` correspondantes. Le modificateur important est également pris en charge (`@apply !flex;`). Les sélecteurs imbriqués sont pris en charge ; une règle comme `.card { h2 { @apply text-xl font-bold; } }` applique donc les utilitaires au `h2` imbriqué.

`@apply` est une instruction : `@apply px-4 { … }` suivie d’un corps provoque une erreur. Une règle `@apply` qui ne contient que des identifiants avec tirets (`@apply --my-mixin;`) est un mixin CSS du brouillon sur les mixins [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), et non une liste d’utilitaires ; TailwindPHP ne la résout donc pas. Mélanger un mixin et des utilitaires dans le même `@apply` provoque une erreur (`You cannot use @apply with both mixins and utilities…`). Les règles de mixin sont actuellement supprimées de la sortie au lieu d’être transmises telles quelles ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` enregistre un utilitaire personnalisé qui participe au moteur de Tailwind : il est trié dans la couche `utilities` et accepte les variantes comme les utilitaires intégrés. Un utilitaire statique utilise un corps fixe :

```css
@utility content-auto {
    content-visibility: auto;
}
```

Comme il s’agit d’un véritable utilitaire, les variantes se composent automatiquement (`hover:content-auto`, `md:content-auto`). Le corps peut lui-même utiliser `@apply` et des sélecteurs imbriqués :

```css
@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}
```

Un utilitaire fonctionnel utilise un suffixe `-*` dans son nom et lit la valeur correspondante avec `--value()` :

```css
@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}
```

`--value()` résout la valeur du candidat à partir de chaque source à tour de rôle : un espace de noms du thème (`--gutter-*`), une valeur arbitraire avec un type de données (`[length]`) ou un type de valeur simple (`integer`, `number`, `percentage`, `ratio`). Toute déclaration dont le `--value()` ne peut pas être résolu est supprimée ; l’enchaînement des déclarations crée donc une chaîne de solutions de repli :

| Classe | Sortie |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

`--modifier()` résout la partie qui suit un `/` de la même façon : avec `line-height: --modifier(integer);` dans le corps, `gutter-4/7` émet aussi `line-height: 7`. Les noms d’utilitaires suivent les règles TailwindCSS v4.3.3 : au plus un `/`, `%` uniquement à la fin après un chiffre, et des points uniquement entre les chiffres.

## `@variant`

`@variant` applique une variante aux déclarations de votre propre CSS, sans définir d’utilitaire :

```css
.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}
```

```css
.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}
```

Les variantes peuvent être empilées (`@variant hover:focus`), séparées par des virgules, imbriquées les unes dans les autres et peuvent désigner vos propres `@custom-variant`s. Un `@variant` de premier niveau sans corps, ou avec `@slot`, est traité comme `@custom-variant` pour assurer la compatibilité ascendante.

## `@custom-variant`

`@custom-variant` définit une nouvelle variante que vous pouvez ajouter en préfixe à n’importe quel utilitaire. La forme compacte nomme la variante et indique un sélecteur ou une règle at-rule entre parenthèses.

Une variante de liste de sélecteurs utilise `&` pour l’élément :

```css
@custom-variant hocus (&:hover, &:focus);
```

`hocus:bg-blue-500` émet alors les règles `:hover` et `:focus`. Une forme avec attribut fonctionne de la même manière :

```css
@custom-variant loading (&[data-loading="true"]);
```

Une variante at-rule enveloppe les utilitaires correspondants dans cette règle at-rule :

```css
@custom-variant tablet (@media (min-width: 600px));
```

Les variantes personnalisées s’empilent avec les variantes intégrées : `sm:hocus:bg-blue-500` imbrique le sélecteur `hocus` dans la requête média `sm`. Pour les cas plus complexes, utilisez la forme bloc et indiquez avec `@slot` où injecter les déclarations de l’utilitaire :

```css
@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}
```

## `@layer`

`@layer` contrôle l’ordre de la cascade à l’aide des couches de cascade natives CSS. Une instruction `@layer` seule déclare l’ordre des couches ; les couches ultérieures l’emportent, quelle que soit la spécificité du sélecteur. L’ordre canonique de Tailwind est :

```css
@layer theme, base, components, utilities;
```

C’est exactement ce que `@import "tailwindcss"` configure en interne. Vous pouvez déclarer votre propre ordre ou le répartir sur plusieurs instructions (`@layer reset, base;` puis `@layer components, utilities;`), et affecter des règles à une couche nommée avec un bloc :

```php
use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');
```

L’ajout de styles de base via `@layer base` les maintient sous `components` et `utilities`, de sorte qu’une classe utilitaire remplace toujours les valeurs par défaut de votre élément. Il en va de même pour `@layer components { … }`, qui sert aux classes de composants devant se trouver sous les utilitaires. Les couches anonymes et les modificateurs `layer()` sur `@import` sont abordés dans [Imports](https://tailwindphp.inline0.dev/fr/docs/usage/imports).

## Étapes suivantes

- [Thème](https://tailwindphp.inline0.dev/fr/docs/usage/theme) — `@theme` les jetons et les fonctions de thème.
- [Imports](https://tailwindphp.inline0.dev/fr/docs/usage/imports) — `@import`, les modules virtuels et les modificateurs `layer()`.
- [Plugins](https://tailwindphp.inline0.dev/fr/docs/plugins) — la directive `@plugin` et le API du plugin.
- [@source](https://tailwindphp.inline0.dev/fr/docs/usage/source) — contrôlez les fichiers et les classes analysés.