Motyw i dostosowywanie

Motyw Tailwind to płaski zestaw zmiennych CSS. Rozszerzaj go lub zastępuj blokiem @theme { … } w wejściowym CSS, odwołuj się do tych wartości wewnątrz CSS za pomocą funkcji motywu, a rozpoznane wartości odczytuj z powrotem z PHP. Nie ma pliku konfiguracyjnego JavaScript — motyw znajduje się w całości w CSS.

Blok @theme

Blok @theme deklaruje tokeny projektowe jako niestandardowe właściwości CSS. Prefiks przestrzeni nazw każdej zmiennej (--color-*, --font-*, --breakpoint-*, --spacing-*, …) wskazuje Tailwind, które narzędzia i warianty korzystają z danego tokenu.

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

Każdy token rejestruje narzędzia w swojej przestrzeni nazw. Powyższy przykład udostępnia bg-brand, text-brand, border-brand, rodzinę font-heading, wariant responsywny xs: oraz odstępy p-huge/m-huge — generowane wyłącznie wtedy, gdy klasa występuje w treści.

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

Token --breakpoint-xs bezpośrednio rejestruje wariant xs::

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

Typowe przestrzenie nazw

Czyszczenie przestrzeni nazw

Ustawienie symbolu wieloznacznego przestrzeni nazw na initial usuwa domyślne wartości Tailwind dla tej przestrzeni przed dodaniem własnych tokenów. Dzięki temu możesz zacząć od czystej palety:

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

--*: initial; czyści cały motyw. Pojedyncza wartość initial w kluczu innym niż symbol wieloznaczny (--color-red-500: initial;) usuwa tylko ten token. Dla symbolu wieloznacznego -* akceptowana jest wyłącznie wartość initial — każda inna powoduje błąd.

Odczytywanie wartości motywu w CSS

theme()

Starsza funkcja theme() odczytuje wartość na podstawie notacji kropkowej i przestrzeni nazw w stylu v3. Rozpoznaje wartość tokenu podczas kompilacji, więc można jej używać wszędzie tam, gdzie oczekiwana jest wartość — także w regułach niestandardowych i innych deklaracjach.

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

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

Ścieżki kropkowe odpowiadają bazowym zmiennym (colors.red.500 → --color-red-500, fontFamily.sans → rodzina bezszeryfowa). Obsługiwany jest modyfikator krycia: theme(colors.red.500 / 50%). Wartość zastępczą można przekazać jako drugi argument: theme(colors.brand, #000). Jeśli ścieżki nie można rozpoznać i nie podano wartości zastępczej, kandydat, który jej używa, zostaje pominięty.

--theme()

--theme() odczytuje zmienną motywu na podstawie jej nazwy niestandardowej właściwości CSS i domyślnie zwraca odwołanie var(), dzięki czemu wartość można nadpisywać w czasie działania programu:

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

Dodaj inline, aby wstawić rozpoznaną wartość zamiast odwołania var(): --theme(--color-brand inline). Drugi argument to wartość zastępcza (--theme(--color-brand, #000)), a wartość zastępcza initial jest obsługiwana specjalnie — wstawiana jest do zagnieżdżonych odwołań var(), które same mają wartość initial. Wewnątrz reguł at (@media, @container) --theme() zawsze jest rozwijana bezpośrednio, ponieważ var() jest nieprawidłowe w tych przedrostkach.

--spacing()

--spacing(n) mnoży podstawową jednostkę odstępu motywu (--spacing) przez n:

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

Mnożnik 1 odpowiada samej zmiennej bazowej (--spacing(1) → var(--spacing), co emituje również p-1), a 0 — zwykłej długości równej zero.

To te same obliczenia, których używają wbudowane narzędzia odstępów, dzięki czemu niestandardowe wartości pozostają zgodne z p-4, m-4 i podobnymi.

--alpha()

--alpha(color / opacity) stosuje krycie do koloru za pomocą color-mix() w przestrzeni barw 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);
  }
}

Postać color-mix() pozostaje możliwa do nadpisania w czasie działania programu; poprzedzająca ją statyczna wartość zastępcza, obliczona na podstawie wartości motywu, obsługuje przeglądarki bez color-mix(). Wyłącz wartość zastępczą opcją polyfills w tw::compile().

Łączenie krycia i color-mix() → oklab()

Modyfikatory krycia łączą się. Zastosowanie wartości 50% do wartości, która już ma krycie 50%, daje 25% obliczone w oklab. Gdy modyfikator krycia jest stosowany do koloru statycznego, TailwindPHP upraszcza wyrażenie color-mix(in oklab, …) do konkretnej wartości oklab() — tak samo jak lightningcss w nadrzędnym łańcuchu narzędzi Tailwind — natomiast kolory dynamiczne (wciąż opakowane w var()) zachowują postać color-mix(), dzięki czemu nadal można je nadpisywać w czasie działania programu.

Odczytywanie wartości motywu z PHP

Trzy metody dostępu zwracają rozpoznane wartości motywu jako tablice PHP. Każda przyjmuje opcjonalny ciąg wejściowy CSS (domyślnie @import "tailwindcss";) i jest również dostępna w instancji kompilatora.

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']

Przekaż ciąg CSS, aby odczytać wartości z dostosowanego motywu:

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 używa jednej bazowej wartości --spacing zamiast skali --spacing-*, dlatego tw::spacing() zwraca tylko zdefiniowane przez Ciebie niestandardowe tokeny --spacing-*. Te same metody są dostępne w instancji kompilatora: $compiler->colors(), $compiler->breakpoints(), $compiler->spacing(). Pełne sygnatury znajdziesz w API.

Następne kroki

• Dyrektywy — @apply, @utility, @custom-variant, @layer.
• Importy — @import, moduły wirtualne i Preflight.
• API — wszystkie metody dostępu i inspekcji.