FSE outreach experiment – Call #8 – Thrive with theme.json

For the (Very) Advanced testing steps of the “Thrive with theme.json” call, I developed a new theme called Written, wrote my comments in issues raised as I developed the theme, and documented other questions in bobbingwide/bobbingwide#31.

In this post I’ll try to summarise my conclusions.

TL;DR – you need both theme.json and style.css

theme.json versus style.css

It’s coming with techno
designed to get smiles
No CSS needed
when you've got Global Styles.

Contrary to what I wrote in “My Favourite Theme”, it’s still necessary for a theme to deliver stylesheets.


The primary purpose of theme.json is to define some settings and default styles for the theme.

The settings indicate what functionality is allowed globally and any variations for individual blocks and their elements.

settings replace many of the capabilities defined using add_theme_support().

The more true‘s you have in the settings the more freedom you give to the user.

Settings defined for the theme trump the settings defined for a block in its block.json file.

styles define the default values for the supported settings.

styles also apply globally and to individual blocks.


style.css is needed for theme specific styling that isn’t supported by theme.json.

For example, at this moment in time, it’s necessary to use a stylesheet to define block styles, where the className attribute is of the form is-style-customstylename.

I chose to use style.css; it was slightly easier than registering my own stylesheets.

Note: If you don’t use register_block_style() it’s still possible to cause a block to take on a particular style by using the Additional CSS class(es).

What I still don’t understand


I often don’t know what the Default values are.

You have to change the setting in an attempt to work out what the default was by analysing any visual change in the blocks.

The problem’s harder when the default values for padding or margin vary by side.

Customization options

Which blocks support which customization options?

Link colour

For example, the Paragraph block supports Link colour but the List block doesn’t.

Font weight

The Heading block supports Font weight but the Paragraph block does not.

How do you find out?

Global styles – blocks

In Global Styles why isn’t there a section for every block?

Some blocks which are not listed are: Audio, Categories.

I assume this is because these blocks don’t use block.json and or don’t have a supports section.

"supports": {
    "html": false,
    "color": {
      "gradients": true,
      "text": false,
      "background": true,
      "link": false
    "typography": {
      "fontSize": true,
      "lineHeight": true

Actually, I think I do understand it. I’ve developed a couple of blocks that implement the supports mechanism and have seen how theme.json settings affect how the block appears to the end user.

It’s complicated.

What did I achieve in theme.json?

My theme.json file is approximately 250 lines of code.

  • Most of it appears to work.
  • You can’t write comments in a JSON file; I should have written better commit messages.
  • I did manage to
    • set the default fontSize for several blocks
    • define a default background colour and padding for the Group block
    • define a default margin for the Heading block
    • style the border for the separator block.

style.css, which I mostly used for some block styles, is 150 lines.

Note: I also have a custom.css file, copied from the original theme, that provides styling for content already present on the website. I haven’t yet determined how much of this CSS is needed.

What I couldn’t do using theme.json

I was unable to use theme.json to

  • Style menus
  • Style query navigation
  • Enable customFontWeight by individual block
  • Define my own font weights
  • Create a restricted colour palette for the Heading block.
  • Enable customFontSize for the Site Title block if the default customFontSize was false.

What I couldn’t do in the editor

  • Set negative margins for blocks that support customMargin.

What I needed to do in style.css

What I got wrong

  • I think some of my CSS styling needs to be more precise.


© Copyright Herb Miller, Bobbing Wide 2021