Theme.json Reference Guide: Common Settings, Examples, and Gotchas

Overview

This section gives you the structure, common settings, and a mental model you can use before editing anything.

At a high level, theme.json is WordPress's configuration layer for block themes and block-based editor settings. It helps define design tokens, editor controls, presets, and style rules in one place. If you have ever changed spacing in one block, adjusted colors somewhere else, and then tried to keep the editor consistent across a site, theme.json exists to make that work more predictably.

For many teams, it becomes the center of a cleaner WordPress developer workflow because it reduces one-off CSS fixes and scattered PHP customizations. It can also make a site easier to maintain over time, especially when the goal is to standardize typography, colors, layout widths, and allowed design options for content editors.

In practical terms, theme.json usually contains top-level sections such as:

• version: the schema version used by the file.
• settings: controls what customization features are available in the editor.
• styles: defines visual styles for the site, blocks, and elements.
• templates or block-specific configuration in some theme setups.
• custom: optional project-specific values that may be referenced in your workflow.

A simplified example looks like this:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "name": "Primary", "color": "#1d4ed8" },
        { "slug": "accent", "name": "Accent", "color": "#f59e0b" }
      ]
    },
    "spacing": {
      "units": ["px", "rem", "%", "vw"]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#111111"
    },
    "typography": {
      "fontSize": "16px",
      "lineHeight": "1.6"
    }
  }
}

If you are new to block themes, think of settings as the part that controls available design tools, and styles as the part that applies actual design decisions.

The most common WordPress theme json settings developers reach for are these:

• Color palette: set brand colors once and expose only the options you want.
• Typography: define font sizes, line heights, font families, and fluid type rules.
• Spacing: standardize margin, padding, block gap, and allowed units.
• Layout: establish content width and wide width for consistency.
• Blocks: override settings or styles for specific blocks only.
• Elements: style shared HTML elements such as links, buttons, and headings.

Here is a compact block-specific example:

{
  "version": 2,
  "styles": {
    "blocks": {
      "core/button": {
        "border": {
          "radius": "6px"
        },
        "spacing": {
          "padding": {
            "top": "0.75rem",
            "right": "1.25rem",
            "bottom": "0.75rem",
            "left": "1.25rem"
          }
        }
      }
    }
  }
}

This is where a lot of developers begin: start with global tokens, then define a few high-value block styles that would otherwise require repetitive CSS.

If you want a broader implementation walkthrough after this reference, see WordPress Block Theme Customization Guide for Developers.

Maintenance cycle

This section explains how to keep your theme.json file usable over time instead of letting it become a fragile dump of experiments.

The most effective way to manage theme.json is to treat it like a living configuration file with a review cycle. Even if your site design is stable, WordPress evolves, editor controls change, and new block capabilities may shift how you want to organize styles.

A practical maintenance cycle looks like this:

1. Review on a scheduled release rhythm

Choose a predictable interval, such as quarterly or around major WordPress updates. You are not hunting for novelty. You are checking whether your current setup still matches how the editor behaves and whether old workarounds can be removed.

2. Audit design tokens before adding exceptions

When someone requests a new color, spacing value, or font size, pause before inserting it. Ask whether it belongs in the core system or whether it is a one-off styling need that should stay outside the shared token set. Too many exceptions make theme.json harder to understand and easier to misuse.

3. Test editor and front-end parity

One of the biggest benefits of theme.json is that it can align editor output with front-end output. During maintenance, compare both views. If a block looks right in the editor but not on the site, or vice versa, you may have a conflict with theme CSS, custom block styles, or plugin output.

4. Keep block-specific overrides intentional

It is tempting to keep adding styles under styles.blocks for every visual request. That works for small themes, but over time it can hide the design system. If many blocks share the same spacing or typography decisions, move those values upward into global settings where possible.

5. Use version control for every meaningful change

Because theme.json can affect the editor and the front end at once, even small edits deserve a commit message that explains the reason for the change. If your process is still informal, a more structured workflow helps. See WordPress Git Workflow for Small Teams: Branching, Deployments, and Rollbacks.

6. Test locally before pushing changes live

This file is not dangerous in the same way as custom PHP, but it can still create layout issues, confusing editor options, or visual regressions. A local environment is the safest place to experiment. If your setup is not stable yet, review Local WordPress Development Setup Guide: LocalWP, Docker, DevKinsta, and XAMPP Compared.

A useful rule is simple: every time you change branding, introduce a new reusable block pattern, or update a block theme significantly, review theme.json at the same time.

Signals that require updates

This section helps you recognize when your current file no longer matches your site's real needs.

You do not need to review theme.json only because a calendar reminder appears. Some signals should trigger a faster update.

Editor controls feel inconsistent

If editors can choose some spacing values in one block but not another, or if colors appear in the UI that your brand no longer uses, the file may need cleanup. This often happens after partial redesigns or after mixing legacy theme CSS with block theme settings.

New custom CSS keeps piling up

Custom CSS is not inherently bad, but repeated front-end fixes for basic typography, spacing, and button styling can mean your design system belongs in theme.json instead. When those tokens live centrally, maintenance usually becomes easier.

Design updates are slow to implement

If changing a font scale or layout width requires editing multiple templates, stylesheets, and block settings, that is a strong sign your configuration is too fragmented. Consolidating shared decisions into theme.json can shorten future redesign work.

Plugins introduce unexpected style options

Some blocks or plugins add their own controls and styles. After activating a plugin, review whether those additions work with your existing palette, spacing scale, and typography rules. This is especially important in websites that combine editorial pages, landing pages, and commerce components.

Theme migration or architecture changes

If you are moving from a classic theme toward a more block-based setup, or deciding between a child theme and a custom theme, theme.json should be part of that review. For background, see Child Theme vs Custom Theme: Which WordPress Approach Makes Sense in 2026? and WordPress Child Theme Checklist: Every File You May Need to Override.

Search intent or team needs have shifted

This article is built as a reference because the practical use of theme.json changes over time. A few years ago, many developers mainly wanted syntax help. Later, they may care more about design token organization, editor restrictions, and maintainability. If your team is asking new questions, your file structure may also need to evolve.

Common issues

This section covers the problems that most often cause confusion, wasted time, or brittle theme setups.

1. Mixing global and block-level styles without a clear rule

A common mistake is defining typography globally, then redefining it for many individual blocks, then adding CSS overrides on top. The result is hard to debug. Try this order instead:

1. Set the base design system globally.
2. Use block-level overrides only where the block truly needs unique treatment.
3. Use custom CSS as the last layer, not the first.

2. Treating theme.json as a replacement for all CSS

Theme.json is powerful, but it is not a complete substitute for stylesheet architecture. It handles many editor-facing design decisions well, but complex layouts, animations, edge-case responsive behavior, and specialized component styling may still belong in CSS.

3. Adding too many presets

Color palettes with a dozen near-identical shades, oversized font scales, or unrestricted spacing units can make the editor harder for content teams to use. A smaller, purposeful set of options usually creates better consistency.

4. Forgetting the difference between settings and styles

This is one of the most common beginner mistakes in any theme json reference. If you want to allow or disable a capability, it usually belongs under settings. If you want to define how something looks, it usually belongs under styles.

5. Relying on outdated snippets

Developers often copy old theme json examples without checking whether the structure still matches the current project. Even if the syntax is close, older examples can lead to hidden inconsistencies. Keep a short internal library of tested patterns rather than pasting random snippets into production themes.

6. Ignoring plugin conflicts

When block styles behave strangely, the issue may not be the theme alone. A plugin can register blocks with styles or controls that clash with your expected defaults. If something changes after a plugin install, isolate the conflict before rewriting your design system. For broader customization patterns, the article WordPress Hooks and Filters Reference for Theme and Plugin Customization is a useful companion.

7. Storing site-specific logic in the wrong place

Theme.json is for theme configuration, not for unrelated feature logic. If you are drifting into functional behavior, custom post processing, or site-specific utilities, that likely belongs in a small plugin or another safer extension point. See Beginner's Guide to Creating a Custom WordPress Plugin for Site-Specific Changes and Custom Functions.php Alternatives: Safer Ways to Add WordPress Snippets.

8. No build or validation workflow

As projects grow, design tokens may also live in SCSS, JavaScript, or documentation. If your theme setup is more advanced, make sure the relationship between those tools and theme.json is documented. Otherwise duplicate values drift apart. For modern tooling considerations, read Modern WordPress Build Tools Compared: Vite vs Webpack vs @wordpress/scripts and How to Use Composer with WordPress Themes and Plugins.

A simple way to avoid many of these issues is to document three things beside the file itself: what your global tokens are, which blocks intentionally break the global rules, and which plugin-added blocks need special handling.

When to revisit

This final section gives you a practical checklist for using this guide as an ongoing reference.

Revisit your theme.json file when any of the following happens:

• You update WordPress and notice editor behavior has changed.
• You launch or refresh a design system.
• You add a major plugin that introduces new blocks or editor controls.
• You start seeing repeated CSS overrides for spacing, typography, or colors.
• You migrate from a classic theme toward a block-first approach.
• You onboard a new developer or content team and need clearer standards.

For a lightweight recurring review, use this checklist:

1. Open the current file and scan for duplication. Look for repeated values that could become shared presets.
2. Review color, typography, spacing, and layout presets. Remove anything no longer used.
3. Check block-specific overrides. Confirm each one still serves a real purpose.
4. Test in the editor and on the front end. Compare the most important page templates and reusable blocks.
5. Audit plugin-added block behavior. Make sure new controls do not weaken your editorial standards.
6. Record what changed. A short changelog note saves time later.

If you maintain more than one site, consider creating your own internal theme.json reference built from tested patterns: a standard palette format, a preferred spacing scale, a button style snippet, a layout baseline, and any known compatibility notes. That turns future customization work into a repeatable system rather than a fresh debugging exercise each time.

The real value of theme.json is not just that it centralizes configuration. It gives you a better way to connect design decisions, editor experience, and maintainable theme architecture. When treated as a reference-backed, regularly reviewed part of your workflow, it becomes one of the cleanest foundations for custom WordPress development and a more sustainable way to learn WordPress development in the block era.

Keep this page bookmarked, review your file on a schedule, and update it whenever your design system or editor behavior shifts. That habit will save more time than any single snippet.