# Teema ja mukauttaminen

Tailwind-teema on litteä joukko CSS-muuttujia. Laajenna tai korvaa se syöte-CSS:si `@theme { … }`-lohkolla, käytä arvoja CSS-sisällä teeman funktioiden kautta ja lue ratkaistut arvot takaisin kohteesta PHP. Erillistä JavaScript-asetustiedostoa ei ole — teema sijaitsee kokonaan CSS-sisällössä.

## `@theme`-lohko

`@theme`-lohko määrittää suunnittelutokenit CSS-mukautettuina ominaisuuksina. Kunkin muuttujan nimiavaruuden etuliite (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) kertoo, mitä apuohjelmia ja muunnelmia token ohjaa Tailwind-järjestelmässä.

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

Jokainen token rekisteröi apuohjelmat omaan nimiavaruuteensa. Yllä oleva esimerkki ottaa käyttöön `bg-brand`, `text-brand` ja `border-brand`, `font-heading`-perheen, responsiivisen muunnelman `xs:` sekä välistysarvot `p-huge`/`m-huge` — mutta ne luodaan vain, kun luokka esiintyy sisällössäsi.

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

`--breakpoint-xs`-token rekisteröi suoraan muunnelman `xs:`:

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

### Yleiset nimiavaruudet

| Nimiavaruus | Tuottaa |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | `font-*`-perheen apuohjelmat |
| `--text-*` | `text-*`-fonttikokoapuohjelmat |
| `--breakpoint-*` | responsiiviset muunnelmat (`sm:`, `md:`, mukautettu `xs:`) |
| `--spacing-*` | nimetyt välistysarvot (`p-huge`, `m-huge`) |
| `--radius-*` | `rounded-*`-apuohjelmat |
| `--shadow-*` | `shadow-*`-apuohjelmat |

### Nimiavaruuden tyhjentäminen

Nimiavaruuden jokerimerkin asettaminen arvoon `initial` poistaa Tailwind-oletukset kyseisestä nimiavaruudesta ennen omien tokeniesi lisäämistä. Näin voit aloittaa puhtaalta pohjalta:

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

`--*: initial;` tyhjentää koko teeman. Arvo `initial` tavallisessa avaimessa (`--color-red-500: initial;`) poistaa vain kyseisen tokenin. `initial` hyväksytään `-*`-jokerimerkin arvoksi; muut arvot aiheuttavat virheen.

## Teema-arvojen lukeminen kohteessa CSS

### `theme()`

Vanha `theme()`-funktio lukee arvon piste-erottelulla v3-tyylisistä nimiavaruuksista. Se ratkaisee tokenin arvon käännösaikana, joten sitä voi käyttää missä tahansa arvoa odotetaan — myös mukautetuissa säännöissä ja muissa määrityksissä.

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

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

Pistepolut vastaavat taustalla olevia muuttujia (`colors.red.500` → `--color-red-500`, `fontFamily.sans` → päätteetön perhe). Läpinäkyvyysmuunnin on tuettu: `theme(colors.red.500 / 50%)`. Varatunnisteen voi antaa toisena argumenttina: `theme(colors.brand, #000)`. Jos polkua ei voida ratkaista eikä varatunnistetta anneta, sitä käyttävä ehdokas hylätään.

### `--theme()`

`--theme()` lukee teeman muuttujan sen CSS mukautetun ominaisuuden nimen perusteella ja palauttaa oletuksena `var()`-viitteen, joten arvo pysyy yliajettavissa suorituksen aikana:

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

Lisää `inline`, jotta ratkaistu arvo korvataan `var()`-viitteellä: `--theme(--color-brand inline)`. Toinen argumentti on varatunniste (`--theme(--color-brand, #000)`), ja `initial`-varatunniste käsitellään erityisesti — se lisätään sisäkkäisiin `var()`-viitteisiin, jotka itse ratkeavat arvoon `initial`. At-säännön (`@media`, `@container`) sisällä `--theme()` ratkaistaan aina suoraan, koska `var()` ei kelpaa näissä esiosissa.

### `--spacing()`

`--spacing(n)` kertoo teeman perusvälistysyksikön (`--spacing`) arvolla `n`:

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

Kerroin `1` ratkeaa itse perusmuuttujaksi (`--spacing(1)` → `var(--spacing)`, jonka myös `p-1` tuottaa), ja `0` pelkäksi nollapituiseksi arvoksi.

Tämä on sama laskutoimitus, jota sisäänrakennetut välistysapuohjelmat käyttävät, joten mukautetut arvot pysyvät yhdenmukaisina seuraavien kanssa: `p-4`, `m-4` ja muut vastaavat.

### `--alpha()`

`--alpha(color / opacity)` lisää väriin peittävyyden `color-mix()`-arvolla oklab-väriavaruudessa:

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

Muoto `color-mix()` pysyy yliajettavissa suorituksen aikana; sitä edeltävä staattinen, teeman arvosta laskettu varatunniste toimii selaimissa, jotka eivät tue ominaisuutta `color-mix()`. Poista varatunniste käytöstä valinnan `polyfills` avulla: [`tw::compile()`](https://tailwindphp.inline0.dev/fi/docs/api#twcompile).

### Peittävyyden ja `color-mix()`-muuntimen ketjuttaminen → `oklab()`

Peittävyysmuuntimet yhdistyvät. Kun arvoon, jonka peittävyys on jo 50 %, lisätään 50 %, tulokseksi tulee 25 % oklabissa laskettuna. Kun peittävyysmuunnin kohdistuu staattiseen väriin, TailwindPHP yksinkertaistaa lausekkeen `color-mix(in oklab, …)` konkreettiseksi `oklab()`-arvoksi — samalla tavoin kuin lightningcss tekee alkupään Tailwind-työkaluketjussa — kun taas dynaamiset värit (jotka ovat edelleen muodon `var()` sisällä) säilyttävät muodon `color-mix()`, jotta ne pysyvät yliajettavissa suorituksen aikana.

## Teeman arvojen lukeminen kohteesta PHP

Kolme käyttötapaa palauttaa ratkaistut teema-arvot PHP-taulukoina. Kukin ottaa valinnaisen syötteen CSS merkkijonona (oletus `@import "tailwindcss";`), ja on käytettävissä myös [kääntäjäinstanssissa](https://tailwindphp.inline0.dev/fi/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']
```

Anna CSS-merkkijono, jotta arvot luetaan mukautetusta teemasta:

```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 käyttää yhtä `--spacing`-perusarvoa `--spacing-*`-asteikon sijaan, joten `tw::spacing()` palauttaa vain määrittelemäsi mukautetut `--spacing-*`-tunnisteet. Samat metodit ovat käytettävissä kääntäjäinstanssista: `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`. Katso täydelliset allekirjoitukset kohdasta [API](https://tailwindphp.inline0.dev/fi/docs/api).

## Seuraavat vaiheet

- [Direktiivit](https://tailwindphp.inline0.dev/fi/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Tuonnit](https://tailwindphp.inline0.dev/fi/docs/usage/imports) — `@import`, virtuaalimoduulit ja Preflight.
- [API](https://tailwindphp.inline0.dev/fi/docs/api) — kaikki käyttö- ja tarkastusmenetelmät.