theme.json in WordPress uitgelegd: settings, styles en de cascade

theme.json is één configuratiebestand in de hoofdmap van een block theme met twee gescheiden taken: settings bepaalt wat de blokeditor aan gebruikers aanbiedt, en styles bepaalt hoe de site er standaard uitziet. WordPress leest het bestand, voegt het samen met zijn eigen standaarden en met alles wat in de site-editor is opgeslagen, en zet het resultaat op elke pagina neer als CSS-variabelen plus een inline stylesheet.

Die twee taken door elkaar halen is de reden dat de meeste aanpassingen in theme.json schijnbaar niets doen. Een kleur onder settings declareren past die kleur nergens toe. Het maakt alleen een variabele en een swatch in de zijbalk van de editor.

De sleutels op het hoogste niveau

Een minimaal bestand ziet er zo uit:

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

Sleutel	Wat het doet
$schema	Alleen autocomplete en validatie in je code-editor. WordPress negeert het.
version	Vertelt WordPress welke schemavorm het moet inlezen. Niet je themaversie.
settings	Genereert CSS-variabelen en bepaalt wat de editor toont.
styles	Past de daadwerkelijke standaardopmaak toe.
templateParts	Declareert onderdelen in parts/ en bij welk gebied ze horen.
customTemplates	Registreert paginasjablonen in templates/ voor de berichteditor.

version zorgt voor verwarring omdat het op een themaversienummer lijkt. Dat is het niet. Het kiest een leesmodus, en oudere WordPress-releases negeren stilzwijgend sleutels uit een schemavorm die ze niet kennen. Ondersteun je oudere installaties, richt je dan op de versie die die installaties begrijpen in plaats van te hopen dat nieuwere sleutels netjes terugvallen. Versie 3 is op dit moment actueel; versie 2 draait nog volop en wordt nog steeds ingelezen.

$schema wijst naar een schema-URL die door WordPress wordt gehost. Zet je die op trunk, dan krijg je de nieuwste hints in je code-editor; een versiespecifieke URL is veiliger als je bewust op een ouder schema blijft.

settings: wat de editor aanbiedt

Alles onder settings levert een CSS-variabele op en meestal ook een bedieningselement in de editor. Niets onder settings maakt zelf opmaak.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Dat levert variabelen op die vernoemd zijn naar het presetpad en de slug:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

Het levert daarnaast hulpklassen op zoals .has-brand-color en .has-brand-background-color; zo past de editor een gekozen swatch toe op een blok.

De regel "custom": false is de andere helft van settings: opties uitzetten. Zet hem en de vrije kleurkiezer verdwijnt, zodat gebruikers alleen jouw palet overhouden. Datzelfde patroon werkt overal — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border, enzovoort. Niets onder settings is decoratief; elke sleutel voegt een variabele toe, voegt een bedieningselement toe, of haalt er een weg.

settings.custom is een vrij in te vullen bak voor je eigen variabelen:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

Die worden --wp--custom--line-height--body en --wp--custom--shadow--card. Let op de omzetting: camelCase-sleutels worden opgesplitst naar kebab-case, en nesting wordt aan elkaar geplakt met dubbele streepjes. Een verkeerd geschreven variabelenaam is een veelvoorkomende reden dat een waarde stilletjes terugvalt.

Je kunt settings per blok afbakenen; zo sta je wel een kleurkiezer toe op knoppen, maar niet op alinea’s:

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: wat er echt wordt weergegeven

In styles worden waarden daadwerkelijk toegepast. De structuur volgt die van de editor: eerst een rootniveau, dan elements, dan blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

Wat op rootniveau in styles staat, landt op de body. elements dekt HTML-basiselementen die geen blok zijn: link, knop, koppen, bijschrift. blocks richt zich op een specifiek bloktype op naam.

De eerlijke beperking: styles kan niet alles uitdrukken wat CSS kan. Je kunt geen eigen media queries schrijven, geen complexe selectors gebruiken, geen animaties maken, en er wordt maar een kleine set pseudo-class-states ondersteund. Fluid typography en layoutgebaseerde maatvoering vangen veel op waar mensen vroeger breakpoints voor gebruikten, maar niet alles. De meeste block themes die daadwerkelijk live gaan hebben theme.json plus een bescheiden stylesheet, en dat is een normale uitkomst, geen falen.

De valkuil van settings versus styles

De meest gestelde supportvraag is een variant op “ik heb mijn merkkleur toegevoegd en er verandert niets”.

Klopt. Door hem aan settings.color.palette toe te voegen maakte je --wp--preset--color--brand en een swatch. Toegepast werd er niets. Wil je hem als standaard linkkleur, dan moet je hem ook onder styles zetten:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Lees het zo: settings is de verfdoos die je de gebruiker aanreikt, styles is de laag die je zelf alvast aanbrengt voordat hij binnenkomt.

De cascade, van laag naar hoog

Dit is het stuk dat verklaart waarom een site het themabestand lijkt te “negeren”. WordPress voegt meerdere lagen samen voordat het CSS uitstuurt:

1. Standaarden van de WordPress-kern — de kern levert een eigen theme.json met een basispalet, lettergroottes en een spacing-schaal.
2. theme.json van het parent theme
3. theme.json van het child theme — sleutel voor sleutel over de parent heen gelegd, niet het hele bestand vervangend.
4. Global Styles in de database — wat het paneel Stijlen in de site-editor wegschrijft.
5. Stijlen op afzonderlijke blokken — attributen die in de berichtinhoud staan en als inline stijlen of klassen worden weergegeven.

Laag 4 is degene die sites sloopt. Zodra iemand het paneel Stijlen opent en opslaat, bewaart WordPress een Global Styles-record, en dat record wint van jouw bestand voor elke eigenschap die erin staat. Daarna verandert theme.json aanpassen niets zichtbaars voor die eigenschappen: de site ziet er na een deploy identiek uit terwijl het bestand op schijf overduidelijk anders is.

De oplossing is dat opgeslagen record wissen, niet escaleren met !important. Open de site-editor, ga naar Stijlen, open het revisiepaneel en zet terug naar de standaardwaarden van het thema. Overleg dat eerst met de klant of de eigenaar van de site — met resetten gooi je hun aanpassingen weg, en dat kost echt iets.

De tweede verdachte is caching. WordPress bewaart de ingelezen theme.json-data in de cache in plaats van het bestand bij elk verzoek opnieuw te lezen, wat je in productie precies wilt en tijdens het ontwikkelen precies niet. Zet je WP_DEBUG aan, of op nieuwere releases de instelling voor themaontwikkeling, dan leest WordPress het bestand elke keer opnieuw. Zie je je aanpassingen pas na een deploy of een cache-flush, dan is dit wat er speelt.

templateParts en customTemplates

Beide zijn arrays die bestanden beschrijven die al in je thema staan.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

name komt overeen met de bestandsnaam zonder extensie — parts/header.html, templates/page-wide.html. De waarde van area doet ertoe: die bepaalt of het onderdeel in een header- of footer-landmark wordt gezet en hoe de editor het indeelt. Laat je hem weg, dan geldt het onderdeel als niet-ingedeeld.

customTemplates zorgt ervoor dat een sjabloon in de sjabloonkeuzelijst van de berichteditor verschijnt. Zonder die vermelding bestaat het bestand wel, maar kan niemand het kiezen.

Een snelle diagnosevolgorde

Werkt een block theme niet zoals het bestand zegt, loop dit dan eerst af voordat je iets aanpast:

1. Bekijk de broncode en zoek naar het gegenereerde global styles-blok. Staat jouw variabele er niet in, dan zit het probleem in settings of in een typefout in een slug.
2. Bestaat de variabele wel maar wordt hij nergens gebruikt, dan ontbreekt er een vermelding onder styles.
3. Bestaan ze allebei en wordt er toch overheen geschreven, controleer dan of er een opgeslagen Global Styles-record is.
4. Kijk pas daarna naar je eigen stylesheet, naar plugins, of naar een paginabouwer die later in de cascade CSS injecteert.