Тема и настройка

Тема Tailwind — это плоский набор переменных CSS. Расширяйте или переопределяйте её блоком @theme { … } во входном CSS, используйте эти значения внутри CSS с помощью функций темы и получайте разрешённые значения из PHP. Файл конфигурации JavaScript не нужен — тема целиком хранится в CSS.

Блок @theme

Блок @theme задаёт токены дизайна как пользовательские свойства CSS. Префикс пространства имён каждой переменной (--color-*, --font-*, --breakpoint-*, --spacing-*, …) сообщает Tailwind, какие утилиты и варианты связаны с этим токеном.

use TailwindPHP\tw;

$css = tw::generate('<div class="bg-brand text-brand xs:flex">', '
    @import "tailwindcss";

    @theme {
        --color-brand: #3b82f6;
        --font-heading: "Inter", sans-serif;
        --breakpoint-xs: 20rem;
        --spacing-huge: 10rem;
    }
');

Каждый токен регистрирует утилиты в своём пространстве имён. Пример выше создаёт bg-brand, text-brand, border-brand, семейство font-heading, адаптивный вариант xs: и интервалы p-huge/m-huge — они генерируются только при наличии класса в содержимом.

/* bg-brand resolves to the theme variable */
:root, :host {
  --color-brand: #3b82f6;
}
.bg-brand {
  background-color: var(--color-brand);
}

Токен --breakpoint-xs напрямую регистрирует вариант xs::

@media (min-width: 20rem) {
  .xs\:flex {
    display: flex;
  }
}

Распространённые пространства имён

Очистка пространства имён

Значение initial для подстановочного знака пространства имён удаляет стандартные значения Tailwind для этого пространства перед добавлением ваших токенов. Так можно начать с чистой палитры:

@theme {
    /* Drop every default color, then define only what you need */
    --color-*: initial;
    --color-brand: #3b82f6;
    --color-ink: #111827;
}

--*: initial; очищает всю тему. Значение initial для ключа без подстановочного знака (--color-red-500: initial;) удаляет только этот токен. Для подстановочного знака -* допустимо только значение initial; любое другое вызовет ошибку.

Чтение значений темы в CSS

theme()

Устаревшая функция theme() читает значение через запись с точками в пространствах имён стиля v3. Она разрешается в значение токена во время компиляции, поэтому её можно использовать везде, где ожидается значение, в том числе в пользовательских правилах и других объявлениях.

$css = tw::generate('<div class="callout">', '
    @import "tailwindcss";
    .callout { color: theme(colors.red.500); }
');

.callout {
  color: oklch(63.7% .237 25.331);
}

Пути с точками указывают на соответствующие переменные (colors.red.500 → --color-red-500, fontFamily.sans → семейство без засечек). Поддерживается модификатор прозрачности: theme(colors.red.500 / 50%). Резервное значение можно передать вторым аргументом: theme(colors.brand, #000). Если путь не удается разрешить и резервное значение не задано, кандидат, в котором он используется, отбрасывается.

--theme()

--theme() читает переменную темы по имени ее пользовательского свойства CSS и по умолчанию возвращает ссылку var(), поэтому значение можно переопределить во время выполнения:

.btn { color: --theme(--color-brand); }
/* → color: var(--color-brand); */

Добавьте inline, чтобы подставить разрешенное значение вместо ссылки var(): --theme(--color-brand inline). Второй аргумент задает резервное значение (--theme(--color-brand, #000)), а резервное значение initial обрабатывается особым образом: оно подставляется во вложенные ссылки var(), которые сами разрешаются в initial. Внутри правила at-rule (@media, @container) значение --theme() всегда подставляется напрямую, поскольку var() недопустим в таких преамбулах.

--spacing()

--spacing(n) умножает базовую единицу интервала темы (--spacing) на n:

@utility my-gap { gap: --spacing(4); }
/* → gap: calc(var(--spacing) * 4); */

Множитель 1 разрешается в саму базовую переменную (--spacing(1) → var(--spacing), что также выдает p-1), а 0 — в нулевую длину без единиц измерения.

Это тот же расчет, который используют встроенные утилиты интервалов, поэтому пользовательские значения согласуются с p-4, m-4 и другими.

--alpha()

--alpha(color / opacity) применяет прозрачность к цвету с помощью color-mix() в цветовом пространстве oklab:

@utility tint { color: --alpha(var(--color-red-500) / 50%); }

.tint {
  color: #fb2c3680;
}
@supports (color: color-mix(in lab, red, red)) {
  .tint {
    color: color-mix(in oklab, var(--color-red-500) 50%, transparent);
  }
}

Форма color-mix() остается переопределяемой во время выполнения; расположенное перед ней статическое резервное значение, вычисленное на основе значения темы, поддерживает браузеры без color-mix(). Отключить резервное значение можно параметром polyfills в tw::compile().

Сочетание прозрачности и color-mix() → oklab()

Модификаторы прозрачности сочетаются. Если применить 50% к значению, которое уже имеет прозрачность 50%, получится 25%, вычисленное в oklab. Когда модификатор прозрачности применяется к статическому цвету, TailwindPHP сводит выражение color-mix(in oklab, …) к конкретному значению oklab() — так же, как это делает lightningcss в исходной цепочке инструментов Tailwind. Динамические цвета, которые по-прежнему обернуты в var(), сохраняют форму color-mix(), чтобы их можно было переопределять во время выполнения.

Чтение значений темы из PHP

Три метода доступа возвращают разрешенные значения темы в виде массивов PHP. Каждый принимает необязательную входную строку CSS (по умолчанию @import "tailwindcss";) и также доступен в экземпляре компилятора.

use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']

Передайте строку CSS, чтобы читать значения пользовательской темы:

tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']

TailwindCSS 4 использует одно базовое значение --spacing вместо шкалы --spacing-*, поэтому tw::spacing() возвращает только заданные вами пользовательские токены --spacing-*. Те же методы доступны и в экземпляре компилятора: $compiler->colors(), $compiler->breakpoints(), $compiler->spacing(). Полные сигнатуры см. в API.

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

• Директивы — @apply, @utility, @custom-variant, @layer.
• Импорты — @import, виртуальные модули и Preflight.
• API — все методы доступа и проверки.