Директивы

Директивы — это at-rule с префиксом @, которые добавляют во входной CSS, чтобы комбинировать, расширять и упорядочивать вывод Tailwind. На этой странице описаны @apply, @utility, @variant, @custom-variant и @layer. О @theme рассказывается в разделе Тема, о @plugin — в разделе Плагины, а о @source — в разделе @source.

@apply

@apply вставляет объявления существующих утилит в ваш селектор. Используйте ее, чтобы добавить стили утилит семантическому классу, в том числе во вложенных селекторах и медиазапросах.

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

Варианты можно указывать списком @apply: @apply bg-blue-500 hover:bg-blue-600; раскрывает состояние :hover, а адаптивные префиксы, такие как @apply px-4 md:px-6 lg:px-8;, добавляют соответствующие правила @media. Модификатор important тоже поддерживается (@apply !flex;). Поддерживаются вложенные селекторы, поэтому правило вроде .card { h2 { @apply text-xl font-bold; } } применяет утилиты к вложенному h2.

@apply — оператор: @apply px-4 { … } с телом вызывает ошибку. @apply, содержащий только идентификаторы с дефисами (@apply --my-mixin;), представляет собой миксин CSS из черновика миксинов CSS, а не список утилит, поэтому TailwindPHP его не распознает. Если поместить миксин и утилиты в один @apply, возникнет ошибка (You cannot use @apply with both mixins and utilities…). Сейчас правила миксинов отбрасываются и не передаются дальше (#12).

@utility

@utility регистрирует пользовательскую утилиту, участвующую в механизме Tailwind: она попадает в слой utilities и, как встроенная утилита, поддерживает варианты. У статической утилиты тело фиксировано:

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

Поскольку это полноценная утилита, варианты автоматически комбинируются (hover:content-auto, md:content-auto). В теле можно использовать @apply и вложенные селекторы:

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

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

В имени функциональной утилиты используется суффикс -*, а подходящее значение считывается с помощью --value():

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

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

--value() последовательно проверяет значение кандидата по каждому источнику: пространству имен темы (--gutter-*), произвольному значению с типом данных ([length]) или простому типу значения (integer, number, percentage, ratio). Если значение --value() не разрешается, объявление отбрасывается, поэтому можно выстроить цепочку резервных значений:

--modifier() разрешает часть после / так же: при наличии line-height: --modifier(integer); в теле gutter-4/7 также выводит line-height: 7. Имена утилит соответствуют правилам TailwindCSS v4.3.3: не более одной /, % только в конце после цифры, точки — только между цифрами.

@variant

@variant применяет вариант к объявлениям внутри вашего CSS, не определяя утилиту:

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

Варианты можно комбинировать (@variant hover:focus), перечислять через запятую, вкладывать друг в друга и указывать в них собственные @custom-variant. Вложенный @variant без тела или с @slot для обратной совместимости считается @custom-variant.

@custom-variant

@custom-variant определяет новый вариант, который можно добавлять перед любой утилитой. В краткой форме указывается имя варианта и селектор или at-правило в скобках.

Вариант со списком селекторов использует & для элемента:

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

hocus:bg-blue-500 выводит оба правила: :hover и :focus. Форма с атрибутом работает так же:

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

Вариант с at-правилом оборачивает подходящие утилиты в это правило:

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

Пользовательские варианты можно комбинировать со встроенными: sm:hocus:bg-blue-500 помещает селектор hocus внутрь медиазапроса sm. Для более сложных случаев используйте блочную форму, где @slot указывает место вставки объявлений утилиты:

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

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

@layer

@layer управляет порядком каскада с помощью нативных каскадных слоёв CSS. Оператор @layer без блока объявляет порядок слоёв; более поздние слои имеют приоритет независимо от специфичности селектора. Канонический порядок Tailwind:

@layer theme, base, components, utilities;

Именно это @import "tailwindcss" настраивает внутри. Вы можете объявить собственный порядок или разбить его на несколько операторов (сначала @layer reset, base;, затем @layer components, utilities;), а правила назначить именованному слою с помощью блока:

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

Базовые стили, добавленные через @layer base, остаются ниже components и utilities, поэтому класс-утилита всегда переопределяет значения по умолчанию для элемента. То же относится к @layer components { … } — слоям классов компонентов, которые должны располагаться ниже утилит. Анонимные слои и модификаторы layer() в @import описаны в разделе Импорт.

Следующие шаги

• Тема — @theme токены и функции темы.
• Импорт — @import, виртуальные модули и модификаторы layer().
• Плагины — директива @plugin и API плагина.
• @source — настройка файлов и классов для сканирования.