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.

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.

/* 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::

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

Espacios de nombres habituales

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:

@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.

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

.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:

.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:

@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:

@utility tint { color: --alpha(var(--color-red-500) / 50%); }

.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().

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.

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:

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 para ver las firmas completas.

Pasos siguientes

• Directivas: @apply, @utility, @custom-variant, @layer.
• Importaciones: @import, módulos virtuales y Preflight.
• API: todos los métodos de acceso e inspección.