Direttive

Le direttive sono at-rule precedute da @ che scrivi nel file di input CSS per comporre, estendere e ordinare l'output di Tailwind. Questa pagina tratta @apply, @utility, @variant, @custom-variant e @layer. @theme è descritta in Tema; @plugin in Plugin; e @source in @source.

@apply

@apply integra le dichiarazioni delle utility esistenti nel tuo selettore. Usala per applicare stili di utility a una classe semantica, anche all'interno di selettori annidati e media query.

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;
    }
');

Le varianti funzionano in un elenco @apply: @apply bg-blue-500 hover:bg-blue-600; espande lo stato :hover e prefissi responsive come @apply px-4 md:px-6 lg:px-8; generano le regole @media corrispondenti. È supportato anche il modificatore important (@apply !flex;). Sono supportati i selettori annidati, quindi una regola come .card { h2 { @apply text-xl font-bold; } } applica le utility al selettore h2 annidato.

@apply è un'istruzione: @apply px-4 { … } con un blocco genera un errore. Un @apply che elenca solo identificatori con trattino (@apply --my-mixin;) è un mixin CSS della bozza dei mixin CSS, non un elenco di utility, quindi TailwindPHP non lo risolve; inserire un mixin e utility nello stesso @apply genera un errore (You cannot use @apply with both mixins and utilities…). Attualmente le regole mixin vengono eliminate dall'output anziché essere mantenute (#12).

@utility

@utility registra un'utility personalizzata che partecipa al motore di Tailwind: viene ordinata nel livello utilities e accetta varianti come quelle integrate. Un'utility statica ha un blocco fisso:

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

Essendo una vera utility, le varianti si combinano automaticamente (hover:content-auto, md:content-auto). Il blocco può usare a sua volta @apply e selettori annidati:

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

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

Un'utility funzionale usa un suffisso -* nel nome e legge il valore corrispondente con --value():

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

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

--value() risolve il valore del candidato confrontandolo, in ordine, con ciascuna fonte: uno spazio dei nomi del tema (--gutter-*), un valore arbitrario con un tipo di dato ([length]) oppure un tipo di valore semplice (integer, number, percentage, ratio). Una dichiarazione il cui --value() non viene risolto viene eliminata, quindi dichiarazioni in sequenza creano una catena di fallback:

--modifier() risolve la parte dopo un / allo stesso modo: con line-height: --modifier(integer); nel body, gutter-4/7 emette anche line-height: 7. I nomi delle utility seguono le regole TailwindCSS v4.3.3: al massimo un /, % solo alla fine dopo una cifra e punti solo tra cifre.

@variant

@variant applica una variante alle dichiarazioni nel tuo CSS, senza definire un'utility:

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

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

Le varianti possono essere concatenate (@variant hover:focus), elencate con virgole, annidate e possono indicare i tuoi @custom-variant. Un @variant di primo livello senza body, o con @slot, viene trattato come @custom-variant per compatibilità con le versioni precedenti.

@custom-variant

@custom-variant definisce una nuova variante da anteporre a qualsiasi utility. La forma compatta indica il nome della variante e fornisce un selettore o una at-rule tra parentesi.

Una variante con elenco di selettori usa & per l'elemento:

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

hocus:bg-blue-500 emette quindi sia le regole :hover sia :focus. La forma con attributo funziona allo stesso modo:

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

Una variante at-rule racchiude le utility corrispondenti in quella at-rule:

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

Le varianti personalizzate si concatenano con quelle integrate: sm:hocus:bg-blue-500 annida il selettore hocus nella media query sm. Per i casi più complessi, usa la forma a blocco, dove @slot indica il punto in cui inserire le dichiarazioni dell'utility:

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

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

@layer

@layer controlla l'ordine della cascata usando i livelli di cascata nativi di CSS. Un'istruzione @layer senza blocco dichiara l'ordine dei livelli; quelli successivi prevalgono indipendentemente dalla specificità del selettore. L'ordine canonico di Tailwind è:

@layer theme, base, components, utilities;

È esattamente ciò che @import "tailwindcss" configura internamente. Puoi dichiarare un tuo ordine oppure suddividerlo in più istruzioni (@layer reset, base; poi @layer components, utilities;) e assegnare le regole a un livello con nome usando un blocco:

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; }
    }
');

Aggiungere stili di base con @layer base li mantiene al di sotto di components e utilities, così una classe utility prevale sempre sui valori predefiniti dell'elemento. Lo stesso vale per @layer components { … }, per le classi dei componenti che devono stare sotto le utility. I livelli anonimi e i modificatori layer() su @import sono trattati in Importazioni.

Passaggi successivi

• Tema — @theme token e funzioni del tema.
• Importazioni — @import, moduli virtuali e modificatori layer().
• Plugin — la direttiva @plugin e API del plugin.
• @source — controlla quali file e classi vengono analizzati.