# Тема та налаштування

Тема 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` → сімейство 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/uk/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/uk/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/uk/docs/api).

## Наступні кроки

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