I started paying closer attention to theme.json because it solved a problem I had run into on several WordPress builds. The problem was not that the design was difficult to create. The problem was keeping design decisions consistent once the site was being edited, maintained and changed by more than one person. Colours would be defined in Sass, repeated inside editor styles, added again inside theme support settings and occasionally reintroduced inside a custom block. It worked, but it never felt as clean as it should have.
With the block editor becoming more central to WordPress, that separation started to feel more awkward. The front end had one view of the design system and the editor had another. If those two drifted apart, editors would make decisions in WordPress that looked fine in the editor but behaved differently on the front end. That kind of mismatch is frustrating because it reduces confidence in the editing experience.
Why I Wanted One Place For Design Settings
The thinking behind theme.json was appealing because it gave the theme a more direct way to describe its design decisions. Colours, font sizes, layout widths and spacing rules could be defined in a structured file rather than scattered across several places. I liked that because it made the theme easier to reason about. If I needed to know which colours were available to the editor, I had one obvious place to look.
This also changed how I thought about client editing. I do not want every editor to have unlimited choice, because unlimited choice usually turns into inconsistent pages after a few months. A controlled palette is much more useful. The client can make the changes they need, but they are choosing from the same decisions that already belong to the brand and the build.
A simple colour setup might look like this:
{
"version": 2,
"settings": {
"color": {
"palette": [
{
"slug": "brand-dark",
"color": "#111827",
"name": "Brand Dark"
},
{
"slug": "brand-light",
"color": "#f9fafb",
"name": "Brand Light"
}
]
}
}
}The useful part is not the JSON itself. The useful part is the decision it represents. The theme is saying these are the colours that should be available, and the editor can now work inside those boundaries.
Making The Editor Feel Closer To The Website
One of the long-running problems with WordPress theming is that the editor and the front end can feel disconnected. A client edits a page in one environment, then previews it in another. If spacing, typography or block widths are different between those two places, the editor becomes less trustworthy. People start previewing every small change because they no longer believe the editor reflects the real page.
theme.json helps because it allows the theme to share more of its decisions with the editor. That does not remove the need for front-end CSS, and I would not pretend it replaces proper theme styling. It does, however, give WordPress a clearer understanding of the design rules that the theme expects.
The more I used it, the more I saw it as a bridge between development and content editing. The developer still makes the important structural decisions, but the editor has a clearer set of tools that match the website. That matters because internal CMS friction usually appears in small ways. A wrong font size here, an unexpected spacing option there, then a page slowly starts to drift from the original design.
Spacing And Layout Decisions
Spacing was another area where theme.json started to make sense. In older builds, spacing utilities could easily become a mixture of CSS classes, block settings and manual overrides. That gives people options, but not always useful ones. I would rather provide spacing choices that reflect the way the site is actually designed.
For example, a site might only need a few sensible spacing values. Small gaps for related items, larger gaps between sections and a few layout widths for content. Those decisions can be exposed in a way that makes sense to the editor, rather than asking people to invent spacing from scratch every time they add a section.
This is where I think theme.json becomes more operational than technical. It reduces the number of small decisions that need to be made repeatedly. The website has a rhythm, the theme describes that rhythm and the editor works inside it.
Retrospective Thoughts
I do not think theme.json makes WordPress theming simple overnight. There is still a lot to learn, and the relationship between block themes, classic themes, editor styles and custom blocks can still be awkward. At the same time, I think it points in a healthier direction. Design settings should not be duplicated across a theme in several disconnected ways.
For me, the main value is clarity. If a build has a defined colour palette, typography scale and spacing system, those decisions should be visible in the place WordPress now expects to find them. That makes the site easier to maintain, but it also makes the editor safer to use. The client gets enough freedom to manage content, while the theme still protects the decisions that hold the design together.