# Tema y personalización

El tema de Tailwind es un conjunto plano de variables CSS. Puedes ampliarlo o sustituirlo con un bloque `@theme { … }` en tu CSS de entrada, consultar esos valores desde CSS mediante las funciones del tema y leer los valores resueltos desde PHP. No hay ningún archivo de configuración JavaScript: el tema reside por completo en CSS.

## El bloque `@theme`

Un bloque `@theme` declara tokens de diseño como propiedades personalizadas de CSS. El prefijo del espacio de nombres de cada variable (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) indica a Tailwind qué utilidades y variantes alimenta el 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;
    }
');
```

Cada token registra utilidades en su espacio de nombres. El ejemplo anterior habilita `bg-brand`, `text-brand`, `border-brand`, la familia `font-heading`, una variante adaptable `xs:` y el espaciado `p-huge`/`m-huge`; solo se generan cuando la clase aparece en tu contenido.

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

El token `--breakpoint-xs` registra directamente la variante `xs:`:

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

### Espacios de nombres habituales

| Espacio de nombres | Proporciona |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | utilidades de la familia `font-*` |
| `--text-*` | utilidades de tamaño de fuente `text-*` |
| `--breakpoint-*` | variantes adaptables (`sm:`, `md:`, `xs:` personalizadas) |
| `--spacing-*` | valores de espaciado con nombre (`p-huge`, `m-huge`) |
| `--radius-*` | utilidades de `rounded-*` |
| `--shadow-*` | utilidades de `shadow-*` |

### Vaciar un espacio de nombres

Asignar `initial` a un comodín de espacio de nombres elimina los valores predeterminados de Tailwind para ese espacio antes de añadir tus propios tokens. Así puedes empezar con una paleta limpia:

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

`--*: initial;` vacía todo el tema. Un valor único de `initial` en una clave que no sea comodín (`--color-red-500: initial;`) elimina solo ese token. Para un comodín `-*`, solo se acepta `initial` como valor; cualquier otro valor genera un error.

## Leer valores del tema en CSS

### `theme()`

La función heredada `theme()` lee un valor mediante notación de puntos en los espacios de nombres de estilo v3. Resuelve el valor del token durante la compilación, por lo que puede usarse donde se espere un valor, incluso en reglas personalizadas y otras declaraciones.

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

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

Las rutas con puntos corresponden a las variables subyacentes (`colors.red.500` → `--color-red-500`, `fontFamily.sans` → la familia sans). Se admite un modificador de opacidad: `theme(colors.red.500 / 50%)`. Se puede pasar un valor alternativo como segundo argumento: `theme(colors.brand, #000)`. Si no se puede resolver una ruta y no se proporciona un valor alternativo, se descarta el candidato que la usa.

### `--theme()`

`--theme()` lee una variable del tema por su nombre de propiedad personalizada CSS y devuelve por defecto una referencia `var()`, para que el valor siga siendo modificable en tiempo de ejecución:

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

Añada `inline` para sustituir el valor resuelto en lugar de una referencia `var()`: `--theme(--color-brand inline)`. El segundo argumento es un valor alternativo (`--theme(--color-brand, #000)`), y los valores alternativos `initial` se gestionan de forma especial: se insertan en referencias `var()` anidadas que, a su vez, se resuelven como `initial`. Dentro de una regla at (`@media`, `@container`), `--theme()` siempre se resuelve en línea porque `var()` no es válido en esos preámbulos.

### `--spacing()`

`--spacing(n)` multiplica la unidad de espaciado base del tema (`--spacing`) por `n`:

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

Un multiplicador de `1` se resuelve como la propia variable base (`--spacing(1)` → `var(--spacing)`, que también es lo que genera `p-1`), y `0` se resuelve como una longitud cero simple.

Este es el mismo cálculo que usan las utilidades de espaciado integradas, así que los valores personalizados son coherentes con `p-4`, `m-4` y otras.

### `--alpha()`

`--alpha(color / opacity)` aplica opacidad a un color usando un `color-mix()` en el espacio de color 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()` sigue siendo modificable en tiempo de ejecución; el valor alternativo estático que la precede, calculado a partir del valor del tema, sirve para los navegadores que no admiten `color-mix()`. Desactive el valor alternativo con la opción `polyfills` de [`tw::compile()`](https://tailwindphp.inline0.dev/es/docs/api#twcompile).

### Acumular opacidad y `color-mix()` → `oklab()`

Los modificadores de opacidad se combinan. Aplicar un 50 % a un valor que ya tiene un 50 % da como resultado un 25 %, calculado en oklab. Cuando un modificador de opacidad se resuelve sobre un color estático, TailwindPHP reduce la expresión `color-mix(in oklab, …)` a un valor `oklab()` concreto, mediante la misma conversión que lightningcss realiza en la cadena de herramientas Tailwind original. En cambio, los colores dinámicos (los que siguen envueltos en `var()`) conservan la forma `color-mix()` para que sigan siendo modificables en tiempo de ejecución.

## Leer valores del tema desde PHP

Tres métodos de acceso devuelven los valores resueltos del tema como matrices PHP. Cada uno acepta una cadena de entrada CSS opcional (valor predeterminado `@import "tailwindcss";`) y también está disponible en una [instancia del compilador](https://tailwindphp.inline0.dev/es/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']
```

Pase una cadena CSS para consultar un tema personalizado:

```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 único valor base `--spacing` en lugar de una escala `--spacing-*`, por lo que `tw::spacing()` devuelve solo los tokens personalizados `--spacing-*` que defina. Los mismos métodos están disponibles en una instancia del compilador: `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`. Consulte la [API](https://tailwindphp.inline0.dev/es/docs/api) para ver las firmas completas.

## Pasos siguientes

- [Directivas](https://tailwindphp.inline0.dev/es/docs/usage/directives): `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Importaciones](https://tailwindphp.inline0.dev/es/docs/usage/imports): `@import`, módulos virtuales y Preflight.
- [API](https://tailwindphp.inline0.dev/es/docs/api): todos los métodos de acceso e inspección.