theme.json explained for WordPress theme builders

The theme.json file declares a theme's editor settings and default styles. It can define a color palette, font sizes, layout widths and block defaults. You do not need to edit it to use the Site Editor.

Separate settings from styles

Settings control available design options and presets. Styles specify default appearance. Declaring a blue palette entry makes that color selectable; it does not automatically make every heading blue.

Block-level configuration can narrow or change the global defaults. User choices saved in the editor can override theme defaults. When a file edit does not appear, inspect those saved choices before assuming the JSON failed to load.

Classic themes can use theme.json too. Its presence alone does not establish that a theme supports the full Site Editor.

Use the correct schema

The current theme.json format is version 3, supported from WordPress 6.6. The schema version is separate from the WordPress version. WordPress 7.1 does not imply a theme.json version of 7.

Use a schema for the WordPress version you target. The living reference and trunk schema can include Gutenberg-plugin features that are not available in the corresponding stable core release.

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "ink", "name": "Ink", "color": "#192321" },
        { "slug": "paper", "name": "Paper", "color": "#ffffff" }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "text": "var:preset|color|ink",
      "background": "var:preset|color|paper"
    }
  }
}

This small example declares two colors, two layout widths and default text/background colors. It does not supply templates, install fonts or create a complete theme. The preset syntax refers to the palette slugs declared above.

Make a controlled file change

Work in a staging theme or child theme and keep the original file. Use a JSON-aware editor with schema validation. A trailing comma or broken brace makes the document invalid JSON before WordPress can interpret the settings.

Change one area, then inspect the editor and the public view. Test a normal-width group and a wide group, a heading, a paragraph and a button. Confirm that existing local block choices behave as intended.

Keep palette slugs stable when existing content uses them. Renaming a slug can leave stored blocks referring to a preset that no longer exists.

Avoid confusing overrides

Theme styles, child-theme changes, saved global Styles and local block settings can all contribute to a result. Check the narrowest override first: the block, then global user styles, then theme files.

Do not reset the whole site's Styles just to verify a file change on production. Test on staging and preserve the user's saved customizations. The child-theme guide explains why database overrides and file inheritance are separate layers.