theme.json – Globale Styles und Einstellungen für WordPress
Von Felix Mit der theme.json Datei können ab WordPress 5.8 globale Stile, Stile einzelner Blöcke und Funktionen im Block-Editor individualisiert werden.
Seit WordPress 5.8 steht uns ein neuer Mechanismus zur Konfiguration des Blockeditors (Gutenberg) zur Verfügung: die Datei theme.json. Sie gibt uns eine sehr einfache Möglichkeit globale Stile, Stile einzelner Blöcke und auch Funktionen im Blockeditor zu individualisieren oder deaktivieren.
Funktionsweise der theme.json
Unabhängig vom verwendeten Theme arbeitet WordPress schon mit Voreinstellungen für Farben, Farbverläufe, Schriftgrößen usw. Solltet ihr das Gutenberg-Plugin installiert haben, werden die Presets aus dem WordPress Core noch einmal um experimentelle Gutenberg-Voreinstellungen erweitert.
Alle diese Voreinstellungen könnt ihr via theme.json neu deklarieren und damit schon einen Großteil des Basis-Stylings eures Themes beeinflussen. Der sog. WordPress »Site-Editor«, der zusammen mit »Full Site Editing« in WordPress Einzug hält, bietet zudem eine grafische Oberfläche zum Anpassen der Voreinstellungen.
Um mit der Individualisierung zu Beginnen, erstellt ihr, mit einem Text-Editor eurer Wahl, eine leere Datei und fügt folgende Zeilen Code ein:
{
"version": 1,
"settings": {},
"styles": {}
}Die version gibt die Version der Datei an. Aktuell ist nur 1 als Wert möglich. In Zukunft soll die Version dann verwendet werden können, um unterschiedliche Formate der theme.json-Datei zu unterstützen.
- In
settingshabt ihr die Möglichkeit einzelne Blockeditor-Funktion zu aktivieren/deaktivieren und die Presets zu überschreiben. - In
styleskönnt ihr die Standard-Werte vordefinierter CSS-Eigenschaften festlegen. Es ist abhängig vom jeweiligen Block, ob und welche Angaben verwendet werden.
Speichert die theme.json im Hauptverzeichnis eures Themes ab. WordPress findet diese Datei automatisch und wendet die Einstellungen an.
Beispiel: Farbpalette im Editor anpassen
Mit folgendem Code-Schnipsel passen wir die Standard-Farbpalette im Blockeditor an. Die Standard-Farbpalette wird dadurch nicht ergänzt, sondern überschrieben. Die CSS Variablen aus dem WordPress Core bleiben im Code bestehen, sind redaktionell im Editor allerdings nicht mehr zugänglich.
{
"version": 1,
"settings": {
"color": {
"palette": [
{
"name": "kulturbanause Grün",
"slug": "kb-green",
"color": "#8bb300"
},
{
"name": "kulturbanause Petrol",
"slug": "kb-petrol",
"color": "#007c86"
}
]
}
}
}Die Werte, die ihr in die theme.json eintragt, werden in CSS Variablen und CSS-Klassen umgewandelt. Sie stehen euch dann sowohl im Blockeditor, als auch im Frontend zur Verfügung. WordPress rendert sie inline in den <head> eures Themes. Übersetzt in Custom Properties (CSS Variablen) sieht das dann im Browser wie folgt aus:
body {
// Custom Properties aus dem WordPress Core
--wp--preset--color--black: #000;
--wp--preset--color--cyan-bluish-gray: #abb8c3;
--wp--preset--color--white: #fff;
--wp--preset--color--pale-pink: #f78da7;
--wp--preset--color--vivid-red: #cf2e2e;
--wp--preset--color--luminous-vivid-orange: #ff6900;
--wp--preset--color--luminous-vivid-amber: #fcb900;
--wp--preset--color--light-green-cyan: #7bdcb5;
--wp--preset--color--vivid-green-cyan: #00d084;
--wp--preset--color--pale-cyan-blue: #8ed1fc;
--wp--preset--color--vivid-cyan-blue: #0693e3;
--wp--preset--color--vivid-purple: #9b51e0;
// Unsere Ergänzungen via theme.json
--wp--preset--color--kb-green: #8bb300;
--wp--preset--color--kb-petrol: #007c86;
}Wie ihr seht, werden die Custom Properties von WordPress in den body-Selektor geschrieben, nicht etwa in das :root-Element. Das nur als Hinweis an dieser Stelle.
Zusätzlich zu den Presets könnt ihr auch benutzerdefinierte Eigenschaften mit settings.custom definieren. Diese Einträge erzeugen dann zusätzliche Custom Properties für Editor und Frontend.
{
"version": 1,
"settings": {
"custom": {
"line-height": {
"body": 1.618,
"title": 1.4
}
}
}
}Dies erzeugt folgende zusätzliche Custom Properties:
body {
--wp--custom--line-height--body: 1.618;
--wp--custom--line-height--heading: 1.4;
}theme.json Standardwerte für settings und styles
Hier eine Übersicht aller aktuellen Einstellungsmöglichkeiten unter settings:
{
"version": 1,
"settings": {
"color": {
"custom": true,
"customDuotone": true,
"customGradient": true,
"duotone": [],
"gradients": [],
"palette": [],
"link": true
},
"custom": {},
"layout": {
"contentSize": "666px",
"wideSize": "1024px"
},
"spacing": {
"customMargin": true,
"customPadding": true,
"units": [
"px",
"em",
"rem",
"vh",
"vw"
]
},
"typography": {
"customFontSize": true,
"customLineHeight": true,
"dropCap": true,
"fontSizes": []
}
}
}Folgend eine Übersicht der aktuellen Einstellungsmöglichkeiten unter styles. Diese Angaben haben direkte Auswirkungen auf das Styling des jeweiligen Elements und erzeugen kein Bedienfeld im Editor:
{
"version": 1,
"styles": {
"color": {
"background": "value",
"gradient": "value",
"text": "value"
},
"spacing": {
"margin": {
"top": "value",
"right": "value",
"bottom": "value",
"left": "value"
},
"padding": {
"top": "value",
"right": "value",
"bottom": "value",
"left": "value"
}
},
"typography": {
"fontSize": "value",
"lineHeight": "value"
},
"elements": {
"link": {
"color": {},
"spacing": {},
"typography": {}
},
"h1": {},
"h2": {},
"h3": {},
"h4": {},
"h5": {},
"h6": {}
},
}
}Blockspezifische Einstellungen und Styles
Zusätzlich zu den globalen Einstellungen könnt ihr auch spezifische Anpassungen pro Block vornehmen. Folgendes Beispiel ändert nur die Farbpalette für den Block Gruppe:
{
"version": 1,
"settings": {
"blocks": {
"core/group": {
"color": {
"palette": [
{
"name": "kulturbanause Grün",
"slug": "kb-green",
"color": "#8bb300"
},
{
"name": "kulturbanause Petrol",
"slug": "kb-petrol",
"color": "#007c86"
}
]
}
}
}
}
}Ebenfalls pro Block, können Styles vordefiniert werden:
{
"version": 1,
"styles": {
"blocks": {
"core/group": {
"color": {
"text": "#fffff",
"background": "#8bb300"
},
"spacing": {},
"typography": {},
"elements": {
"link": {},
"h1": {},
"h2": {},
"h3": {},
"h4": {},
"h5": {},
"h6": {}
}
},
"etc": {}
}
}
}Welche Angaben pro Block verfügbar und damit auch anpassbar sind, ist vom jeweiligen Block abhängig. Zum Erscheinungsdatum von WordPress 5.8 unterstützen beispielsweise nur die wenigsten Blöcke die Spacing-Eigenschaften customMargin oder customPadding. Die Website CSS Tricks hat eine umfangreiche Liste aller Einstellungen veröffentlicht.
Geschrieben von Felix Lehmann
Als Web-Designer und Frontend-Developer bei kulturbanause umfasst Felix Hauptaufgabenbereich die Konzeption, Gestaltung und Umsetzung von Designsystemen. Scribble auf Papier, Prototyping im Design-Tool, schnellstmöglich in den Browser und mit CSS umsetzen. Auch das Überführen in ein Custom WordPress-Theme ist kein Problem. Die meiste Zeit verbringt er trotzdem damit die richtigen Klassennamen zu finden.
Hallo Felix,
vielen Dank für Deine Arbeit und Deinen Erläuterungen. Ich bin erst am Anfang meiner Arbeit mit dem FSE – ich hänge immer noch sehr an der „klassischen Themeentwicklung – und sehe mir daher ein paar FSE-Tutorials parallel an. Dabei ist mir ein Punkt aufgefallen, der bei Dir nicht mehr aktuell ist: Gleich zu Beginn schreibst Du, es gebe in der theme.json nur die Version 1, was nicht mehr stimmt. Seit WP 5.9 gibt es Version 2. Da ich – wie geschrieben – noch am Anfang mit FSE stehe, weiß ich nicht welche Änderungen von v1 zu v2 umgesetzt wurden. Aber vielleicht weißt du es und kannst in einer neuen Version darauf eingehen.
Viele Grüße
Frank