The first three things to add to theme.json

If you’re developing a WordPress block theme, here’s three things to add to your theme.json.

Here’s a starter theme.json file for a WordPress theme I’m working on, which will hopefully combine some of the best features of the Twenty Twenty theme (one of my favorites) and the newer Twenty Twentytwo theme.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json”,
  "version": 2,
  "settings": {
    "layout": {
      "contentSize": "720px”,
      "wideSize": “1200px"
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif”,
          "slug": "system-font”,
          "name": "System Font”
        }
      ]
    }
  },
  "styles": {
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--system-font)”
    }
  }
}

Here’s what’s in this starter file that you might want to add.

JSON schema

"$schema": "https://schemas.wp.org/trunk/theme.json”

Adding this line will save you a ton of headaches and time wasted fishing through the WordPress documentation for how to structure your file. By adding a JSON schema, it gives your code editor like Visual Studio Code a better sense of how to structure your JSON file. You’ll notice this as you’re writing as see the autocomplete display valid properties that you can set, which is a lot easier than memorizing the WordPress documentation.

Content width

"settings": {
  "layout": {
    "contentSize": "720px”,
    "wideSize": “1200px"
  }

Setting the content width will help make content display better as you’re configuring templates. In the example above, I put in a normal content size and wide size in pixels, but you can use other units of measurement.

The contentSize width is used for any block where the custom size is set to None, while wideSize is used if you select Wide width. Selecting Full width implies 100%.

Change the default Times Roman font

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif”,
          "slug": "system-font”,
          "name": "System Font”
        }
      ]
    }
  },
  "styles": {
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--system-font)”
    }
  }
}

There’s something about seeing Times Roman on a web page that makes it look broken immediately. So for this starter theme.json file, I’m setting the default font to use system fonts for most operating systems.

First, a CSS variable called system-font is defined under settings > typography > fontFamilies. When you define a CSS variable in your theme.json file, the variable will be prefixed depending on the setting, starting with “–wp–preset–“.

Then the font family for the body element is defined under styles > typography > fontFamily. Although you don’t see anything that suggests style is targeting the body element, it is. When I was getting started with block theme development, it took nearly an hour to figure out how to get the fonts to appear correctly (back before the JSON schema and better documentation).