# Директивы

Директивы — это at-rule с префиксом `@`, которые добавляют во входной CSS, чтобы комбинировать, расширять и упорядочивать вывод Tailwind. На этой странице описаны `@apply`, `@utility`, `@variant`, `@custom-variant` и `@layer`. О `@theme` рассказывается в разделе [Тема](https://tailwindphp.inline0.dev/ru/docs/usage/theme), о `@plugin` — в разделе [Плагины](https://tailwindphp.inline0.dev/ru/docs/plugins), а о `@source` — в разделе [@source](https://tailwindphp.inline0.dev/ru/docs/usage/source).

## `@apply`

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

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

Варианты можно указывать списком `@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](https://drafts.csswg.org/css-mixins-1/#apply-rule), а не список утилит, поэтому TailwindPHP его не распознает. Если поместить миксин и утилиты в один `@apply`, возникнет ошибка (`You cannot use @apply with both mixins and utilities…`). Сейчас правила миксинов отбрасываются и не передаются дальше ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

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

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

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

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

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

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

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

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

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

| Класс | Результат |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

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

## `@variant`

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

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

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

## `@custom-variant`

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

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

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

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

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

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

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

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

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

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

## `@layer`

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

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

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

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

Базовые стили, добавленные через `@layer base`, остаются ниже `components` и `utilities`, поэтому класс-утилита всегда переопределяет значения по умолчанию для элемента. То же относится к `@layer components { … }` — слоям классов компонентов, которые должны располагаться ниже утилит. Анонимные слои и модификаторы `layer()` в `@import` описаны в разделе [Импорт](https://tailwindphp.inline0.dev/ru/docs/usage/imports).

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

- [Тема](https://tailwindphp.inline0.dev/ru/docs/usage/theme) — `@theme` токены и функции темы.
- [Импорт](https://tailwindphp.inline0.dev/ru/docs/usage/imports) — `@import`, виртуальные модули и модификаторы `layer()`.
- [Плагины](https://tailwindphp.inline0.dev/ru/docs/plugins) — директива `@plugin` и API плагина.
- [@source](https://tailwindphp.inline0.dev/ru/docs/usage/source) — настройка файлов и классов для сканирования.