Directivas

Las directivas son reglas at con el prefijo @ que escribes en el archivo de entrada CSS para componer, ampliar y ordenar el resultado de Tailwind. Esta página cubre @apply, @utility, @variant, @custom-variant y @layer. @theme se explica en Tema; @plugin, en Complementos; y @source, en @source.

@apply

@apply inserta las declaraciones de utilidades existentes en tu propio selector. Úsala para aplicar estilos de utilidad a una clase semántica, incluso dentro de selectores anidados y consultas de medios.

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

Las variantes funcionan en una lista @apply: @apply bg-blue-500 hover:bg-blue-600; amplía el estado :hover y los prefijos adaptables como @apply px-4 md:px-6 lg:px-8; generan las reglas @media correspondientes. También se respeta el modificador important (@apply !flex;). Se admiten selectores anidados, por lo que una regla como .card { h2 { @apply text-xl font-bold; } } aplica utilidades al elemento h2 anidado.

@apply es una instrucción: @apply px-4 { … } con un bloque produce un error. Un @apply que solo enumera identificadores con guiones (@apply --my-mixin;) es una mezcla CSS del borrador de mezclas de CSS, no una lista de utilidades, por lo que TailwindPHP no la resuelve; mezclar una mezcla y utilidades en el mismo @apply produce un error (You cannot use @apply with both mixins and utilities…). Actualmente, las reglas de mezcla se descartan en vez de conservarse en el resultado (#12).

@utility

@utility registra una utilidad personalizada que participa en el motor de Tailwind: se ordena en la capa utilities y admite variantes como cualquier utilidad integrada. Una utilidad estática tiene un bloque fijo:

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

Al ser una utilidad real, las variantes se combinan automáticamente (hover:content-auto, md:content-auto). El bloque puede usar @apply y selectores anidados:

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

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

Una utilidad funcional usa un sufijo -* en el nombre y obtiene el valor coincidente con --value():

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

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

--value() resuelve el valor del candidato probando cada fuente por turno: un espacio de nombres del tema (--gutter-*), un valor arbitrario con un tipo de datos ([length]) o un tipo de valor básico (integer, number, percentage, ratio). Si no se resuelve el --value() de una declaración, esta se descarta, así que al apilar declaraciones se crea una cadena alternativa:

--modifier() resuelve la parte posterior a un / de la misma manera: con line-height: --modifier(integer); en el cuerpo, gutter-4/7 también emite line-height: 7. Los nombres de las utilidades siguen las reglas de TailwindCSS v4.3.3: como máximo un /, % solo al final y después de un dígito, y puntos únicamente entre dígitos.

@variant

@variant aplica una variante a las declaraciones dentro de tu propio CSS, sin definir una utilidad:

.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;
  }
}

Las variantes se pueden apilar (@variant hover:focus), enumerar con comas, anidar unas dentro de otras y pueden nombrar tus propios @custom-variants. Un @variant de nivel superior sin cuerpo, o con @slot, se trata como @custom-variant por compatibilidad con versiones anteriores.

@custom-variant

@custom-variant define una variante nueva que puedes anteponer a cualquier utilidad. El formato compacto indica el nombre de la variante y un selector o una regla at en paréntesis.

Una variante de lista de selectores usa & para el elemento:

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

hocus:bg-blue-500 emite entonces las reglas de :hover y :focus. Una forma con atributo funciona igual:

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

Una variante de regla at envuelve las utilidades coincidentes en esa regla:

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

Las variantes personalizadas se apilan con las integradas: sm:hocus:bg-blue-500 anida el selector hocus dentro de la consulta de medios sm. Para casos más complejos, usa el formato de bloque y marca con @slot dónde se insertan las declaraciones de la utilidad:

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

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

@layer

@layer controla el orden de la cascada mediante las capas de cascada nativas de CSS. Una declaración @layer sin bloque declara el orden de las capas; las capas posteriores prevalecen independientemente de la especificidad del selector. El orden canónico de Tailwind es:

@layer theme, base, components, utilities;

Esto es exactamente lo que @import "tailwindcss" configura internamente. Puedes declarar tu propio orden o dividirlo en varias declaraciones (@layer reset, base; y luego @layer components, utilities;), y asignar reglas a una capa con nombre mediante un bloque:

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

Añadir estilos base con @layer base los mantiene por debajo de components y utilities, de modo que una clase de utilidad siempre prevalece sobre los valores predeterminados del elemento. Lo mismo se aplica a @layer components { … } para las clases de componentes que deben quedar por debajo de las utilidades. Las capas anónimas y los modificadores layer() en @import se explican en Imports.

Pasos siguientes

• Theme — tokens @theme y funciones del tema.
• Imports — @import, módulos virtuales y modificadores layer().
• Plugins — la directiva @plugin y el API del complemento.
• @source — controla qué archivos y clases se analizan.