--- title: "WordPress Block-Theme mit theme.json anpassen: Farben, Breiten und Stile" date: 2026-09-30T22:45:20+02:00 modified: 2026-10-23T22:07:31+02:00 category: wordpress type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/wordpress-block-theme-anpassen-theme-json-child-theme keywords: - WordPress - theme.json - Block-Theme - Child-Theme - Design reading_time: 9 --- # WordPress Block-Theme mit theme.json anpassen: Farben, Breiten und Stile 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. **Kurzfassung:** Bearbeiten Sie nie die `theme.json` des Eltern-Themes, sonst überschreibt das nächste Theme-Update Ihre Arbeit. Legen Sie ein Child-Theme an und geben Sie ihm eine eigene `theme.json` mit `"version": 3`. Unter `settings` definieren Sie Farbpalette, Breiten und erlaubte Werkzeuge, unter `styles` das Aussehen von Links, Buttons und Blöcken. Eine eigene Palette ersetzt die des Eltern-Themes vollständig. Anpassungen aus dem Website-Editor liegen in der Datenbank und haben Vorrang vor der Datei. ## Voraussetzungen - [ ] WordPress ab Version 6.6, weil die Dateiversion 3 der `theme.json` diese Version voraussetzt. Getestet mit WordPress 7.1.2. - [ ] Ein aktives Block-Theme, zum Beispiel Twenty Twenty-Five. Klassische Themes ohne Website-Editor nutzen `theme.json` nur 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. > **Prüfen:** Ö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](https://s-edv.com/anleitungen/wordpress-child-theme-anlegen-theme-updates-anpassungen-behalten). Für diese Anleitung genügt ein Ordner `wp-content/themes/firma-child` mit einer `style.css`: Datei: `style.css` ```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. > **Prüfen:** 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: ```json { "$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. > **Prüfen:** 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. > **Prüfen:** Ö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: Datei: `styles/firma-dunkel.json` ```json { "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. > **Prüfen:** 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: ```bash $ 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](https://s-edv.com/anleitungen/wordpress-wp-cli-installieren-wichtigste-befehle-admins). 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](https://wordpressupdate.de/?utm_source=s-edv.com&utm_medium=artikel&utm_campaign=115) spielt Updates von WordPress, Plugins und Themes mit Kompatibilitätsprüfung ein und sichert die Website wöchentlich auf externen Speicher. > **Prüfen:** 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](https://s-edv.com/anleitungen/wordpress-google-fonts-lokal-einbinden-datenschutz). ### 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. ## 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](https://wordpressupdate.de/?utm_source=s-edv.com&utm_medium=fazit&utm_campaign=115) von Marcel Schönfelder. ## Weiterführende Anleitungen und Quellen - [Child-Theme anlegen und Anpassungen bei Updates behalten](https://s-edv.com/anleitungen/wordpress-child-theme-anlegen-theme-updates-anpassungen-behalten) - [Google Fonts lokal einbinden](https://s-edv.com/anleitungen/wordpress-google-fonts-lokal-einbinden-datenschutz) - [Staging-Umgebung mit WP-CLI einrichten](https://s-edv.com/anleitungen/wordpress-staging-umgebung-wp-cli-einrichten) - [Theme-Handbuch: Global Settings and Styles (theme.json)](https://developer.wordpress.org/themes/global-settings-and-styles/) - [Theme-Handbuch: Style Variations](https://developer.wordpress.org/themes/global-settings-and-styles/style-variations/) - [Referenz: theme.json Version 3](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/)