Open Survey for WordPress Theme Authors on JSON Files and Block Themes

WordPress 5.8 introduced an opt-in system for themes to configure block settings, styles, templates, and more. It is done through a new theme.json file that authors can put at the root of their theme folders. Anne McCarthy, the lead of the FSE Outreach Program, announced a survey earlier today to get feedback from developers on this feature.

“Since this new mechanism is an early step towards a comprehensive style system for the future of WordPress, it’s important to hear from everyone who is currently using theme.json to learn more about how folks are using this tool and what might make sense to include in Core going forward,” she wrote in the announcement.

The survey is open to all theme authors who have used theme.json, giving them a chance to put in some early feedback and help steer the ship going forward.

Because I have worked extensively with this system over the past few months, I had a few things to say. Plus, I just like participating in WordPress-related surveys. I also decided it would be an opportunity to share some of my unfiltered thoughts from a development perspective on the current state of theme.json.

What follows are my responses to the survey’s questions — well, the tidied-up version.

Note: This is a developer-centric post that might not universally appeal to all of our readers. I have attempted to explain some things in user-friendly terminology, but some prerequisite knowledge of theme development may be necessary.


The first question of the survey is pretty cut-and-dry. It asks what your experience is with building block themes or using theme.json. It provides four choices (and an “other” option):

  • I have built and launched block themes.
  • I have experimented with building block themes.
  • I have explored using theme.json with a classic theme.
  • I have used a block theme, but I have not built one yet.

I chose the first option because I have already built two block themes for family and friends. These were simple personal sites that I already maintain for free — honestly, I need to start charging. I am also working on a theme that I hope to release publicly.

How It Started and How It’s Going

The second question asks how one got started with block themes and theme.json. The choices are between forking an existing theme, using the Empty Theme, or starting from scratch.

Again, this is one of those things where I have experimented with each direction, but I cannot remember the exact starting point. The bulk of my work has come from forking a theme that I last worked on in 2019.

I plan to release this as a new theme for free at some point. I am mostly waiting on the following:

  • Navigation block development to settle down
  • The Post Author block to be split into smaller blocks
  • A robust set of comment-related blocks
  • Post Featured Image block to have a size option

I think I could realistically release a use-at-your-own-risk beta version of my theme today if those items were addressed.

Templates and Template Parts

The survey asked which templates and template parts themers always include in their block-based themes. There was a freeform comment field — steps upon soapbox…

I have a love/hate relationship with block templates at the moment. The static nature of HTML templates reminds me of simpler times when theme development was less complicated. However, this also presents a problem in a dynamic system.

I cannot remember the last time I have built a traditional, PHP-based theme with more than one top-level template: index.php. The dynamic pieces have always been the guts of the thing, which are template parts. With PHP, it is easy to set some variable or use a function call to contextually load the templates parts necessary for whichever page a visitor is currently viewing on a site.

The block template system does not work like that. It essentially forces developers into breaking the Don’t Repeat Yourself (DRY) principle.

For example, if a designer wanted to display a different header template part for pages and posts, they would only need to create a header-page.php or header-post.php template in traditional themes. However, because the block template system is different, they must now create two top-level templates, single.html (post) and page.html, to accomplish the same thing.

This is a “bad thing” because theme authors must duplicate all the other code in each of the top-level templates. There is no way to contextually load different template parts.

To answer the question: I am using almost all of the possible top-level templates out of necessity.

I also answered the second part of the question and listed my most commonly used template parts (broken down by hierarchy):

  • Header
  • Content
    – Loop
    – Sidebar
  • Footer

The content-*.html and loop-*.html template parts are those with the most variations.

Defining Colors

The next section of the survey asks how theme authors define their color palette slugs in theme.json. Believe it or not, naming colors may be the most controversial topic in the theming world in years. The only two things generally agreed upon are “background” and “foreground” colors.

Morten Rand-Hendriksen opened a ticket in 2018 for standardizing a theme color naming scheme. It was not the first discussion and has not been the last. The problem it was meant to address was the slugs for colors in the system, which is how themes define their palettes. Once a user makes use of a preset color, the slug is hardcoded into their content. Switch to another theme with different slugs, and the old colors disappear and do not automatically change to the new theme’s colors.

I use semantic names that follow something that closely resembles the Tailwind CSS framework’s shading system. Instead of red-medium (descriptive), I would use primary-500 (semantic), for example. A semantic approach would allow theme authors to define a set of colors that are updated each time a user switches themes.

Of course, there are other schools of thought, and even everyone who prefers semantic naming does not agree on the same system. I have described my approach in more detail in a more recent GitHub ticket and have a theme.json Gist for others who might want to try it.

Other Theme JSON Settings

Outside of colors and typography, the survey asks what other settings theme authors have used. This is another scenario where I typically use everything — if there is an option for it, I am defining it.

One use case that WordPress does not currently have a preset for is global spacing. Most theme authors use a single value for most vertical margins (whitespace between blocks and elements). It is also often used for default vertical and horizontal padding.

I am unsure if I want a preset because I do not know how WordPress will use it. It is something that others have asked for, and it is nearly ubiquitous in use. Defining an entire system around it could cause headaches down the road, but I would still like to see some discussion around implementing at least a standard global spacing preset.

Per-Block Settings and Styles

This survey section was a yes/no question, simply asking if theme authors included per-block settings or styles in their theme.json files. Of course, I left some additional comments later in the optional comment section.

I am happy with the system when it comes to settings, which allows themers to define which features are enabled globally or on a per-block basis. However, I am not sold on adding styles via theme.json.

Writing CSS in JSON, essentially what we are talking about, feels wrong on so many levels. Currently, it is limited to merely a few configurable styles, so anything beyond that requires diving into an actual CSS file anyway. That is problematic because half of the theme’s CSS code is divided between theme.json and a separate CSS file. From a development standpoint, it makes the codebase harder to maintain.

Initially, I started down the path of configuring per-block and element styles from theme.json. However, I have since moved my styling back to CSS files. It feels more natural, and I have the added benefit of all the tooling I am accustomed to. Right now, I cannot imagine a scenario where I would move back.

Besides saving a few bytes of code, I have not seen many benefits to adding styles for most things via JSON. Maybe that will change in the future, and I will be a convert. For now, I am sticking primarily with CSS.

Other Feedback: A PHP Layer

I have said it before, but it bears repeating. We need a PHP layer for this theme.json configuration system. There is currently an open ticket for addressing this.

There are two main benefits to such a system. Having a PHP API for piecing together configuration will feel far more natural to traditional theme developers. I look at it as a bit of an olive branch, a show of good faith that the core/Gutenberg developers recognize that many theme authors will have an easier time easing into FSE features via a familiar programming language.

The second advantage is that there is an untold number of plugin ideas to extend global styles, site editing, and more if there is an easy way to hook into the theme JSON system and overwrite things. A simple filter hook would make this painless.


8 responses to “Open Survey for WordPress Theme Authors on JSON Files and Block Themes”

    • On the front end, it should be relatively easy with a filter on the block itself. In the editor, I’m not sure. I don’t know how you’d get whatever context you need (current post, current query, etc.). That’s where I’ve hit problems.

  1. As someone who is trying to find my footing, your posts have been super valuable lately.

  2. This doesn’t really fit in with the survey but I found that manually editing JSON files for complex themes soon become unwieldy. Even with my closures indicated by my editor I soon get lost in the nested elements.

    Rather than a manual JSON edit it’s easier of course to create the layout in the (new) WP theme editor and export the JSON from there, that process is actually very simple. Thankfully.

    But it demonstrates my point:
    I think theming in JSON was chosen for it’s simplicity and legibility – which seems true at first but once we start building complex themes it becomes labyrinthine and really relies on our tooling to create coherent valid outcomes. So with that reliance on tooling the output format becomes a black box, and could have been any file really! It could have been SQL!

    I’m not sure I have an actual point, just that observation: JSON loses legibility after a certain depth of complexity and loses the supposed benefits of direct text editing, it starts to rely on the WYSIWYG JSON theme editor. Which may be fine. It depends on use cases.

    • I’m right there with you. That’s one of the reasons I think it’d be nice to have a method for doing this via PHP, which would allow theme devs to organize and manage this in a way that makes sense to them.

      Currently, I am splitting my theme.json into multiple JSON files and merging them with this webpack script, but that method makes the barrier to entry for new devs much higher. At least it keeps me sane for the moment though.

      • Hi Justin.
        There were some older GitHub tickets discussing the need for script in templates. I’m not really sure why we found ourselves without script in template files when the need seems obvious, and limitations seem arbitrarily puritanical.

        Way back in Nov 2020 before FSE was finalised there was some discussion around the partials format and the necessity to include logic which implied PHP ought to be the format of choice. Yet today we have only flat html template files, and even inline scripting conditionals don’t seem to work (last I checked).

        I had to stop developing FSE themes about 6 weeks ago because required conditionals. It was overkill to build the conditional into an extended core block pattern where it could have been achieved with 20 characters in header.html

        I have a strong feeling that there’s a fashionable distaste for PHP, and there are some “babies being thrown out with the bathwater”.

        Here’s the old discussion about flat html Vs PHP templates.

        I’m not sure who took the ultimate decision to kill scripting in templates, and why that is the preferred limitation. I’m not sure if scripting is coming, or if this is closed.

        • Another article on the subject of “PHP or HTML template files in FSE”

          During the core editor and customize meeting on May 28th 2020, it was clarified that templates and template parts will likely be PHP files instead of HTML files.The background to this is the need for dynamic urls and the ability to translate text strings.

          I’m not sure when this decision was reversed, or who made that decision and why.

  3. Justin! As always, thank you for participating in the survey and encouraging others to do the same. I imagine you sharing this article is part of why there are 25+ responses already :) Speaking personally, it’s immensely helpful to read someone’s long form thoughts to the survey questions as it’s easy to only get condensed answers in return. Stay tuned for the full write up.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: