/ sagar_pansuriya
§ WordPress

theme.json for Classic Theme and Sage Developers

Illustration of a theme.json file feeding a colour palette, type scale and matching editor and front-end previews

You've probably inherited a classic theme, or a Sage theme you built yourself, where the front end looks exactly like the design and the block editor looks like a different website. The client picks a colour from a rainbow picker, sets a heading to 43px, adds a drop cap, and the page they preview in the editor bears no relation to the page that goes live.

For years we fixed this with a pile of add_theme_support() calls, an editor stylesheet and some hope. Today the answer is one file: theme.json. It isn't only for block themes. A classic or Sage theme can ship one too, and it's the cleanest way I know to make the editor match the design and stop clients from wandering off-brand.

This post is for developers coming from PHP templates who keep hearing about theme.json but haven't sat down with it. What it controls, how to lock things down, how to feed it from your design tokens, and where block themes fit next to Sage.

What theme.json actually is

theme.json is a configuration file in the root of your theme that WordPress reads on every request. It has two main jobs, and it helps to keep them separate in your head:

  • settings decide what the editor offers: which colours appear in the palette, which font sizes exist, whether custom values are allowed, which design tools are switched on for which blocks.
  • styles decide how things look by default: body text, links, headings, buttons, individual blocks.

From those two sections WordPress generates CSS for you. Every preset becomes a CSS custom property, every colour gets utility classes, and your default styles become a global stylesheet loaded in both the editor and the front end. That last part is the point: one definition, rendered in both places.

Diagram showing theme.json settings and styles producing editor controls, CSS custom properties, preset classes and a global stylesheet used by both editor and front end

Here's a small but complete file. The version key matters: version 2 arrived with WordPress 5.9 and version 3 with 6.6. Use 3 for anything new; the $schema line gives you autocompletion and validation in most editors.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "ink",    "name": "Ink",    "color": "#16161b" },
        { "slug": "paper",  "name": "Paper",  "color": "#faf8f4" },
        { "slug": "brand",  "name": "Brand",  "color": "#5b5bd6" },
        { "slug": "accent", "name": "Accent", "color": "#f2b880" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small",  "name": "Small",  "size": "0.875rem" },
        { "slug": "base",   "name": "Base",   "size": "1rem" },
        { "slug": "large",  "name": "Large",  "size": "1.5rem" },
        { "slug": "huge",   "name": "Huge",   "size": "2.5rem" }
      ]
    },
    "layout": { "contentSize": "720px", "wideSize": "1200px" }
  },
  "styles": {
    "color": { "background": "var:preset|color|paper", "text": "var:preset|color|ink" },
    "elements": {
      "link": { "color": { "text": "var:preset|color|brand" } }
    }
  }
}

The CSS it generates

This is the part that clicks for most classic-theme developers. Each preset turns into a custom property with a predictable name:

PresetCustom propertyClasses
Colour brand--wp--preset--color--brand.has-brand-color, .has-brand-background-color
Font size large--wp--preset--font-size--large.has-large-font-size
Font family body--wp--preset--font-family--body.has-body-font-family
Spacing 40--wp--preset--spacing--40(used by block spacing controls)

Inside theme.json you reference presets with the var:preset|color|brand shorthand, which WordPress expands into the right var(). In your own CSS or Blade templates you can use the custom properties directly, so a hand-built header and a block-built section pull from the same values.

There's also settings.custom, a free-form object for values that aren't presets. Anything you put there becomes --wp--custom--*. Nested keys are joined with double dashes, so { "radius": { "card": "12px" } } becomes --wp--custom--radius--card. Handy for radii, shadows or transition timings you want in both places.

Locking down the editor for clients

This is where theme.json earns its keep on client sites. The default editor gives people a lot of rope. Most of it can be switched off with a handful of settings:

"settings": {
  "color": {
    "custom": false,
    "customGradient": false,
    "defaultPalette": false,
    "defaultGradients": false,
    "defaultDuotone": false
  },
  "typography": {
    "customFontSize": false,
    "dropCap": false
  },
  "spacing": {
    "customSpacingSize": false,
    "units": ["px", "rem", "%"]
  }
}

With that in place the colour picker only shows your brand palette, the font size control only offers your named sizes, and WordPress's own default colours disappear. Editors can still make choices, they just can't make off-brand choices.

You can go further per block. settings.blocks takes the same keys, scoped to one block type. A common pattern is a tight global palette and a slightly different one for buttons:

"settings": {
  "blocks": {
    "core/button": {
      "color": {
        "palette": [
          { "slug": "brand",  "name": "Brand",  "color": "#5b5bd6" },
          { "slug": "accent", "name": "Accent", "color": "#f2b880" }
        ]
      }
    },
    "core/heading": {
      "typography": { "fontSizes": [] }
    }
  }
}

One thing to watch: "appearanceTools": true is a shortcut that turns on a whole group of controls (borders, link colours, spacing, line height and more). It's great for block themes and often too generous for a locked-down client site. I'd rather enable the individual tools I need.

theme.json controls what design tools exist. It doesn't control which blocks exist. For that, keep using the allowed_block_types_all filter, and use block locking or patterns for structure. Together they cover most "please don't let them break the homepage" requests.

Feeding theme.json from your design tokens

If you already have tokens in Tailwind (I wrote about structuring tokens that survive a rebrand), the worst thing you can do is copy hex values into theme.json by hand. Two sources of truth will drift within a month.

Pick one direction and automate it. Recent Sage versions can generate theme.json from your Tailwind configuration as part of the build, so check the Sage docs on roots.io for the version you're on. If you're not on Sage, or you want full control, a tiny build script does the job:

// scripts/theme-json.mjs
import fs from 'node:fs';

const tokens = JSON.parse(fs.readFileSync('tokens.json', 'utf8'));
const theme  = JSON.parse(fs.readFileSync('theme.base.json', 'utf8'));

theme.settings.color.palette = Object.entries(tokens.color).map(([slug, color]) => ({
    slug,
    name: slug.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
    color,
}));

theme.settings.typography.fontSizes = Object.entries(tokens.fontSize).map(([slug, size]) => ({
    slug, name: slug, size,
}));

fs.writeFileSync('theme.json', JSON.stringify(theme, null, 2) + '\n');

Run it before your Vite build and commit the output. Now a token change updates Tailwind utilities, the editor palette and the preset variables in one go.

Going the other way also works: point Tailwind at the WordPress variables, so a class like bg-brand resolves to var(--wp--preset--color--brand). I prefer generating theme.json from tokens, because the tokens file stays readable and framework-neutral, but either is fine as long as there's exactly one place where a colour is typed.

Styling elements and blocks

The styles section replaces a surprising amount of editor-style CSS. It has three levels: root styles, elements (links, headings, buttons, captions) and blocks:

"styles": {
  "typography": { "fontFamily": "var:preset|font-family|body", "lineHeight": "1.6" },
  "elements": {
    "heading": { "typography": { "fontFamily": "var:preset|font-family|display" } },
    "button": {
      "color": { "background": "var:preset|color|brand", "text": "var:preset|color|paper" },
      "border": { "radius": "999px" }
    }
  },
  "blocks": {
    "core/quote": {
      "border": { "left": { "color": "var:preset|color|accent", "width": "4px" } }
    }
  }
}

Because these styles are loaded in the editor too, a quote block looks the same while editing as it does live. No separate editor-style.css to keep in sync.

Block style variations

Block styles are the named options in the sidebar, like "Outline" on a button. You register one in PHP and style it from theme.json:

// functions.php, or a Sage/Acorn service provider
add_action('init', function () {
    register_block_style('core/button', [
        'name'  => 'ghost',
        'label' => __('Ghost', 'sage'),
    ]);
});
"styles": {
  "blocks": {
    "core/button": {
      "variations": {
        "ghost": {
          "color": { "background": "transparent", "text": "var:preset|color|brand" },
          "border": { "color": "var:preset|color|brand", "width": "2px", "style": "solid" }
        }
      }
    }
  }
}

This is my favourite way to give clients choice without giving them control. Three named button styles beat a colour picker every time.

Where block themes fit, and where Sage still wins

A block theme is a theme whose templates are block markup in HTML files (templates/ and parts/), editable in the Site Editor. theme.json is its backbone. A classic or Sage theme uses theme.json only for the editor and global styles, while templates stay in PHP or Blade.

Block themeSage + theme.json
Who edits layoutSite owners, in the Site EditorDevelopers, in Blade
TemplatingBlock markup in HTML filesBlade components, PHP logic
Complex data and logicAwkward, pushed into custom blocksNatural: composers, Acorn, services
Version control of layoutMixed: DB edits can override filesEverything in Git
Best forContent-led sites the client runsProduct-like sites with real logic

My rule of thumb: if the client wants to redesign headers and archive layouts themselves, a block theme is the honest choice. If the site has integrations, custom queries and a component library in Blade, stay on Sage and use theme.json for what it's great at: making the content editor match the design and keeping it on-brand.

A checklist for adding theme.json to a classic theme

  1. Add theme.json with "version": 3 and the $schema line.
  2. Define palette, font sizes, font families and spacing as presets, generated from your tokens.
  3. Turn off custom colours, custom font sizes and the default WordPress palette.
  4. Enable design tools one by one instead of reaching for appearanceTools.
  5. Move editor-style CSS into styles: root, elements, then blocks.
  6. Offer choice through block style variations, not colour pickers.
  7. Remove old add_theme_support() calls for palettes and font sizes that theme.json now covers, so there's only one definition.
  8. Use --wp--preset--* variables in your own templates so hand-built and block-built parts match.

None of this requires moving to a block theme. It's one JSON file, and it turns the editor from the place where designs go to die into a reasonably faithful preview of the real site.

Discussion