As designers and developers, especially when creating bespoke websites, we want to finely control and curate the capabilities and styles available to content creators working with the websites we make. After all, what’s the point of putting in all this hard work in creating a branded and accessible website if people can change the intentional features that create the vibe and functionality that make the website so great?
With the advent of the block editor and the introduction of blocks as the tools of building a website, we now needed to curate and control a lot more user-facing features than we ever did before, because of what the block editor offers. There’s that pesky drop cap feature, the typography settings, the spacing controls, the colour palette, etc.
For example, in one of my recent projects, my designer intended for the colour palette to be available in only certain blocks, and there were other blocks that should only have a subset of the palette available to them. But there was no straight forward way to make this happen. Once you create a custom palette, it becomes available to any block that has the colour palette feature.
Incorporating theme.json in your process
That’s where the theme.json file comes in
theme.json is a configuration file that allows WordPress themes to set existing editor and block-level settings. This is intended to not only take over and consolidate the various add_theme_support() calls we needed to control parts of the editor before, it also now gives us really easy access to granular settings that we never had straightforward access to before.
This is really cool and I see a lot of potential as the API develops further and more and more people adopt it as a way to set values and other settings.
Before we get into the technical details of how to use theme.json, I think it’s important to talk about the role it plays in your theme development process. Ideally, before you write any CSS at all, you should be setting up your theme.json, and whenever you’re configuring new formatting rules, your first question should be, “Does this – or part of this – implementation belong in theme.json?”
The idea is you set up your variables, aka your CSS Custom Properties in theme.json. Then use those variables in your actual CSS.
Why? Let’s say the background colour of the website is a light grey, however, a small design refresh tweaks this colour to be a bit more beige. Normally, you’d pop open your SCSS file, change the colour in the variable, re-compile your CSS and update the live website. However, if you had set up the background colour as a Custom Property in your theme.json file, and were using that variable in your CSS. All you would do is open up your theme.json file, switch the hexcode and update the live website. No opening up your SCSS, no re-compiling. A tiny hex code change and a quick commit to production.
This, by the way, also allows the Global Styles editor within the WordPress dashboard to do the same thing, but that’s outside of the scope of this particular video.
So the purpose – as I see it – of theme.json is to create a flexible ruleset file that cascades down into the rest of your styles. You’re already doing this when you write styles of any kind, but by putting this all in a JSON file, we’ve taken the rules often scattered between PHP, CSS, and sometimes even JS, and put them in one file, creating a single source of truth that can communicate with the WordPress Dashboard, your PHP, JS, and CSS. Seriously, it’s fantastic.
In order to start using theme.json, you just need to create a theme.json file in the root of your theme. Within curly brackets, you add your first key/value pair: version: 1 . Right now, there’s only one version of the theme.json API, but as it evolves, this will be a way to ensure your file doesn’t break with new iterations. Then the rest of your rules will belong to one of 3 sections: settings, styles, or templateParts.
Note: all the keys, that is, the property names, are written in camelCase.
The settings section is a top-level declaration area, things set here apply to the body. The styles section allows you to set specific styles for particular blocks or elements (like links or headings). the templateParts section lets you list the template parts present in the block-template-parts folder in your theme. It helps you persist settings of that template part across all its instances.
In the video above, I go through a simple tutorial, demonstrating how to. add theme.json to your theme, and how you can add a custom colour palette with it.
Some tips and thoughts on systems and streamlining.
I mentioned this before, but asking yourself whether the change you want to make belongs in theme.json before you make a change is going to be really helpful. It also helps you reevaluate how you want to create the desired change and if it’s at all possible with the properties and foundations you have already established within theme.json .
I want to bring attention to a few articles by Rich Tabor – a 3 part series on standardization of certain properties in block themes. I encourage everyone to read it, developers and designers both, and think about how you can apply it in your work.
Specifically, he talks about colour slugs, font sizings, and spacing. The concept has a lot of merit, even for those of us building bespoke websites, knowing that our clients are not going to randomly switch themes one day on a whim.
For example, he talks about how themes shouldn’t use colour values as the slugs (or variable) in their palette. Just because your theme has the colour green, doesn’t mean it should be called green. This is a philosophy I have followed for a long time, and I wholeheartedly agree.
Right now, my colour palette has the following standard slugs and variable names: primary, secondary, highlighter, dark, and light. I believe in labels that tell you the purpose of the colour, not what the colour is.
Rich proposes a different set of slugs: background, foreground, and them iterative labels for all other colours starting with primary, so secondary, tertiary, and so on. I do think primary, secondary, tertiary, etc, after a certain number of them, lose their value – the label no longer tells you much about how the colour is used, just how important it is or maybe when it was added. But as far as basic standardization goes, it makes a lot of sense and I’m down to apply it in my own work.
This is a fairly brief introduction to theme.json. I’m hoping to make a few more videos diving deeper into what you can do with theme.json with concrete examples, and such. Let me know on Twitter if you have any questions and if there’s something else you’d like to know more about.
Did you like this article? Get articles like this straight in your inbox for easy reading. 🙂