Tema & Penyesuaian

Tema Tailwind berupa kumpulan variabel CSS datar. Anda dapat memperluas atau menggantinya dengan blok @theme { … } di CSS input Anda, merujuk nilai tersebut dari dalam CSS melalui fungsi tema, dan membaca kembali nilai yang telah diselesaikan dari PHP. Tidak ada file konfigurasi JavaScript — tema sepenuhnya berada di CSS.

Blok @theme

Blok @theme mendeklarasikan token desain sebagai properti kustom CSS. Prefiks namespace pada tiap variabel (--color-*, --font-*, --breakpoint-*, --spacing-*, …) memberi tahu Tailwind utilitas dan varian mana yang menggunakan token tersebut.

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

Setiap token mendaftarkan utilitas dalam namespace-nya. Contoh di atas membuat bg-brand, text-brand, border-brand, keluarga font-heading, varian responsif xs:, serta spasi p-huge/m-huge tersedia — hanya dibuat ketika kelas tersebut muncul dalam konten Anda.

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

Token --breakpoint-xs mendaftarkan varian xs: secara langsung:

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

Namespace umum

Menghapus namespace

Mengatur wildcard namespace ke initial menghapus default Tailwind untuk namespace tersebut sebelum token Anda sendiri ditambahkan. Dengan begitu, Anda dapat memulai dari palet kosong:

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

--*: initial; menghapus seluruh tema. Satu nilai initial pada kunci non-wildcard (--color-red-500: initial;) hanya menghapus satu token tersebut. Hanya initial yang diterima sebagai nilai untuk wildcard -* — nilai lainnya akan menyebabkan kesalahan.

Membaca nilai tema di CSS

theme()

Fungsi lama theme() membaca nilai menggunakan notasi titik berdasarkan namespace bergaya v3. Fungsi ini menyelesaikan nilai token saat kompilasi, sehingga dapat digunakan di mana pun nilai diperlukan — termasuk dalam aturan kustom dan deklarasi lainnya.

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

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

Jalur titik memetakan ke variabel yang mendasarinya (colors.red.500 → --color-red-500, fontFamily.sans → keluarga sans). Modifier opasitas didukung: theme(colors.red.500 / 50%). Nilai fallback dapat diberikan sebagai argumen kedua: theme(colors.brand, #000). Jika jalur tidak dapat diresolusikan dan tidak ada fallback, kandidat yang menggunakannya akan dihapus.

--theme()

--theme() membaca variabel tema berdasarkan nama properti kustom CSS dan secara default mengembalikan referensi var(), sehingga nilainya tetap dapat ditimpa saat runtime:

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

Tambahkan inline untuk menyisipkan nilai yang telah diresolusikan alih-alih referensi var(): --theme(--color-brand inline). Argumen kedua adalah nilai fallback (--theme(--color-brand, #000)), dan fallback initial ditangani secara khusus — nilainya disisipkan ke dalam referensi var() bertingkat yang juga diresolusikan menjadi initial. Di dalam at-rule (@media, @container), --theme() selalu diresolusikan secara inline karena var() tidak valid dalam prelude tersebut.

--spacing()

--spacing(n) mengalikan unit spasi dasar tema (--spacing) dengan n:

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

Pengali 1 diresolusikan menjadi variabel dasar itu sendiri (--spacing(1) → var(--spacing), sama seperti yang dihasilkan p-1), sedangkan 0 menjadi panjang nol biasa.

Ini adalah perhitungan yang sama dengan yang digunakan utilitas spasi bawaan, sehingga nilai kustom tetap konsisten dengan p-4, m-4, dan lainnya.

--alpha()

--alpha(color / opacity) menerapkan opasitas pada warna menggunakan color-mix() dalam ruang warna 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);
  }
}

Bentuk color-mix() tetap dapat ditimpa saat runtime; fallback statis sebelumnya, yang dihitung dari nilai tema, mencakup browser yang tidak mendukung color-mix(). Nonaktifkan fallback dengan opsi polyfills pada tw::compile().

Menumpuk opasitas dan color-mix() → oklab()

Modifier opasitas dapat digabungkan. Menerapkan 50% pada nilai yang sudah memiliki opasitas 50% menghasilkan 25%, dihitung dalam oklab. Saat modifier opasitas diresolusikan terhadap warna statis, TailwindPHP menyederhanakan ekspresi color-mix(in oklab, …) menjadi nilai oklab() konkret — konversi yang sama dengan yang dilakukan lightningcss pada toolchain Tailwind upstream — sedangkan warna dinamis (yang masih dibungkus dalam var()) mempertahankan bentuk color-mix() agar tetap dapat ditimpa saat runtime.

Membaca nilai tema dari PHP

Tiga accessor mengembalikan nilai tema yang telah diresolusikan sebagai array PHP. Masing-masing menerima string input CSS opsional (default @import "tailwindcss";) dan juga tersedia pada instance compiler.

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

Berikan string CSS untuk membaca berdasarkan tema yang dikustomisasi:

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 menggunakan satu nilai dasar --spacing, bukan skala --spacing-*, sehingga tw::spacing() hanya mengembalikan token --spacing-* kustom yang Anda definisikan. Metode yang sama juga tersedia dari instance compiler: $compiler->colors(), $compiler->breakpoints(), $compiler->spacing(). Lihat API untuk signature lengkap.

Langkah berikutnya

• Direktif — @apply, @utility, @custom-variant, @layer.
• Impor — @import, modul virtual, dan Preflight.
• API — setiap accessor dan metode inspeksi.