# Тема и персонализиране

Темата на 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/bg/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/bg/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/bg/docs/api) за пълните сигнатури.

## Следващи стъпки

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