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; @plugin em Plugins; e @source em @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.

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, 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).

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

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

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

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

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

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

As variantes podem ser encadeadas (@variant hover:focus), listadas com vírgulas, aninhadas umas nas outras e podem nomear seus próprios @custom-variants. 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:

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

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

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

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

@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 é:

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

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.

Próximas etapas

• Tema — @theme tokens e funções do tema.
• Importações — @import, módulos virtuais e modificadores layer().
• Plugins — a diretiva @plugin e a API do plugin.
• @source — controle quais arquivos e classes são analisados.