# Motyw i dostosowywanie

Motyw Tailwind to płaski zestaw zmiennych CSS. Rozszerzaj go lub zastępuj blokiem `@theme { … }` w wejściowym CSS, odwołuj się do tych wartości wewnątrz CSS za pomocą funkcji motywu, a rozpoznane wartości odczytuj z powrotem z PHP. Nie ma pliku konfiguracyjnego JavaScript — motyw znajduje się w całości w CSS.

## Blok `@theme`

Blok `@theme` deklaruje tokeny projektowe jako niestandardowe właściwości CSS. Prefiks przestrzeni nazw każdej zmiennej (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) wskazuje Tailwind, które narzędzia i warianty korzystają z danego tokenu.

```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;
    }
');
```

Każdy token rejestruje narzędzia w swojej przestrzeni nazw. Powyższy przykład udostępnia `bg-brand`, `text-brand`, `border-brand`, rodzinę `font-heading`, wariant responsywny `xs:` oraz odstępy `p-huge`/`m-huge` — generowane wyłącznie wtedy, gdy klasa występuje w treści.

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

Token `--breakpoint-xs` bezpośrednio rejestruje wariant `xs:`:

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

### Typowe przestrzenie nazw

| Przestrzeń nazw | Udostępnia |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | narzędzia z rodziny `font-*` |
| `--text-*` | narzędzia rozmiaru czcionki `text-*` |
| `--breakpoint-*` | warianty responsywne (`sm:`, `md:`, niestandardowy `xs:`) |
| `--spacing-*` | nazwane wartości odstępów (`p-huge`, `m-huge`) |
| `--radius-*` | narzędzia `rounded-*` |
| `--shadow-*` | narzędzia `shadow-*` |

### Czyszczenie przestrzeni nazw

Ustawienie symbolu wieloznacznego przestrzeni nazw na `initial` usuwa domyślne wartości Tailwind dla tej przestrzeni przed dodaniem własnych tokenów. Dzięki temu możesz zacząć od czystej palety:

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

`--*: initial;` czyści cały motyw. Pojedyncza wartość `initial` w kluczu innym niż symbol wieloznaczny (`--color-red-500: initial;`) usuwa tylko ten token. Dla symbolu wieloznacznego `-*` akceptowana jest wyłącznie wartość `initial` — każda inna powoduje błąd.

## Odczytywanie wartości motywu w CSS

### `theme()`

Starsza funkcja `theme()` odczytuje wartość na podstawie notacji kropkowej i przestrzeni nazw w stylu v3. Rozpoznaje wartość tokenu podczas kompilacji, więc można jej używać wszędzie tam, gdzie oczekiwana jest wartość — także w regułach niestandardowych i innych deklaracjach.

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

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

Ścieżki kropkowe odpowiadają bazowym zmiennym (`colors.red.500` → `--color-red-500`, `fontFamily.sans` → rodzina bezszeryfowa). Obsługiwany jest modyfikator krycia: `theme(colors.red.500 / 50%)`. Wartość zastępczą można przekazać jako drugi argument: `theme(colors.brand, #000)`. Jeśli ścieżki nie można rozpoznać i nie podano wartości zastępczej, kandydat, który jej używa, zostaje pominięty.

### `--theme()`

`--theme()` odczytuje zmienną motywu na podstawie jej nazwy niestandardowej właściwości CSS i domyślnie zwraca odwołanie `var()`, dzięki czemu wartość można nadpisywać w czasie działania programu:

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

Dodaj `inline`, aby wstawić rozpoznaną wartość zamiast odwołania `var()`: `--theme(--color-brand inline)`. Drugi argument to wartość zastępcza (`--theme(--color-brand, #000)`), a wartość zastępcza `initial` jest obsługiwana specjalnie — wstawiana jest do zagnieżdżonych odwołań `var()`, które same mają wartość `initial`. Wewnątrz reguł at (`@media`, `@container`) `--theme()` zawsze jest rozwijana bezpośrednio, ponieważ `var()` jest nieprawidłowe w tych przedrostkach.

### `--spacing()`

`--spacing(n)` mnoży podstawową jednostkę odstępu motywu (`--spacing`) przez `n`:

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

Mnożnik `1` odpowiada samej zmiennej bazowej (`--spacing(1)` → `var(--spacing)`, co emituje również `p-1`), a `0` — zwykłej długości równej zero.

To te same obliczenia, których używają wbudowane narzędzia odstępów, dzięki czemu niestandardowe wartości pozostają zgodne z `p-4`, `m-4` i podobnymi.

### `--alpha()`

`--alpha(color / opacity)` stosuje krycie do koloru za pomocą `color-mix()` w przestrzeni barw 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);
  }
}
```

Postać `color-mix()` pozostaje możliwa do nadpisania w czasie działania programu; poprzedzająca ją statyczna wartość zastępcza, obliczona na podstawie wartości motywu, obsługuje przeglądarki bez `color-mix()`. Wyłącz wartość zastępczą opcją `polyfills` w [`tw::compile()`](https://tailwindphp.inline0.dev/pl/docs/api#twcompile).

### Łączenie krycia i `color-mix()` → `oklab()`

Modyfikatory krycia łączą się. Zastosowanie wartości 50% do wartości, która już ma krycie 50%, daje 25% obliczone w oklab. Gdy modyfikator krycia jest stosowany do koloru statycznego, TailwindPHP upraszcza wyrażenie `color-mix(in oklab, …)` do konkretnej wartości `oklab()` — tak samo jak lightningcss w nadrzędnym łańcuchu narzędzi Tailwind — natomiast kolory dynamiczne (wciąż opakowane w `var()`) zachowują postać `color-mix()`, dzięki czemu nadal można je nadpisywać w czasie działania programu.

## Odczytywanie wartości motywu z PHP

Trzy metody dostępu zwracają rozpoznane wartości motywu jako tablice PHP. Każda przyjmuje opcjonalny ciąg wejściowy CSS (domyślnie `@import "tailwindcss";`) i jest również dostępna w instancji [kompilatora](https://tailwindphp.inline0.dev/pl/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']
```

Przekaż ciąg CSS, aby odczytać wartości z dostosowanego motywu:

```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 używa jednej bazowej wartości `--spacing` zamiast skali `--spacing-*`, dlatego `tw::spacing()` zwraca tylko zdefiniowane przez Ciebie niestandardowe tokeny `--spacing-*`. Te same metody są dostępne w instancji kompilatora: `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`. Pełne sygnatury znajdziesz w [API](https://tailwindphp.inline0.dev/pl/docs/api).

## Następne kroki

- [Dyrektywy](https://tailwindphp.inline0.dev/pl/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Importy](https://tailwindphp.inline0.dev/pl/docs/usage/imports) — `@import`, moduły wirtualne i Preflight.
- [API](https://tailwindphp.inline0.dev/pl/docs/api) — wszystkie metody dostępu i inspekcji.