WordPress Block-Theme mit theme.json anpassen: Farben, Breiten und Stile
So passen Sie ein Block-Theme wie Twenty Twenty-Five mit einer eigenen theme.json im Child-Theme an: Firmenfarben, Inhaltsbreite, Sperren für Redakteure und Stilvarianten.
Mit KI erstellt – redaktionelle Prüfung ausstehend
WerbelinksMit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Mehr dazu
Block-Themes wie Twenty Twenty-Five legen Farben, Schriften, Abstände und Inhaltsbreiten nicht mehr hauptsächlich in CSS fest, sondern in einer Datei namens theme.json. Sie steuert, was auf der Website erscheint, und zugleich, welche Werkzeuge Redakteure im Block-Editor überhaupt angeboten bekommen. Wer ein Block-Theme an das Erscheinungsbild seines Unternehmens anpassen will, kommt an dieser Datei kaum vorbei. Diese Anleitung zeigt, wie Sie eine eigene theme.json in einem Child-Theme anlegen, Firmenfarben und Layoutbreiten setzen, Einstellungen für Redakteure sperren, eine Stilvariante ergänzen und verstehen, warum Änderungen manchmal nicht sichtbar werden.
Voraussetzungen
- WordPress ab Version 6.6, weil die Dateiversion 3 der
theme.jsondiese Version voraussetzt. Getestet mit WordPress 7.1.2. - Ein aktives Block-Theme, zum Beispiel Twenty Twenty-Five. Klassische Themes ohne Website-Editor nutzen
theme.jsonnur eingeschränkt. - Zugriff auf die Dateien per SFTP, FTP oder SSH und die Rolle Administrator im Backend.
- Einen Texteditor, der JSON prüft, etwa Visual Studio Code. Ein einziges fehlendes Komma macht die Datei unbrauchbar.
- Ein aktuelles Backup von Dateien und Datenbank. Am besten arbeiten Sie zuerst auf einer Staging-Kopie.
Schritt 1: Verstehen, welche Ebene gewinnt
Das Theme-Handbuch auf developer.wordpress.org beschreibt vier Ebenen, die WordPress nacheinander zusammenführt. Ganz unten liegt die theme.json von WordPress selbst mit Grundeinstellungen. Darüber kommt die Datei des Eltern-Themes, dann die des Child-Themes. Ganz oben stehen die Anpassungen, die jemand im Website-Editor unter Design > Editor > Stile gespeichert hat. Diese oberste Ebene liegt in der Datenbank, nicht im Dateisystem.
Daraus folgen zwei praktische Regeln. Erstens gewinnt eine Einstellung im Website-Editor immer gegen Ihre Datei. Ändern Sie also die Linkfarbe in der theme.json und sehen nichts, hat vermutlich jemand die Linkfarbe im Editor festgelegt. Zweitens sollte die Datei der Ort für dauerhafte, dokumentierte Vorgaben sein, der Editor der Ort für schnelle Versuche. Die Datei lässt sich versionieren und auf andere Websites übertragen, die Datenbankeinträge nicht so einfach.
Verifizieren: Öffnen Sie Design > Editor > Stile und prüfen Sie über das Menü mit den drei Punkten, ob Stile zurücksetzen aktiv ist. Ist der Eintrag auswählbar, gibt es bereits gespeicherte Anpassungen in der Datenbank.
Schritt 2: Child-Theme mit eigener theme.json anlegen
Updates des Eltern-Themes ersetzen dessen Dateien vollständig. Deshalb gehören Ihre Änderungen in ein Child-Theme. Wie Sie es anlegen und warum es sich lohnt, erklärt ausführlich die Anleitung Child-Theme anlegen und Anpassungen bei Updates behalten. Für diese Anleitung genügt ein Ordner wp-content/themes/firma-child mit einer style.css:
/*
Theme Name: Firma Child
Template: twentytwentyfive
Version: 1.0.0
*/Die Zeile Template enthält den Ordnernamen des Eltern-Themes. Daneben legen Sie eine leere Datei theme.json an. Das Handbuch hält fest, dass die theme.json des Child-Themes die des Eltern-Themes überschreibt. Sie müssen also nicht alles kopieren, sondern nur die Werte eintragen, die sich ändern sollen. Alles andere erbt das Child-Theme.
Verifizieren: Unter Design > Themes erscheint „Firma Child“. Nach dem Aktivieren zeigt wp theme list das Child-Theme als active und Twenty Twenty-Five als parent.
Schritt 3: Firmenfarben und Layoutbreiten festlegen
Die folgende Datei setzt drei Farben, eine schmalere Inhaltsbreite und einige Stile. Die Zeile $schema ist optional, sorgt aber dafür, dass Editoren wie Visual Studio Code Eigenschaften vorschlagen und Tippfehler markieren:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "base", "color": "#FFFFFF", "name": "Hintergrund" },
{ "slug": "contrast", "color": "#1A1A2E", "name": "Text" },
{ "slug": "accent-1", "color": "#0057B8", "name": "Firmenblau" }
],
"custom": false
},
"layout": { "contentSize": "720px", "wideSize": "1200px" },
"blocks": {
"core/paragraph": { "typography": { "customFontSize": false } }
}
},
"styles": {
"elements": {
"link": { "color": { "text": "var(--wp--preset--color--accent-1)" } },
"button": { "border": { "radius": "4px" }, "color": { "background": "var(--wp--preset--color--accent-1)" } }
},
"blocks": {
"core/heading": { "typography": { "fontWeight": "700" } }
}
}
}Die Slugs base, contrast und accent-1 stammen aus Twenty Twenty-Five. Behalten Sie die Slugs des Eltern-Themes bei, dann greifen dessen Vorlagen und Muster automatisch auf Ihre neuen Farbwerte zu. WordPress erzeugt aus jedem Eintrag eine CSS-Variable nach dem Muster --wp--preset--color--accent-1, auf die Sie unter styles verweisen.
Ein wichtiger Punkt, der im Test sichtbar wurde: Eine eigene Palette ergänzt die Palette des Eltern-Themes nicht, sie ersetzt sie. Twenty Twenty-Five bringt die Farben accent-2 bis accent-6 mit. Nach dem Aktivieren der obigen Datei tauchten diese Variablen im Quelltext nicht mehr auf. Nutzen Muster oder bestehende Seiten solche Farben, verlieren sie ihre Farbe. Übernehmen Sie deshalb alle Paletteneinträge des Eltern-Themes, die Sie weiter brauchen, und ändern Sie nur deren Werte.
Verifizieren: Rufen Sie die Startseite auf und suchen Sie im Seitenquelltext nach --wp--preset--color--accent-1. Im Test stand dort #0057B8 und bei --wp--style--global--content-size der Wert 720px.
Schritt 4: Werkzeuge für Redakteure gezielt einschränken
Der Bereich settings legt nicht nur Werte fest, sondern auch, welche Regler im Block-Editor erscheinen. In der Beispieldatei sorgt "custom": false unter color dafür, dass Redakteure keine freien Farben mehr wählen können, sondern nur die drei Firmenfarben. "customFontSize": false unter blocks gilt nur für den Absatz-Block und entfernt dort die freie Eingabe einer Schriftgröße. Die voreingestellten Größen bleiben verfügbar.
Solche Sperren schützen das Corporate Design, wenn mehrere Personen Inhalte pflegen. Der Nachteil: Wer tatsächlich einmal eine Sonderfarbe braucht, muss Sie fragen. Wägen Sie ab, wie viel Freiheit Ihr Team braucht. Umgekehrt schaltet "appearanceTools": true auf einen Schlag viele Werkzeuge frei, etwa Rahmen, Abstände und Zeilenhöhe. Twenty Twenty-Five aktiviert diese Einstellung bereits, Ihr Child-Theme erbt sie.
Verifizieren: Öffnen Sie einen Beitrag, markieren Sie einen Absatz und öffnen Sie in der Seitenleiste die Farbeinstellungen. Es erscheinen nur die Firmenfarben, das Feld für eine eigene Farbe fehlt. Per WP-CLI liefert wp eval 'echo wp_json_encode(wp_get_global_settings(["color","custom"]));' den Wert false.
Schritt 5: Stilvariante für eine alternative Gestaltung anlegen
Laut Theme-Handbuch sind Stilvarianten alternative Fassungen der theme.json, die im Unterordner styles des Themes liegen. Redakteure können sie im Website-Editor mit einem Klick auswählen. Das eignet sich etwa für eine dunkle Gestaltung oder ein saisonales Erscheinungsbild. Legen Sie dazu styles/firma-dunkel.json an:
{
"version": 3,
"title": "Firma dunkel",
"settings": {
"color": {
"palette": [
{ "slug": "base", "color": "#1A1A2E", "name": "Hintergrund" },
{ "slug": "contrast", "color": "#FFFFFF", "name": "Text" }
]
}
}
}Der Eintrag title ist der Name, der im Editor erscheint. Im Test listete WordPress die neue Variante zusammen mit den Varianten des Eltern-Themes auf. Auch hier gilt: Die Palette der Variante ersetzt die gesamte Palette, deshalb fehlt in diesem kurzen Beispiel accent-1. In der Praxis übernehmen Sie alle Einträge.
Verifizieren: Unter Design > Editor > Stile über Stile durchstöbern erscheint „Firma dunkel“ als Auswahl.
Schritt 6: Änderungen sichtbar machen und Editor-Anpassungen zurücksetzen
Wenn eine Änderung in der Datei nicht ankommt, gibt es drei typische Gründe. Häufig ist die Datei ungültig: Ein überzähliges Komma genügt, und WordPress ignoriert die komplette Child-Datei stillschweigend. Im Test fiel die Website dann auf die Farben und Breiten des Eltern-Themes zurück, ohne Fehlermeldung. Prüfen Sie die Datei auf dem Server so:
php -r 'json_decode(file_get_contents("theme.json")); echo json_last_error_msg(), PHP_EOL;'Die Ausgabe No error bedeutet gültiges JSON, Syntax error weist auf einen Fehler hin. Zweitens kann ein Cache-Plugin oder der Browser alte Stile ausliefern, leeren Sie beides. Drittens überdecken gespeicherte Anpassungen aus dem Website-Editor Ihre Datei. Im Test setzte eine Linkfarbe aus dem Editor den Wert aus der theme.json außer Kraft, bis die Anpassung entfernt war. Zurücksetzen können Sie das unter Design > Editor > Stile über das Menü mit den drei Punkten und Stile zurücksetzen.
Setzen Sie Stile nur zurück, wenn Sie wissen, was im Editor gespeichert wurde. Die Aktion entfernt alle Anpassungen dieser Ebene. Exportieren Sie vorher die Datenbank, etwa mit wp db export. Wie Sie WP-CLI dafür einrichten, beschreibt die Anleitung WP-CLI installieren und die wichtigsten Befehle nutzen.
Ein Child-Theme mit eigener theme.json nimmt Ihnen Arbeit bei Theme-Updates ab, die Updates selbst bleiben aber. Nach jedem Update des Eltern-Themes lohnt ein kurzer Blick, ob neue Paletteneinträge oder Muster hinzugekommen sind. Wer diese laufende Pflege nicht selbst übernehmen möchte, kann sie abgeben: Die WordPress-Wartung von wordpressupdate.de spielt Updates von WordPress, Plugins und Themes mit Kompatibilitätsprüfung ein und sichert die Website wöchentlich auf externen Speicher.
Verifizieren: Nach dem Zurücksetzen zeigt der Seitenquelltext wieder die Werte aus Ihrer Datei, zum Beispiel a:where(:not(.wp-element-button)){color: var(--wp--preset--color--accent-1);} für Links.
Typische Fehler
| Symptom | Ursache | Lösung |
|---|---|---|
| Keine Änderung sichtbar, Website sieht aus wie das Eltern-Theme | Ungültiges JSON, die Datei wird komplett ignoriert | Mit php -r oder im Editor prüfen, Komma und Klammern kontrollieren |
| Einzelne Werte wie die Linkfarbe greifen nicht | Anpassung im Website-Editor gespeichert, sie hat Vorrang | Stile zurücksetzen oder den Wert im Editor ändern |
| Muster und Buttons verlieren ihre Farbe | Eigene Palette hat Einträge des Eltern-Themes ersetzt | Alle benötigten Slugs des Eltern-Themes in die Child-Palette übernehmen |
| Neue Eigenschaften werden ignoriert | Datei nutzt "version": 2 oder die Eigenschaft gibt es in dieser WordPress-Version noch nicht | "version": 3 setzen, Eigenschaft in der theme.json-Referenz nachschlagen |
| Stilvariante erscheint nicht | Datei liegt nicht im Ordner styles oder title fehlt | Pfad styles/NAME.json prüfen, Titel ergänzen |
Häufige Fragen
Kann ich statt eines Child-Themes die theme.json des Eltern-Themes bearbeiten?
Technisch ja, aber das nächste Update des Themes überschreibt die Datei. Bei Standard-Themes wie Twenty Twenty-Five kommen solche Updates regelmäßig, oft automatisch. Ein Child-Theme kostet wenige Minuten und verhindert diesen Verlust.
Brauche ich noch zusätzliches CSS?
Für Farben, Schriften, Abstände und Breiten meist nicht. Für Details, die theme.json nicht abbildet, bleibt die style.css des Child-Themes oder das Feld für zusätzliches CSS im Website-Editor. Halten Sie beides klein, denn verstreutes CSS macht spätere Änderungen mühsam.
Wie binde ich eigene Schriften ein?
Über settings.typography.fontFamilies mit Schriftdateien, die im Theme liegen. So laden Besucher keine Schriften von fremden Servern, was auch datenschutzrechtlich wichtig ist. Hintergründe dazu liefert die Anleitung Google Fonts lokal einbinden.
Wirkt sich theme.json auf die Ladezeit aus?
WordPress erzeugt aus der Datei ein Stylesheet, das direkt in die Seite geschrieben wird. Eine schlanke Datei hält dieses Stylesheet klein. Große Paletten und viele Schriftgrößen vergrößern es, spürbar wird das aber erst bei sehr umfangreichen Dateien.
Testumfang
Wir haben unter WordPress 7.1.2 ein Child-Theme für Twenty Twenty-Five mit der gezeigten theme.json eingerichtet, und die Stile kamen auf der Startseite an. Auffällig war, dass eine fehlerhafte Datei ohne jeden Hinweis ignoriert wird und die eigene Palette die Farben des Eltern-Themes verdrängt.
Den Website-Editor haben wir nicht per Klick im Browser geprüft, sondern nur über Übersetzungen und gespeicherte Daten. Kontrollieren Sie die Menüpunkte daher in Ihrem Backend und testen Sie andere Block-Themes zuerst auf einer Kopie.
Fazit
Mit einer eigenen theme.json im Child-Theme bringen Sie ein Block-Theme sauber auf Ihr Firmendesign, ohne bei Updates Arbeit zu verlieren. Achten Sie auf gültiges JSON, übernehmen Sie die Paletten-Slugs des Eltern-Themes und denken Sie daran, dass Editor-Anpassungen Vorrang haben. Die regelmäßigen Theme- und Plugin-Updates danach übernimmt auf Wunsch die WordPress-Wartung von Marcel Schönfelder.
