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.
Experience
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.jsonwith 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.
