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.

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.

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

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

Spații de nume uzuale

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

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

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

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

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

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

@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);
  }
}

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

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.

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

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.

Pașii următori

• Directive — @apply, @utility, @custom-variant, @layer.
• Importuri — @import, module virtuale și Preflight.
• API — fiecare accessor și metodă de inspectare.