# Diretivas

As diretivas são regras at com prefixo `@` que você escreve no CSS de entrada para compor, estender e ordenar a saída de Tailwind. Esta página aborda `@apply`, `@utility`, `@variant`, `@custom-variant` e `@layer`. `@theme` é abordada em [Tema](https://tailwindphp.inline0.dev/pt/docs/usage/theme); `@plugin` em [Plugins](https://tailwindphp.inline0.dev/pt/docs/plugins); e `@source` em [@source](https://tailwindphp.inline0.dev/pt/docs/usage/source).

## `@apply`

`@apply` incorpora as declarações de utilitários existentes ao seu próprio seletor. Use-a para associar estilos utilitários a uma classe semântica, inclusive dentro de seletores aninhados e consultas de 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;
    }
');
```

As variantes funcionam em uma lista `@apply` — `@apply bg-blue-500 hover:bg-blue-600;` expande o estado `:hover`, e prefixos responsivos como `@apply px-4 md:px-6 lg:px-8;` emitem as regras `@media` correspondentes. O modificador de importância também é respeitado (`@apply !flex;`). Há suporte a seletores aninhados; assim, uma regra como `.card { h2 { @apply text-xl font-bold; } }` aplica utilitários ao `h2` aninhado.

`@apply` é uma instrução: `@apply px-4 { … }` com um corpo gera um erro. Um `@apply` que lista apenas identificadores com hífen (`@apply --my-mixin;`) é um mixin CSS do rascunho de mixins [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), não uma lista de utilitários; por isso, TailwindPHP não o resolve. Colocar um mixin e utilitários no mesmo `@apply` gera um erro (`You cannot use @apply with both mixins and utilities…`). Atualmente, as regras de mixin são descartadas da saída em vez de serem repassadas ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` registra um utilitário personalizado que participa do mecanismo de Tailwind — ele é ordenado na camada `utilities` e aceita variantes como qualquer utilitário integrado. Um utilitário estático tem um corpo fixo:

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

Por ser um utilitário de verdade, as variantes são compostas automaticamente (`hover:content-auto`, `md:content-auto`). O corpo também pode usar `@apply` e seletores aninhados:

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

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

Um utilitário funcional usa um sufixo `-*` no nome e lê o valor correspondente com `--value()`:

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

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

`--value()` resolve o valor candidato em cada fonte, na ordem: um namespace do tema (`--gutter-*`), um valor arbitrário com tipo de dado (`[length]`) ou um tipo de valor simples (`integer`, `number`, `percentage`, `ratio`). Uma declaração cujo `--value()` não é resolvido é descartada; por isso, empilhar declarações cria uma cadeia de fallback:

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

`--modifier()` resolve a parte após um `/` da mesma forma: com `line-height: --modifier(integer);` no corpo, `gutter-4/7` também emite `line-height: 7`. Os nomes das utilidades seguem as regras de TailwindCSS v4.3.3: no máximo um `/`, `%` apenas no final, após um dígito, e pontos apenas entre dígitos.

## `@variant`

`@variant` aplica uma variante às declarações dentro do seu próprio CSS, sem definir uma utilidade:

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

As variantes podem ser encadeadas (`@variant hover:focus`), listadas com vírgulas, aninhadas umas nas outras e podem nomear seus próprios `@custom-variant`s. Um `@variant` de nível superior sem corpo, ou com `@slot`, é tratado como `@custom-variant` para manter a compatibilidade com versões anteriores.

## `@custom-variant`

`@custom-variant` define uma nova variante que você pode prefixar a qualquer utilidade. O formato compacto nomeia a variante e fornece um seletor ou uma regra at-rule entre parênteses.

Uma variante de lista de seletores usa `&` para o elemento:

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

`hocus:bg-blue-500` então emite as regras `:hover` e `:focus`. Uma forma com atributo funciona da mesma maneira:

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

Uma variante de regra at-rule envolve as utilidades correspondentes nessa regra:

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

As variantes personalizadas podem ser encadeadas com as integradas — `sm:hocus:bg-blue-500` aninha o seletor `hocus` dentro da consulta de mídia `sm`. Para casos mais complexos, use o formato de bloco, com `@slot` indicando onde as declarações da utilidade são inseridas:

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

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

## `@layer`

`@layer` controla a ordem da cascata usando camadas nativas de cascata do CSS. Uma instrução `@layer` sem bloco declara a ordem das camadas; as camadas posteriores têm prioridade, independentemente da especificidade do seletor. A ordem canônica de Tailwind é:

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

É exatamente isso que `@import "tailwindcss"` configura internamente. Você pode declarar sua própria ordem ou dividi-la em várias instruções (`@layer reset, base;` e depois `@layer components, utilities;`), e atribuir regras a uma camada nomeada com um bloco:

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

Adicionar estilos base por meio de `@layer base` os mantém abaixo de `components` e `utilities`, assim uma classe de utilidade sempre sobrescreve os padrões do elemento. O mesmo vale para `@layer components { … }`, para classes de componentes que devem ficar abaixo das utilidades. Camadas anônimas e modificadores `layer()` em `@import` são abordados em [Importações](https://tailwindphp.inline0.dev/pt/docs/usage/imports).

## Próximas etapas

- [Tema](https://tailwindphp.inline0.dev/pt/docs/usage/theme) — `@theme` tokens e funções do tema.
- [Importações](https://tailwindphp.inline0.dev/pt/docs/usage/imports) — `@import`, módulos virtuais e modificadores `layer()`.
- [Plugins](https://tailwindphp.inline0.dev/pt/docs/plugins) — a diretiva `@plugin` e a API do plugin.
- [@source](https://tailwindphp.inline0.dev/pt/docs/usage/source) — controle quais arquivos e classes são analisados.