# Tema e personalizzazione

Il tema di Tailwind è un insieme piatto di variabili CSS. Puoi estenderlo o sostituirlo con un blocco `@theme { … }` nell'input CSS, richiamare quei valori da CSS tramite le funzioni del tema e leggere i valori risolti da PHP. Non esiste un file di configurazione JavaScript: il tema risiede interamente in CSS.

## Il blocco `@theme`

Un blocco `@theme` dichiara i token di progettazione come proprietà personalizzate CSS. Il prefisso del namespace di ciascuna variabile (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) indica a Tailwind quali utility e varianti alimenta il token.

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

Ogni token registra utility nel proprio namespace. L'esempio precedente rende disponibili `bg-brand`, `text-brand`, `border-brand`, la famiglia `font-heading`, una variante responsive `xs:` e le spaziature `p-huge`/`m-huge`; vengono generate solo se la classe compare nei contenuti.

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

Il token `--breakpoint-xs` registra direttamente la variante `xs:`:

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

### Namespace comuni

| Namespace | Fornisce |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | Utility della famiglia `font-*` |
| `--text-*` | Utility per dimensione del carattere `text-*` |
| `--breakpoint-*` | Varianti responsive (`sm:`, `md:`, `xs:` personalizzata) |
| `--spacing-*` | Valori di spaziatura con nome (`p-huge`, `m-huge`) |
| `--radius-*` | Utility `rounded-*` |
| `--shadow-*` | Utility `shadow-*` |

### Cancellare un namespace

Impostare un carattere jolly del namespace su `initial` rimuove i valori predefiniti di Tailwind per quel namespace prima di aggiungere i tuoi token. Così puoi partire da una tavolozza pulita:

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

`--*: initial;` cancella l'intero tema. Un singolo valore `initial` su una chiave che non è un carattere jolly (`--color-red-500: initial;`) rimuove solo quel token. Per un carattere jolly `-*` è ammesso solo il valore `initial`: qualsiasi altro valore genera un errore.

## Leggere i valori del tema in CSS

### `theme()`

La funzione legacy `theme()` legge un valore usando la notazione a punti nei namespace in stile v3. Risolve il valore del token in fase di compilazione, quindi può essere usata ovunque sia previsto un valore, incluse le regole personalizzate e altre dichiarazioni.

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

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

I percorsi con notazione a punti corrispondono alle variabili sottostanti (`colors.red.500` → `--color-red-500`, `fontFamily.sans` → la famiglia sans). È supportato un modificatore di opacità: `theme(colors.red.500 / 50%)`. È possibile passare un valore di fallback come secondo argomento: `theme(colors.brand, #000)`. Se non è possibile risolvere un percorso e non viene fornito alcun fallback, il candidato che lo usa viene scartato.

### `--theme()`

`--theme()` legge una variabile del tema usando il nome della proprietà personalizzata CSS e per impostazione predefinita restituisce un riferimento `var()`, così il valore può essere sovrascritto in fase di esecuzione:

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

Aggiungi `inline` per sostituire il riferimento `var()` con il valore risolto: `--theme(--color-brand inline)`. Il secondo argomento è un valore di fallback (`--theme(--color-brand, #000)`), mentre un fallback `initial` viene gestito in modo speciale: viene inserito nei riferimenti `var()` annidati che a loro volta si risolvono in `initial`. All'interno di una regola at (`@media`, `@container`), `--theme()` viene sempre risolto inline, perché `var()` non è valido in quei preludi.

### `--spacing()`

`--spacing(n)` moltiplica l'unità di spaziatura di base del tema (`--spacing`) per `n`:

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

Un moltiplicatore pari a `1` si risolve nella variabile di base stessa (`--spacing(1)` → `var(--spacing)`, come produce anche `p-1`), mentre `0` si risolve in una lunghezza pari a zero.

È lo stesso calcolo usato dalle utilità di spaziatura integrate, quindi i valori personalizzati restano coerenti con `p-4`, `m-4` e le altre.

### `--alpha()`

`--alpha(color / opacity)` applica un'opacità a un colore usando un `color-mix()` nello spazio colore 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);
  }
}
```

La forma `color-mix()` resta sovrascrivibile in fase di esecuzione; il fallback statico che la precede, calcolato dal valore del tema, copre i browser che non supportano `color-mix()`. Disattiva il fallback con l'opzione `polyfills` di [`tw::compile()`](https://tailwindphp.inline0.dev/it/docs/api#twcompile).

### Composizione dell'opacità e `color-mix()` → `oklab()`

I modificatori di opacità si compongono. Applicando il 50% a un valore che ha già un'opacità del 50% si ottiene il 25%, calcolato in oklab. Quando un modificatore di opacità viene risolto rispetto a un colore statico, TailwindPHP riduce l'espressione `color-mix(in oklab, …)` a un valore `oklab()` concreto, come fa la toolchain upstream Tailwind — mentre i colori dinamici, ancora racchiusi in `var()`, mantengono la forma `color-mix()` per restare sovrascrivibili in fase di esecuzione.

## Lettura dei valori del tema da PHP

Tre accessor restituiscono i valori risolti del tema come array PHP. Ognuno accetta una stringa CSS di input facoltativa (il valore predefinito è `@import "tailwindcss";`) ed è disponibile anche su un'[istanza del compilatore](https://tailwindphp.inline0.dev/it/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']
```

Passa una stringa CSS per leggere i valori di un tema personalizzato:

```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 usa un unico valore di base `--spacing` invece di una scala `--spacing-*`, quindi `tw::spacing()` restituisce solo i token personalizzati `--spacing-*` che definisci. Gli stessi metodi sono disponibili anche da un'istanza del compilatore: `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`. Consulta [API](https://tailwindphp.inline0.dev/it/docs/api) per le firme complete.

## Passaggi successivi

- [Direttive](https://tailwindphp.inline0.dev/it/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Importazioni](https://tailwindphp.inline0.dev/it/docs/usage/imports) — `@import`, moduli virtuali e Preflight.
- [API](https://tailwindphp.inline0.dev/it/docs/api) — tutti gli accessor e i metodi di ispezione.