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

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

## Блок `@theme`

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

```php
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` — они генерируются только при наличии класса в содержимом.

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

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

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

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

| Пространство имён | Создаёт |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | утилиты семейства `font-*` |
| `--text-*` | утилиты размера шрифта `text-*` |
| `--breakpoint-*` | адаптивные варианты (`sm:`, `md:`, пользовательский `xs:`) |
| `--spacing-*` | именованные значения интервалов (`p-huge`, `m-huge`) |
| `--radius-*` | утилиты `rounded-*` |
| `--shadow-*` | утилиты `shadow-*` |

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

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

```css
@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. Она разрешается в значение токена во время компиляции, поэтому её можно использовать везде, где ожидается значение, в том числе в пользовательских правилах и других объявлениях.

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

```css
.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()`, поэтому значение можно переопределить во время выполнения:

```css
.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`:

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

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

```css
.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()`](https://tailwindphp.inline0.dev/ru/docs/api#twcompile).

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

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

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

Три метода доступа возвращают разрешенные значения темы в виде массивов PHP. Каждый принимает необязательную входную строку CSS (по умолчанию `@import "tailwindcss";`) и также доступен в экземпляре [компилятора](https://tailwindphp.inline0.dev/ru/docs/api).

```php
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, чтобы читать значения пользовательской темы:

```php
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](https://tailwindphp.inline0.dev/ru/docs/api).

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

- [Директивы](https://tailwindphp.inline0.dev/ru/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Импорты](https://tailwindphp.inline0.dev/ru/docs/usage/imports) — `@import`, виртуальные модули и Preflight.
- [API](https://tailwindphp.inline0.dev/ru/docs/api) — все методы доступа и проверки.