Theme.json is a configuration file used in WordPress themes to define global design settings and styles using a structured JSON format. Introduced in WordPress 5.8, it serves as the central control point for a theme’s design system — managing color palettes, typography, spacing, layout widths, and which block customization options are exposed to editors.
For block-based themes (used with Full Site Editing), theme.json is essential. For classic themes, it’s increasingly useful as WordPress moves toward a unified design token system. The file allows developers to define a consistent visual language for the entire site in one place, while also controlling what editors can and cannot change in the block editor. Business owners benefit from a site that looks coherent and is harder to accidentally break through editor customization.
How Theme.json Works
theme.json lives in the root directory of a WordPress theme. It uses a hierarchical structure with two primary sections:
settings— Controls which options are available to editors in the block editor interface. You can expose a curated color palette, restrict font choices, enable or disable spacing controls, and define layout dimensions.styles— Defines default visual styles applied globally (to the entire site) or to specific block types. These styles are output as CSS custom properties on the front end.
When WordPress loads a page, it reads theme.json and generates a corresponding stylesheet of CSS custom properties. These variables are then used by blocks and the block editor to apply consistent styles. The system operates in a cascade — WordPress core defines defaults, the theme’s theme.json overrides them, and user customizations in the Site Editor (stored as user-level theme.json data) override the theme’s settings.
This cascade means a developer can define a precise color palette in theme.json, and the editor will only show those colors — preventing editors from choosing colors outside the brand palette.
Purpose & Benefits
1. Centralized Design System Control
Rather than writing scattered CSS across multiple stylesheets, theme.json provides a single source of truth for a theme’s design tokens — colors, font sizes, spacing values, and layout widths. Changes to the global color palette or typography scale happen in one file and propagate throughout the theme and editor automatically. This is especially powerful for maintaining brand consistency across a site with multiple editors. It connects directly to how we build custom WordPress designs.
2. Control Over Editor Customization Options
By default, the block editor exposes many customization controls that can lead to inconsistent design decisions — editors can pick any color, any font size, any spacing value. theme.json lets developers curate exactly which options are available. You can expose only the brand-approved colors, limit font sizes to the defined type scale, and hide controls that shouldn’t be touched. This creates a more guided editing experience and a more consistently branded result.
3. CSS Custom Properties for Front-End Consistency
Values defined in theme.json are output as CSS custom properties (variables) on the front end. This means the same values used in the block editor are the ones applied in production — no discrepancy between how something looks in the editor and how it looks live. Spacing, colors, and typography all derive from the same source, reducing CSS maintenance complexity.
Examples
1. Defining a Brand Color Palette
The most common use of theme.json is defining the theme’s color palette so editors can only choose from brand-approved colors:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"color": {
"palette": [
{
"name": "Brand Blue",
"slug": "brand-blue",
"color": "#1E40AF"
},
{
"name": "Accent Orange",
"slug": "accent-orange",
"color": "#EA580C"
},
{
"name": "Neutral Gray",
"slug": "neutral-gray",
"color": "#6B7280"
}
]
}
}
}
With this palette defined, the block editor’s color picker shows only these three colors — preventing editors from using off-brand colors.
2. Setting Global Typography and Layout
theme.json can define the site’s content width, font families, and type scale:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"layout": {
"contentSize": "780px",
"wideSize": "1200px"
},
"typography": {
"fontSizes": [
{ "name": "Small", "slug": "small", "size": "0.875rem" },
{ "name": "Base", "slug": "base", "size": "1rem" },
{ "name": "Large", "slug": "large", "size": "1.25rem" },
{ "name": "X-Large","slug": "x-large","size": "1.5rem" }
]
}
}
}
These values control the content column widths in the editor and expose a curated type scale instead of the default WordPress sizes.
3. Applying Global Styles to Blocks
Beyond settings, theme.json can apply default styles to specific blocks:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"styles": {
"blocks": {
"core/button": {
"color": {
"background": "var(--wp--preset--color--brand-blue)",
"text": "#ffffff"
},
"border": {
"radius": "4px"
}
}
}
}
}
This makes every Button block default to the brand blue background and white text — consistent styling without requiring editors to manually apply it each time.
Common Mistakes to Avoid
- Forgetting the
$schemaproperty — Including the JSON schema URL at the top oftheme.jsonenables validation in code editors like VS Code, which shows warnings for incorrect properties. It’s a small addition that makes authoringtheme.jsonsignificantly easier. - Using incorrect version numbers —
theme.jsonuses aversionkey that corresponds to the WordPress API version. Using an outdated version number means some newer settings and features won’t be available. Always check the current version in the WordPress developer documentation. - Caching issues during development — WordPress caches the stylesheet generated from
theme.json. During development, enable WP_DEBUG inwp-config.phpor visit Settings > Permalinks to flush the cache if yourtheme.jsonchanges aren’t appearing on the front end. - Overriding theme.json in CSS files — Changes made in
theme.jsonare output as CSS custom properties. If additional CSS files override those properties with hardcoded values, the design system breaks down. Keep design tokens intheme.jsonand reference them via CSS variables in any additional stylesheets.
Best Practices
1. Define All Design Tokens in Theme.json
Treat theme.json as the single source of truth for your theme’s design system. Define all colors, font sizes, spacing values, and layout dimensions there — don’t split them between theme.json and separate CSS files. This ensures that the editor experience and the front-end output stay aligned and that changes only need to happen in one place.
2. Disable Controls That Editors Shouldn’t Touch
Use theme.json settings to turn off controls that would allow editors to make off-brand or inconsistent design decisions. Setting "custom": false under color prevents editors from choosing arbitrary colors outside your palette. Setting "customFontSize": false under typography limits font size choices to your defined scale. A well-configured theme.json creates guardrails that make the editing experience safer for non-designers.
3. Validate Your theme.json Before Committing
Syntax errors in theme.json can break block editor functionality or cause styles not to load. Use a JSON validator or a code editor with JSON schema support to check your file before pushing changes. Google’s Structured Data Testing Tool analogy applies here — validate before you go live. Test on a staging site first when making significant changes to the design system.
Frequently Asked Questions
Is theme.json required for WordPress themes?
It’s not technically required for classic PHP themes, but it’s required for block-based themes that support Full Site Editing. For classic themes, adding theme.json is optional but increasingly recommended as WordPress continues building the block editor design system. It’s effectively required for any new theme development following modern WordPress standards.
Can I use theme.json with a classic (non-block) theme?
Yes. Classic themes can include theme.json to define color palettes and other settings that appear in the block editor. Starting with WordPress 6.1, classic themes can also use block-based template parts. The level of control is more limited than in a full block theme, but theme.json can still provide useful guardrails in classic theme contexts.
How does theme.json relate to the WordPress Customizer?
They serve different purposes and contexts. The Customizer is a live-preview settings panel used primarily in classic themes for colors, fonts, and layout options. theme.json is a developer-defined configuration file used in block themes to set defaults and controls. As WordPress transitions toward Full Site Editing, the Customizer is being phased out in favor of the Site Editor and theme.json.
What is the difference between theme.json settings and styles?
settings control what options are available in the editor interface — the color palette, font size choices, spacing controls. styles define the actual visual properties applied to the site and blocks — the background color, text color, font size values. Settings define the vocabulary; styles apply it. You can define a color in settings and then apply it as a style elsewhere in the same file.
Related Glossary Terms
- Full Site Editing (FSE)
- WordPress Theme
- Block Editor (Gutenberg)
- Template Part
- Child Theme
- Debug Mode (WP_DEBUG)
- CSS (Cascading Style Sheets)
How CyberOptik Can Help
theme.json is part of how we architect WordPress block themes — from color palette configuration to typography systems to block-level style defaults. If you’re investing in a custom WordPress site or a redesign, building on a well-structured theme.json foundation means your editors work within guardrails that protect brand consistency and your developers have a maintainable design system to build from. You don’t need to understand JSON to benefit from it — that’s what we’re here for. Get in touch to discuss your project or explore our WordPress development services.
