Директиви

Директиви — це правила 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. Також підтримується модифікатор важливості (@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-rule.

У варіанті зі списком селекторів для позначення елемента використовується &:

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

hocus:bg-blue-500 генерує правила і для :hover, і для :focus. Форма з атрибутом працює так само:

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

Варіант правила at-rule огортає відповідні утиліти цим правилом:

@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 — налаштування файлів і класів для сканування.