# Theme und Anpassung

Das Theme von Tailwind besteht aus einer flachen Menge von CSS-Variablen. Du erweiterst oder ersetzt es mit einem `@theme { … }`-Block in deinem Eingabe-CSS, verweist innerhalb von CSS über Theme-Funktionen auf diese Werte und liest die aufgelösten Werte aus PHP aus. Es gibt keine JavaScript-Konfigurationsdatei – das Theme liegt vollständig in CSS.

## Der `@theme`-Block

Ein `@theme`-Block definiert Design-Tokens als benutzerdefinierte Eigenschaften von CSS. Das Namensraumpräfix jeder Variable (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) gibt an, welche Utilities und Varianten Tailwind mit diesem Token bereitstellt.

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

Jeder Token registriert Utilities in seinem Namensraum. Das obige Beispiel stellt `bg-brand`, `text-brand`, `border-brand`, die Familie `font-heading`, eine responsive Variante `xs:` sowie Abstände `p-huge`/`m-huge` bereit – generiert werden sie nur, wenn die jeweilige Klasse in deinen Inhalten vorkommt.

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

Der Token `--breakpoint-xs` registriert die Variante `xs:` direkt:

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

### Häufige Namensräume

| Namensraum | Stellt bereit |
|-----------|-------|
| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
| `--font-*` | Utilities der Familie `font-*` |
| `--text-*` | `text-*`-Schriftgrößen-Utilities |
| `--breakpoint-*` | Responsive Varianten (`sm:`, `md:`, benutzerdefiniertes `xs:`) |
| `--spacing-*` | Benannte Abstände (`p-huge`, `m-huge`) |
| `--radius-*` | `rounded-*`-Utilities |
| `--shadow-*` | `shadow-*`-Utilities |

### Namensraum zurücksetzen

Wenn du einen Namensraum-Wildcard auf `initial` setzt, entfernt Tailwind zunächst die Standardwerte für diesen Namensraum. Anschließend werden deine eigenen Tokens hinzugefügt. So kannst du mit einer leeren Palette beginnen:

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

`--*: initial;` setzt das gesamte Theme zurück. Ein einzelner Wert `initial` für einen Schlüssel ohne Wildcard (`--color-red-500: initial;`) entfernt nur diesen Token. Als Wert für einen `-*`-Wildcard ist nur `initial` zulässig; jeder andere Wert führt zu einem Fehler.

## Theme-Werte in CSS auslesen

### `theme()`

Die veraltete Funktion `theme()` liest einen Wert in Punktnotation aus den Namespaces von v3-style. Sie wird beim Kompilieren zum Wert des Tokens aufgelöst und kann daher überall dort verwendet werden, wo ein Wert erwartet wird – auch in benutzerdefinierten Regeln und anderen Deklarationen.

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

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

Punktpfade verweisen auf die zugrunde liegenden Variablen (`colors.red.500` → `--color-red-500`, `fontFamily.sans` → die serifenlose Schriftfamilie). Ein Opazitätsmodifikator wird unterstützt: `theme(colors.red.500 / 50%)`. Ein Fallback kann als zweites Argument übergeben werden: `theme(colors.brand, #000)`. Kann ein Pfad nicht aufgelöst werden und ist kein Fallback angegeben, wird der Kandidat, der ihn verwendet, verworfen.

### `--theme()`

`--theme()` liest eine Theme-Variable anhand ihres CSS-Eigenschaftsnamens und gibt standardmäßig eine `var()`-Referenz zurück, damit der Wert zur Laufzeit überschreibbar bleibt:

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

Füge `inline` hinzu, um statt einer `var()`-Referenz den aufgelösten Wert einzusetzen: `--theme(--color-brand inline)`. Ein zweites Argument dient als Fallback (`--theme(--color-brand, #000)`); ein `initial`-Fallback wird speziell behandelt — er wird in verschachtelte `var()`-Referenzen eingefügt, die selbst zu `initial` aufgelöst werden. Innerhalb einer At-Regel (`@media`, `@container`) wird `--theme()` immer inline aufgelöst, da `var()` in diesen Präambeln ungültig ist.

### `--spacing()`

`--spacing(n)` multipliziert die grundlegende Abstandseinheit des Themes (`--spacing`) mit `n`:

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

Ein Multiplikator von `1` wird zur Basisvariable selbst aufgelöst (`--spacing(1)` → `var(--spacing)`, was auch `p-1` ausgibt), und `0` zu einer einfachen Länge von null.

Dies ist dieselbe Berechnung, die die integrierten Abstandswerkzeuge verwenden. Benutzerdefinierte Werte bleiben so mit `p-4`, `m-4` und ähnlichen Werten konsistent.

### `--alpha()`

`--alpha(color / opacity)` wendet mithilfe eines `color-mix()` im oklab-Farbraum eine Opazität auf eine Farbe an:

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

Die Form `color-mix()` bleibt zur Laufzeit überschreibbar; der davorstehende statische Fallback, der aus dem Theme-Wert berechnet wird, deckt Browser ohne `color-mix()` ab. Deaktiviere den Fallback mit der Option `polyfills` von [`tw::compile()`](https://tailwindphp.inline0.dev/de/docs/api#twcompile).

### Opazität und `color-mix()` kombinieren → `oklab()`

Opazitätsmodifikatoren lassen sich kombinieren. Werden auf einen Wert, der bereits 50 % Opazität hat, nochmals 50 % angewendet, ergibt das 25 %, berechnet in oklab. Wird ein Opazitätsmodifikator auf eine statische Farbe angewendet, reduziert TailwindPHP den Ausdruck `color-mix(in oklab, …)` auf einen konkreten Wert vom Typ `oklab()` — dieselbe Umwandlung, die lightningcss in der vorgelagerten Tailwind-Toolchain durchführt. Dynamische Farben, die weiterhin in `var()` eingeschlossen sind, behalten die Form `color-mix()` und bleiben dadurch zur Laufzeit überschreibbar.

## Theme-Werte aus PHP lesen

Drei Zugriffsmethoden geben aufgelöste Theme-Werte als PHP-Arrays zurück. Jede nimmt optional einen Eingabestring CSS entgegen (Standardwert `@import "tailwindcss";`) und ist auch auf einer [Compilerinstanz](https://tailwindphp.inline0.dev/de/docs/api) verfügbar.

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

Übergib einen CSS-String, um Werte aus einem angepassten Theme auszulesen:

```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 verwendet einen einzelnen `--spacing`-Basiswert statt einer `--spacing-*`-Skala, daher gibt `tw::spacing()` nur die benutzerdefinierten `--spacing-*`-Tokens zurück, die du definierst. Bei einer Compilerinstanz sind dieselben Methoden verfügbar: `$compiler->colors()`, `$compiler->breakpoints()`, `$compiler->spacing()`. Die [API](https://tailwindphp.inline0.dev/de/docs/api) enthält alle Signaturen.

## Nächste Schritte

- [Direktiven](https://tailwindphp.inline0.dev/de/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [Importe](https://tailwindphp.inline0.dev/de/docs/usage/imports) — `@import`, virtuelle Module und Preflight.
- [API](https://tailwindphp.inline0.dev/de/docs/api) — alle Accessor- und Inspektionsmethoden.