Block-Themes mit theme.json

In Modul 1 haben Sie theme.json als Herzstück eines Block-Themes kennengelernt. Diese Lektion geht in die Tiefe: Wie ist die Datei aufgebaut, wie werden Farben, Schriften und Abstände als Presets angelegt, wie wirken Stile auf Blöcke und Elemente, und wie lassen sich Varianten und responsive Werte umsetzen? Mit einer gut aufgebauten theme.json lässt sich ein vollständiges, einheitliches Design fast ohne eigenes CSS umsetzen – und Redakteure bekommen genau die Gestaltungsmöglichkeiten, die sie brauchen, ohne das Design verbiegen zu können.

1. Aufbau

1{
2  "$schema": "https://schemas.wp.org/trunk/theme.json",
3  "version": 3,
4  "settings": {
5    "appearanceTools": true,
6    "color": {
7      "custom": false,
8      "palette": [
9        { "slug": "marke", "color": "#21759b", "name": "Marke" },
10        { "slug": "tinte", "color": "#0f1115", "name": "Tinte" },
11        { "slug": "papier", "color": "#fafaf7", "name": "Papier" }
12      ]
13    },
14    "typography": {
15      "fluid": true,
16      "fontSizes": [
17        { "slug": "klein", "size": "0.9rem", "name": "Klein" },
18        { "slug": "gross", "size": "2.4rem", "fluid": { "min": "1.8rem", "max": "2.4rem" }, "name": "Groß" }
19      ]
20    },
21    "spacing": { "spacingScale": { "steps": 6 } },
22    "layout": { "contentSize": "720px", "wideSize": "1200px" }
23  },
24  "styles": {
25    "color": { "background": "var(--wp--preset--color--papier)", "text": "var(--wp--preset--color--tinte)" },
26    "elements": {
27      "button": { "color": { "background": "var(--wp--preset--color--marke)" } },
28      "link": { "color": { "text": "var(--wp--preset--color--marke)" } }
29    },
30    "blocks": {
31      "core/quote": { "border": { "left": { "color": "var(--wp--preset--color--marke)", "width": "4px" } } }
32    }
33  }
34}

Aus jedem Preset erzeugt WordPress eine CSS-Variable nach dem Muster --wp--preset--color--marke. Diese Variablen lassen sich überall in styles und im eigenen CSS verwenden. Ändert man die Farbe in der Palette, ändert sie sich überall. Mit „custom“: false werden freie Farbwähler im Editor ausgeblendet, sodass nur die Palette zur Verfügung steht. appearanceTools schaltet auf einen Schlag Rahmen, Abstände, Zeilenhöhe und weitere Werkzeuge im Editor frei.

2. Ebenen und Vorrang

Die Stile einer Website stammen aus mehreren Ebenen, die sich überlagern: den Standards von WordPress, der theme.json des Themes, eines Child-Themes, einer gewählten Stilvariante und den Anpassungen im Website-Editor. Spätere Ebenen haben Vorrang. Klicken Sie sich durch:

Dieses Modell erklärt eine häufige Überraschung: Ein Entwickler ändert eine Farbe in theme.json, doch auf der Website ändert sich nichts. Meist liegt es daran, dass jemand die Farbe zuvor im Website-Editor angepasst hat – diese Anpassung hat Vorrang. Im Website-Editor lassen sich solche Anpassungen unter „Stile“ zurücksetzen.

3. Stilvarianten und Abschnittsstile

Stilvarianten sind zusätzliche JSON-Dateien im Ordner styles, die einen Teil von theme.json überschreiben – etwa eine dunkle Variante oder eine andere Farbwelt. Redakteure wählen sie im Website-Editor mit einem Klick. Seit einigen Versionen gibt es außerdem Abschnittsstile: Varianten für Gruppen-Blöcke, die einem Bereich einer Seite ein anderes Farbschema geben, etwa eine dunkle Hervorhebung mit hellem Text, wobei alle darin enthaltenen Blöcke automatisch passende Farben bekommen. So entstehen abwechslungsreiche Seiten, ohne dass einzelne Blöcke umgefärbt werden müssen.

1{
2  "$schema": "https://schemas.wp.org/trunk/theme.json",
3  "version": 3,
4  "title": "Dunkel",
5  "settings": {
6    "color": {
7      "palette": [
8        { "slug": "papier", "color": "#101418", "name": "Papier" },
9        { "slug": "tinte", "color": "#f1f3f5", "name": "Tinte" }
10      ]
11    }
12  }
13}

4. Fließende Typografie und Responsivität

Schriftgrößen sollen auf dem Handy kleiner sein als auf großen Bildschirmen. Mit „fluid“: true berechnet WordPress für jede Größe automatisch eine CSS-Funktion, die zwischen einem Minimal- und einem Maximalwert stufenlos skaliert. Für Abstände gibt es eine Skala mit vordefinierten Stufen. Mit WordPress 7.1 kamen zudem responsive Stilzustände hinzu, mit denen sich für Blöcke unterschiedliche Werte je Bildschirmbreite hinterlegen lassen. Zusammen sorgen diese Werkzeuge dafür, dass ein Block-Theme auf allen Geräten gut aussieht, ohne dass eigenes CSS mit Medienabfragen geschrieben werden muss.

5. Werkzeuge

6. Ein Beispiel

Ein Café mit Rösterei ließ ein Block-Theme entwickeln. Die theme.json enthält eine Palette aus fünf Farben, zwei Schriftfamilien mit fließenden Größen, eine Abstandsskala mit sechs Stufen und Standardstile für Buttons, Links und Zitate. Freie Farben und Schriftgrößen sind im Editor abgeschaltet. Dazu gibt es zwei Stilvarianten, „Sommer“ und „Winter“, und einen Abschnittsstil „Röstung“ mit dunklem Hintergrund für Hervorhebungen. Das Team gestaltet neue Seiten selbst aus Mustern und Blöcken; jede Seite passt automatisch zum Design. Als das Café seine Hausfarbe änderte, genügte eine Zeile in theme.json.

7. Häufige Fragen

Brauche ich noch eine style.css? Ja, aber vor allem für den Kopfbereich mit Name, Version und Beschreibung des Themes. Eigenes CSS ist in Block-Themes oft nur für Details nötig, die theme.json nicht abdeckt, etwa besondere Animationen. Blockspezifisches CSS lässt sich zudem gezielt nur dann laden, wenn der Block auf der Seite vorkommt.

Was bedeutet die Versionsnummer in theme.json? Sie bezeichnet das Format der Datei, nicht die Version des Themes. Version 3 ist derzeit aktuell; ältere Formate werden weiter unterstützt, aber neue Funktionen stehen nur im aktuellen Format zur Verfügung.

Kann ein Plugin theme.json-Werte beeinflussen? Ja, über Filter wie wp_theme_json_data_theme lassen sich Einstellungen und Stile programmatisch ergänzen oder überschreiben. Das ist nützlich, wenn ein Plugin etwa eigene Farben mitbringt, sollte aber sparsam eingesetzt werden, damit das Theme die Hoheit über das Design behält.

8. Übung zum Selbermachen

Installieren Sie in WordPress Playground das Plugin Create Block Theme und erzeugen Sie damit ein Child-Theme des Standard-Themes. Ändern Sie in dessen theme.json die Palette auf drei eigene Farben, schalten Sie freie Farben ab und geben Sie Buttons einen Rundungsradius. Legen Sie dann eine Stilvariante mit dunklen Farben an. Prüfen Sie im Website-Editor, ob die Einschränkungen greifen und die Variante auswählbar ist. Ändern Sie abschließend eine Farbe im Editor und beobachten Sie, dass Ihre Änderung in theme.json danach keine Wirkung mehr zeigt – bis Sie die Anpassung im Editor zurücksetzen.

Stand: September 2026, WordPress 7.1, PHP 8.3. Kursmaterial der Klarwerk Akademie. WordPress entwickelt sich schnell – maßgeblich ist die aktuelle Dokumentation auf developer.wordpress.org.