Was gehört in eine theme.json-Datei in WordPress?

Eine theme.json-Datei in WordPress ist eine JSON-Datei im Stammverzeichnis eines Block-Themes. Sie legt die Design-Tokens des Themes (Farben, Schriftgrößen, Schriftfamilien, Abstände und Layoutbreiten) an einer zentralen Stelle fest, sodass Block-Editor und Frontend dieselben Werte verwenden.

Wer bereits mit Design-Token-Pipelines arbeitet, findet sich in der Datei schnell zurecht. Schwieriger wird es, wenn man das daraus generierte CSS sucht oder herausfinden muss, warum ein Child-Theme die halbe Farbpalette gelöscht hat. Dieser Artikel geht jeden Bereich der Datei durch, zeigt das CSS, das WordPress daraus erzeugt, erklärt, wie Sie diese Variablen in Ihrem eigenen Stylesheet verwenden, und beschreibt, wo weiterhin handgeschriebenes CSS nötig ist. Alle Beispiele verwenden Schema-Version 3, die mit WordPress 6.6 eingeführt wurde.

Was ist theme.json?

theme.json ist die Design-Token-Datei eines Block-Themes. Farben, Typografie, Abstände und Layoutbreiten werden darin einmalig deklariert. WordPress nutzt diese Werte anschließend, um die Steuerelemente des Editors aufzubauen und das Frontend-Stylesheet zu generieren. Die oberste Ebene ist überschaubar: $schema, version, settings und styles sowie customTemplates, templateParts und patterns zum Registrieren von Templates, Template-Teilen und Patterns aus dem Pattern-Verzeichnis.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {}
}

Wenn $schema auf das theme.json-Schema aus dem Trunk verweist, erhalten Sie in VS Code Autovervollständigung und Validierung.

Warum gibt es theme.json?

theme.json ersetzt drei Dinge, die früher leicht auseinanderliefen: add_theme_support()-Flags in PHP, die Editor-Konfiguration und das Frontend-CSS. Der Leitfaden zu globalen Einstellungen im Block Editor Handbook ordnet jedem älteren add_theme_support-Flag einen theme.json-Schlüssel zu. Legt ein Theme denselben Wert an beiden Stellen fest, hat der Wert aus theme.json Vorrang.

Was gehört in settings?

settings steuert, was der Editor anbietet: welche Presets in den Auswahlfeldern erscheinen und welche freien Steuerelemente erlaubt sind. Presets sind Arrays aus Objekten, die jeweils einen slug, einen Wert und einen Anzeigenamen (name) enthalten.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "custom": false,
      "customGradient": false,
      "defaultPalette": false,
      "palette": [
        { "slug": "ink", "color": "#1b1f24", "name": "Ink" },
        { "slug": "accent", "color": "#3b5bdb", "name": "Accent" }
      ]
    },
    "typography": {
      "customFontSize": false,
      "defaultFontSizes": false,
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ],
      "fontFamilies": [
        { "slug": "system", "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif", "name": "System" }
      ]
    },
    "spacing": { "blockGap": true, "units": ["px", "rem", "%"] },
    "layout": { "contentSize": "720px", "wideSize": "1100px" },
    "custom": { "radius": { "card": "12px" } }
  }
}

Wenn Sie color.custom, customGradient und customFontSize auf false setzen, entfallen die freien Auswahlwerkzeuge, und Redakteure können nur noch aus Ihren Presets wählen. defaultFontSizes: false ist in Version 3 besonders wichtig. Laut der Dev Note zu theme.json Version 3 kann ein v3-Theme die Slugs der Core-Standardschriftgrößen und -Standardabstände nur dann wiederverwenden, wenn defaultFontSizes bzw. defaultSpacingSizes auf false gesetzt ist – und sowohl small als auch large sind Core-Slugs. appearanceTools: true aktiviert eine Gruppe von Designwerkzeugen, die in der Living Reference zu theme.json aufgeführt sind. Wenn Sie Webfonts für fontFamilies laden, lesen Sie wie Sie Google Fonts in WordPress selbst hosten.

Jeder Preset-Typ erzeugt eine andere Ausgabe:

theme.json enthält zwei voneinander unabhängige custom-Schlüssel. settings.color.custom: false blendet den Farbwähler aus. settings.custom ist ein frei definierbares Objekt, dessen Werte zu CSS-Variablen werden.

Wie funktionieren layout.contentSize und wideSize?

layout.contentSize legt die Standardbreite von Inhalten in eingeschränkten Layouts (Constrained Layouts) fest. layout.wideSize bestimmt die Breite von Blöcken mit der Ausrichtung „Weite Breite“. Core stellt beide Werte als --wp--style--global--content-size und --wp--style--global--wide-size auf :root bereit, nachdem Gutenberg PR #42084 globale Custom Properties von body dorthin verschoben hat. Eigene Komponenten lassen sich dadurch am Block-Raster ausrichten:

.site-banner {
  max-width: var(--wp--style--global--wide-size);
  margin-inline: auto;
}

Was gehört in styles?

styles weist Standardwerte auf drei Ebenen zu. Properties auf oberster Ebene gelten für body, elements richtet sich an HTML-Elemente wie link (entspricht a) und h1 bis h6, und blocks adressiert einzelne Blöcke über ihren Namen. Der Styles-Abschnitt des Handbooks dokumentiert jede dieser Ebenen.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "styles": {
    "color": { "text": "var(--wp--preset--color--ink)" },
    "spacing": { "blockGap": "1.5rem" },
    "blocks": {
      "core/group": {
        "color": { "text": "var(--wp--preset--color--accent)" },
        "elements": {
          "h2": { "typography": { "fontSize": "var(--wp--preset--font-size--large)" } }
        }
      }
    }
  }
}

Ausgabe:

body {
  color: var(--wp--preset--color--ink);
}
:root :where(.wp-block-group) {
  color: var(--wp--preset--color--accent);
}
:root :where(.wp-block-group h2) {
  font-size: var(--wp--preset--font-size--large);
}

Seit WordPress 6.6 hält der :root :where()-Wrapper diese Regeln auf einer Spezifität von 0-1-0 – also genauso hoch wie eine einzelne Klasse. Jede Theme-Regel mit gleicher oder höherer Spezifität, die später geladen wird, setzt sich durch. Die Elemente link und button akzeptieren zusätzlich Schlüssel für Pseudo-Zustände wie ":hover" und ":focus".

Welches CSS erzeugt WordPress aus theme.json?

Jedes Preset mit Ausnahme der Duotone-Filter wird zu einer CSS Custom Property nach dem Muster --wp--preset--{category}--{slug}. Presets, die Klassen erzeugen, folgen dem Muster .has-{slug}-{category}. Werte unter settings.custom werden zu --wp--custom---Properties. WordPress wandelt camelCase-Schlüssel in kebab-case um und setzt -- zwischen jede Verschachtelungsebene, sodass aus custom.lineHeight.body die Property --wp--custom--line-height--body wird. Die Namens-FAQ im Handbook schlüsselt den Namen Segment für Segment auf.

Mit den oben gezeigten Settings und Styles enthält das globale Stylesheet eine Ausgabe wie die folgende. Die Beispiele im Handbook zeigen body, aktuelle Core-Versionen deklarieren diese Properties jedoch auf :root – eine Änderung, die mit Gutenberg PR #42084 eingeführt wurde:

:root {
  --wp--preset--color--ink: #1b1f24;
  --wp--preset--color--accent: #3b5bdb;
  --wp--preset--font-size--large: 1.5rem;
  --wp--custom--radius--card: 12px;
  --wp--style--block-gap: 1.5rem;
}
.has-accent-color { color: var(--wp--preset--color--accent) !important; }

Der Root-Wert styles.spacing.blockGap wird als --wp--style--block-gap bereitgestellt. Ob Redakteure ihn ändern können, hängt von settings.spacing.blockGap ab:

Da es sich um gewöhnliche Custom Properties handelt, kann jedes Stylesheet sie verwenden:

.pricing-card {
  background: var(--wp--preset--color--ink);
  color: #fff;
  border-radius: var(--wp--custom--radius--card);
  padding: var(--wp--style--block-gap);
  font-size: var(--wp--preset--font-size--large);
}

Ändern Sie einen Token in theme.json, passt sich diese Komponente automatisch an. Die Ausgabe von theme.json wird gecacht. Setzen Sie daher während der Entwicklung WP_DEVELOPMENT_MODE in der wp-config.php auf 'theme'.

Was kann theme.json nicht, und wie werden Child-Themes zusammengeführt?

theme.json deckt nur Properties ab, die im Styles-Schema enthalten sind. Alles andere gehört ins CSS:

• Layout für Markup, das kein Block ist, etwa Ausgaben von Plugins oder Drittanbietern
• Animationen, Transitions und Keyframes
• Beliebige Selektoren, die nicht an einen Block oder ein Element gebunden sind
• Komponenten-Styling, das über die verfügbaren Style-Properties hinausgeht (der Leitfaden zum responsiven WordPress-Theme mit Bootstrap zeigt den CSS-zentrierten Ansatz)

style.css ist weiterhin erforderlich, da sie den Theme-Header enthält. Bei einem Child-Theme verweist das Feld Template auf das Parent-Theme – und zwar über dessen Ordnernamen in wp-content/themes, in exakt derselben Schreibweise. Das erläutert die Seite zum Haupt-Stylesheet im Theme Handbook:

/*
Theme Name: Studio Child
Template: studio
*/

Die theme.json eines Child-Themes wird mit der des Parent-Themes zusammengeführt. Jede Preset-Liste, die das Child-Theme deklariert, ersetzt die entsprechende Liste des Parent-Themes jedoch vollständig. Mit dieser Child-Datei bleibt nur eine einzige Farbe in der Palette übrig:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "accent", "color": "#c2255c", "name": "Accent" }
      ]
    }
  }
}

Um nur accent zu ändern, kopieren Sie die gesamte Palette und bearbeiten lediglich diesen einen Eintrag:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "ink", "color": "#1b1f24", "name": "Ink" },
        { "slug": "accent", "color": "#c2255c", "name": "Accent" }
      ]
    }
  }
}

Objektschlüssel, die Sie in der theme.json des Child-Themes nicht deklarieren, werden weiterhin vom Parent-Theme geerbt. Setzt das Child-Theme beispielsweise nur styles.spacing.padding.top und bottom, bleibt das linke und rechte Padding des Parent-Themes erhalten. Wenn ein entfernter Slug dazu führt, dass Inhalte auf der Live-Website auf eine andere Farbe zurückfallen, in der Editor-Vorschau aber nicht, zeigt ein Session-Replay des Frontends, welches Element und welches Template das Preset verloren hat.

Fazit

theme.json ist eine Token-Datei, die WordPress in Custom Properties, Utility-Klassen und Standardregeln mit niedriger Spezifität kompiliert. Halten Sie Presets in settings, Standardwerte in styles und alles Weitere in CSS, das die generierten --wp---Variablen verwendet. Als nächsten Schritt öffnen Sie auf einer Seite mit Ihrem Theme global-styles-inline-css in den Entwicklertools Ihres Browsers und vergleichen die deklarierten Properties mit Ihrer Datei. Jeder fehlende Token weist auf einen Fehler im Slug oder im Schema hin, den Sie beheben können, bevor er Ihre Nutzer erreicht.

FAQs

Warum erscheint ein Wert, den ich in theme.json geändert habe, nicht auf meiner Website?

Eine gespeicherte Anpassung aus dem Website-Editor überschreibt ihn. Ändert ein Benutzer Stile unter Design > Editor, speichert WordPress dieses JSON in der Datenbank der Website. Laut Theme Handbook hat diese Benutzerkonfiguration Vorrang vor den Core-Standardwerten, der theme.json des Parent-Themes und der theme.json des Child-Themes. Prüfen Sie, ob der Token im Bereich Stile angepasst wurde, setzen Sie ihn dort zurück und laden Sie anschließend das Frontend neu.

Kann ich rohes CSS direkt in theme.json schreiben?

Ja. Seit WordPress 6.2 akzeptiert theme.json CSS-Strings in styles.css für globale Regeln sowie in der css-Property eines Blocks unter styles.blocks für blockspezifische Regeln. Blockspezifisches CSS erscheint für den jeweiligen Block im Bereich Stile, wo Benutzer es bearbeiten können. Benutzerdefiniertes CSS kann auf diese Weise hinzugefügtes Theme-CSS überschreiben oder entfernen. Regeln, auf die das Design angewiesen ist, gehören daher in ein per Enqueue eingebundenes Stylesheet.

Kann ein klassisches PHP-Theme theme.json verwenden?

Ja. Ein klassisches Theme kann eine theme.json enthalten, um Einstellungen und Presets des Block-Editors ohne add_theme_support-Aufrufe zu konfigurieren – in der Community wird dies als Hybrid-Theme bezeichnet. Durch das Hinzufügen der Datei wird es jedoch nicht zum Block-Theme, denn WordPress behandelt ein Theme nur dann als Block-Theme, wenn es templates/index.html enthält. Behält das Theme einige add_theme_support-Aufrufe bei, haben entsprechende Einstellungen in theme.json Vorrang.

Wie lese ich theme.json-Werte in PHP aus?

Rufen Sie wp_get_global_settings() für Settings und wp_get_global_styles() für Styles auf. Beide Funktionen akzeptieren ein Pfad-Array, sodass wp_get_global_settings( array( 'color', 'palette', 'theme' ) ) nur die Paletteneinträge des Themes zurückgibt. Ein Kontext-Array mit dem Schlüssel block_name beschränkt die Abfrage auf einen einzelnen Block. Standardmäßig enthält das Ergebnis auch Benutzeranpassungen. Setzen Sie origin im Kontext-Array auf 'base', um ausschließlich Core- und Theme-Werte zu erhalten.