theme.json

Die Datei theme.json ist die zentrale Konfigurationsdatei für Block-Themes in WordPress. Sie wurde mit WordPress 5.8 eingeführt und definiert in einer strukturierten JSON-Datei, welche Gestaltungsoptionen ein Theme anbietet: Farbpaletten, Schriftarten, Abstände, Layout-Breiten und viele weitere Design-Einstellungen. Die theme.json ersetzt damit einen großen Teil des klassischen CSS und der PHP-basierten Theme-Konfiguration.

Technischer Hintergrund

Die theme.json liegt im Hauptverzeichnis eines Themes und ist in mehrere Abschnitte gegliedert. Der Abschnitt settings legt fest, welche Optionen im Block-Editor zur Verfügung stehen – etwa ob Benutzer eigene Farben wählen dürfen oder welche Schriftgrößen angeboten werden. Der Abschnitt styles definiert die Standardwerte für Farben, Typografie und Abstände auf globaler Ebene oder für einzelne Blocktypen.

Zusätzlich können über templateParts und customTemplates die verfügbaren Templates und Template-Teile deklariert werden, die im Site Editor verwendet werden können. Das Feld version gibt die Schema-Version an und bestimmt, welche Eigenschaften unterstützt werden.

WordPress verarbeitet die theme.json und generiert daraus automatisch CSS-Custom-Properties (CSS-Variablen), die im Frontend und im Editor angewendet werden. Ein Child-Theme kann eine eigene theme.json mitbringen, deren Werte die des Parent-Themes überschreiben – ähnlich wie bei Template-Dateien.

Praxisrelevanz

Für die WordPress-Wartung ist die theme.json ein wichtiges Element, weil sie Design-Entscheidungen zentralisiert und transparent macht. Anstatt Gestaltungsregeln über verschiedene CSS-Dateien, den Customizer und Theme-Optionen zu verteilen, bündelt die theme.json alles an einem Ort. Das erleichtert die Dokumentation und die Übergabe an andere Entwickler oder Wartungsdienstleister.

Bei Theme-Updates sollte geprüft werden, ob sich die theme.json des Parent-Themes geändert hat, da dies Auswirkungen auf die Darstellung haben kann.

Häufige Probleme

• Syntaxfehler in der JSON-Struktur (fehlende Kommas, falsche Klammern) führen dazu, dass die gesamte Datei ignoriert wird.
• Veraltete Schema-Versionen, die neuere Eigenschaften nicht unterstützen.
• Widersprüche zwischen Einstellungen in der theme.json und manuell eingefügtem CSS, die zu unerwartetem Verhalten führen.
• Unklare Prioritäten: Einstellungen aus der theme.json des Parent-Themes, des Child-Themes und Benutzeranpassungen im Site Editor überlagern sich in einer festen Reihenfolge.
• Fehlende Dokumentation der verwendeten Einstellungen erschwert die spätere Wartung.

Best Practices

• Die theme.json mit einem JSON-Validator prüfen, bevor sie hochgeladen wird.
• Immer die aktuelle Schema-Version verwenden, um alle verfügbaren Funktionen nutzen zu können.
• Design-Grundlagen (Farben, Schriften, Abstände) ausschließlich in der theme.json definieren, anstatt sie in separaten CSS-Dateien zu duplizieren.
• In einem Child-Theme nur die tatsächlich abweichenden Werte in der theme.json überschreiben.
• Änderungen an der theme.json versionieren und dokumentieren, da sie sich direkt auf die gesamte Website-Darstellung auswirken.