# 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](https://tailwindphp.inline0.dev/es/docs/usage/theme); `@plugin`, en [Complementos](https://tailwindphp.inline0.dev/es/docs/plugins); y `@source`, en [@source](https://tailwindphp.inline0.dev/es/docs/usage/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.

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

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](https://drafts.csswg.org/css-mixins-1/#apply-rule), 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](https://github.com/inline0/tailwindphp/issues/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:

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

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

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

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

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

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

Las variantes se pueden apilar (`@variant hover:focus`), enumerar con comas, anidar unas dentro de otras y pueden nombrar tus propios `@custom-variant`s. 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:

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

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

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

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

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

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

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

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

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](https://tailwindphp.inline0.dev/es/docs/usage/imports).

## Pasos siguientes

- [Theme](https://tailwindphp.inline0.dev/es/docs/usage/theme) — tokens `@theme` y funciones del tema.
- [Imports](https://tailwindphp.inline0.dev/es/docs/usage/imports) — `@import`, módulos virtuales y modificadores `layer()`.
- [Plugins](https://tailwindphp.inline0.dev/es/docs/plugins) — la directiva `@plugin` y el API del complemento.
- [@source](https://tailwindphp.inline0.dev/es/docs/usage/source) — controla qué archivos y clases se analizan.