# Temă și personalizare

Tema Tailwind este un set plat de variabile CSS. O extindeți sau o înlocuiți cu un bloc `@theme { … }` în intrarea CSS, faceți referire la valorile respective din CSS prin funcțiile temei și citiți valorile rezolvate din PHP. Nu există un fișier de configurare JavaScript — tema se află în întregime în CSS.

## Blocul `@theme`

Un bloc `@theme` declară tokenuri de design ca proprietăți personalizate CSS. Prefixul spațiului de nume pentru fiecare variabilă (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) îi indică lui Tailwind ce utilitare și variante folosește tokenul.

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

Fiecare token înregistrează utilitare sub spațiul său de nume. Exemplul de mai sus face disponibile `bg-brand`, `text-brand`, `border-brand`, familia `font-heading`, o variantă adaptivă `xs:` și valorile de spațiere `p-huge`/`m-huge` — generate doar când clasa apare în conținutul dvs.

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

Tokenul `--breakpoint-xs` înregistrează direct varianta `xs:`:

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

### Spații de nume uzuale

| Spațiu de nume | Oferă |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | utilitare din familia `font-*` |
| `--text-*` | utilitare pentru dimensiunea fontului `text-*` |
| `--breakpoint-*` | variante adaptive (`sm:`, `md:`, `xs:` personalizată) |
| `--spacing-*` | valori de spațiere cu nume (`p-huge`, `m-huge`) |
| `--radius-*` | utilitare `rounded-*` |
| `--shadow-*` | utilitare `shadow-*` |

### Golirea unui spațiu de nume

Setarea unui wildcard pentru spațiul de nume la `initial` elimină valorile implicite Tailwind pentru acel spațiu înainte de adăugarea propriilor tokenuri. Astfel puteți porni de la o paletă curată:

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

`--*: initial;` golește întreaga temă. O singură valoare `initial` pentru o cheie fără wildcard (`--color-red-500: initial;`) elimină doar acel token. Pentru valoarea unui wildcard `-*` este acceptat doar `initial` — orice altă valoare este o eroare.

## Citirea valorilor temei în CSS

### `theme()`

Funcția veche `theme()` citește o valoare folosind notația cu puncte în spațiile de nume de tip v3. Rezolvă valoarea tokenului în timpul compilării, deci poate fi folosită oriunde este așteptată o valoare — inclusiv în reguli personalizate și alte declarații.

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

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

Căile cu puncte corespund variabilelor subiacente (`colors.red.500` → `--color-red-500`, `fontFamily.sans` → familia sans). Este acceptat un modificator de opacitate: `theme(colors.red.500 / 50%)`. Se poate transmite o valoare de rezervă ca al doilea argument: `theme(colors.brand, #000)`. Dacă o cale nu poate fi rezolvată și nu se furnizează nicio valoare de rezervă, candidatul care o folosește este eliminat.

### `--theme()`

`--theme()` citește o variabilă a temei după numele proprietății personalizate CSS și returnează implicit o referință `var()`, astfel încât valoarea poate fi suprascrisă în timpul execuției:

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

Adăugați `inline` pentru a substitui valoarea rezolvată în locul unei referințe `var()`: `--theme(--color-brand inline)`. Al doilea argument este o valoare de rezervă (`--theme(--color-brand, #000)`), iar o valoare de rezervă `initial` este tratată special — este inserată în referințele `var()` imbricate care se rezolvă la `initial`. Într-o regulă at (`@media`, `@container`), `--theme()` se rezolvă întotdeauna în linie, deoarece `var()` nu este valid în aceste preambuluri.

### `--spacing()`

`--spacing(n)` înmulțește unitatea de spațiere de bază a temei (`--spacing`) cu `n`:

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

Un multiplicator de `1` se rezolvă la variabila de bază însăși (`--spacing(1)` → `var(--spacing)`, exact ce emite și `p-1`), iar `0` la o lungime simplă de zero.

Acesta este același calcul folosit de utilitarele de spațiere încorporate, astfel încât valorile personalizate rămân coerente cu `p-4`, `m-4` și celelalte.

### `--alpha()`

`--alpha(color / opacity)` aplică opacitate unei culori folosind un `color-mix()` în spațiul de culoare 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);
  }
}
```

Forma `color-mix()` poate fi suprascrisă în timpul execuției; valoarea statică de rezervă dinaintea ei, calculată pe baza valorii temei, acoperă browserele fără `color-mix()`. Dezactivați valoarea de rezervă cu opțiunea `polyfills` din [`tw::compile()`](https://tailwindphp.inline0.dev/ro/docs/api#twcompile).

### Combinarea opacității și `color-mix()` → `oklab()`

Modificatorii de opacitate se compun. Aplicarea unei opacități de 50% unei valori care are deja 50% produce 25%, calculat în oklab. Când un modificator de opacitate se rezolvă pentru o culoare statică, TailwindPHP simplifică expresia `color-mix(in oklab, …)` la o valoare `oklab()` concretă — aceeași conversie pe care o efectuează lightningcss în lanțul de instrumente Tailwind din amonte — în timp ce culorile dinamice (cele încă încapsulate în `var()`) păstrează forma `color-mix()`, pentru a putea fi suprascrise în timpul execuției.

## Citirea valorilor temei din PHP

Trei accesorii returnează valorile rezolvate ale temei ca tablouri PHP. Fiecare acceptă un șir opțional de intrare CSS (implicit `@import "tailwindcss";`) și este disponibil și pe o [instanță a compilatorului](https://tailwindphp.inline0.dev/ro/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']
```

Transmiteți un șir CSS pentru a citi dintr-o temă personalizată:

```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 folosește o singură valoare de bază `--spacing` în locul unei scale `--spacing-*`, așa că `tw::spacing()` returnează doar tokenurile personalizate `--spacing-*` pe care le definiți. Aceleași metode sunt disponibile și dintr-o instanță a compilatorului: `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`. Pentru semnăturile complete, consultați [API](https://tailwindphp.inline0.dev/ro/docs/api).

## Pașii următori

- [Directive](https://tailwindphp.inline0.dev/ro/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Importuri](https://tailwindphp.inline0.dev/ro/docs/usage/imports) — `@import`, module virtuale și Preflight.
- [API](https://tailwindphp.inline0.dev/ro/docs/api) — fiecare accessor și metodă de inspectare.