How to Document theme.json Changes So the Next Theme Update Doesn’t Undo Them

theme.json is the single source of truth for block theme settings, styles, and template defaults in WordPress. But when a theme update ships a fresh version of that file, any direct edits you made to the parent theme’s theme.json get wiped. No error message. No warning. Just a site that suddenly looks a little off—wrong colors, missing font sizes, content widths that snap back to the theme author’s defaults. For a small-to-mid publishing team running a house theme on a block-based stack, this isn’t a one-time annoyance. It’s recurring technical debt. The answer isn’t to freeze theme updates. The answer is a documentation and override strategy that treats theme.json as a living configuration layer, not a static file you hack on directly.

Why theme.json Edits Vanish and What Actually Gets Lost

Block themes load theme.json straight from the active theme directory. A theme update replaces the entire folder. If you added custom color slugs, tweaked the content width, or registered new font sizes directly in that file, those changes are gone. The same thing happens with child themes that inherit a parent’s theme.json but don’t explicitly override the sections you modified. The damage isn’t just cosmetic. When a publishing team depends on specific settings.color.palette entries to enforce brand consistency, a missing slug breaks the editor UI. Content creators fall back to inline styles. That’s a governance failure, not a technical glitch.

Three things matter here: theme.json merging logic, block-level style inheritance, and editor setting defaults. WordPress core merges multiple theme.json sources—core, theme, child theme, and user customizations—using a deep-replace algorithm. If you don’t understand that merge order, you’ll keep losing changes.

Map the Merge Order Before You Touch a Single Value

WordPress resolves theme.json settings in this sequence: core defaults, parent theme, child theme, and finally user customizations stored in the database via the Global Styles interface. Each layer can override or extend the previous one. Edit the parent theme’s theme.json directly, and you’re working in the second layer—the one that gets replaced on update. The only durable layers are the child theme and the database. If you don’t use a child theme, the database layer is all you’ve got. But it’s opaque: serialized PHP sitting in the wp_posts table under the wp_global_styles post type. Documenting changes means recording which layer you modified and why.

Start by exporting the current active configuration. Run wp theme json get from WP-CLI to dump the resolved settings and styles. That output is the merged result of all layers. Diff it against the parent theme’s original theme.json. Every difference is a customization that will disappear on update unless it lives in a child theme or the database. That diff is your documentation baseline.

Build a Child Theme Override File That Survives Updates

The most reliable way to preserve theme.json changes is a child theme. Drop a theme.json in the child theme directory that contains only the sections you need to override. WordPress merges child theme values on top of parent theme values. If the parent changes something you haven’t overridden, you get the update. If you’ve overridden it, your value wins. This selective-override approach is cleaner than copying the whole parent file.

Say you need a custom color palette and a wider content area. Your child theme’s theme.json might look like this:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "brand-blue",
          "color": "#1e3a8a",
          "name": "Brand Blue"
        }
      ]
    },
    "layout": {
      "contentSize": "840px",
      "wideSize": "1200px"
    }
  }
}

Document each override in a plain-text changelog stored in the child theme root: theme.json CHANGELOG.txt. For every entry, record the date, the parent theme version at the time, the specific section modified, and the reason. When the parent theme updates, this changelog is your single source of truth for auditing whether your overrides are still necessary or now conflict with new parent defaults.

When Child Themes Aren’t an Option: Documenting Database-Stored Global Styles

Some teams skip child themes because they add maintenance overhead or clash with a managed hosting workflow. In that case, customizations made through the Site Editor’s Global Styles panel live in the database. The problem: those changes are invisible to version control and can be accidentally reset by anyone with administrator access. Documenting them means extracting the database values and storing them as a reference file in the project repository.

Use WP-CLI to export the user-modified styles:

wp post list --post_type=wp_global_styles --format=json

This returns one or more posts containing the serialized style data. Pipe the output to a JSON file and commit it alongside the theme. Before and after every theme update, re-export and diff the file. If the update wipes the database styles—which can happen if the theme’s theme.json structure changes significantly—you’ll have a snapshot to restore from. This isn’t a backup strategy; it’s a change-detection mechanism. The actual restoration still requires manual reapplication through the editor or a custom script.

Create a theme.json Audit Script That Flags Drift

Manual diffing doesn’t scale if you’re managing multiple sites. Write a small shell script that compares the active theme’s original theme.json (stored in a /reference directory in the project repo) against the current resolved output from wp theme json get. The script should flag any key that appears in the resolved output but not in the reference file—or any value that differs. Run it right after a theme update and again after any editor modifies Global Styles. The output is a plain-text report you can store in version control. Documentation stops being a chore and becomes an automated artifact.

Here’s a minimal example using jq for JSON diffing:

diff <(wp theme json get --theme=parent-theme) <(wp theme json get) | grep '[<>]' > theme-json-audit.txt

This assumes you’re comfortable with command-line tools. If not, the manual diff described earlier is the fallback. Either way, the output must be human-readable and stored where the next person who updates the theme will find it.

Document the “Why” Behind Each Customization

A diff shows what changed. It doesn’t show whether a customization is still needed. Without context, a developer updating the theme might assume an override is stale and remove it. Your documentation must answer three questions for every modified value: What business requirement does this serve? What breaks if it’s removed? Who approved it? Store these answers in the child theme’s changelog or in a theme.json companion document. For database-stored styles, keep a parallel markdown file that maps each Global Styles change to its rationale.

Example entry:

## settings.layout.contentSize: 840px
- Date: 2025-02-14
- Parent theme version: 2.1.0
- Reason: Editorial team requires wider content area for long-form articles with inline media. Default 640px causes excessive wrapping on 50% of published posts.
- Approved by: Lead Developer (J.V.)
- Depends on: Nothing. Safe to keep indefinitely unless parent theme changes layout engine.

This level of detail stops well-meaning cleanup from reintroducing a known problem. It also serves as institutional memory when team members rotate.

Handling theme.json Partial Overrides and Block-Level Styles

Not all customizations belong in the top-level theme.json. Block-level styles—modifying the default appearance of a core block—can go in a child theme’s theme.json under styles.blocks. These overrides are granular and less likely to conflict with parent theme updates. Document them with the same rigor: which block, which property, and why the default is insufficient. If the parent theme later improves that block’s default, your override may become redundant. The changelog helps you decide whether to keep or retire it.

For custom block styles registered via theme.json (the styles.blocks.core/paragraph.variations pattern), document the design token they represent. Publishing teams often create “Article Body,” “Sidebar Note,” or “Caption” variations. When a theme update changes the underlying CSS custom properties, these variations can silently break. A companion style guide that maps each variation to its visual output—screenshots included—lets editors spot regressions immediately after an update.

Integrate theme.json Documentation into the Deployment Checklist

Documentation nobody reads is dead weight. For a small-to-mid publishing team, the most effective place to surface theme.json change logs is the deployment checklist. Before pushing a theme update to staging, the checklist should require:

• Diff the parent theme’s new theme.json against the previous version.
• Cross-reference each parent change with the child theme’s override changelog.
• If a parent change affects a section you override, test the site with the override temporarily removed.
• Re-export database-stored Global Styles and diff against the last snapshot.
• Update the changelog with any new decisions.

This process adds 15–20 minutes to a theme update. It prevents hours of debugging when the editorial team discovers broken styles on deadline. For a deeper look at systematic debugging workflows, see What to Fix First When a New WordPress Site Says Nothing Found, which applies the same diagnostic rigor to a different failure mode.

FAQ

Can I just lock the parent theme to prevent updates?

You can, but it’s a short-term hack that creates long-term risk. Theme updates often include security patches and compatibility fixes for new WordPress versions. Locking the theme trades style stability for potential vulnerabilities. A child theme with documented overrides gives you both: you can update the parent safely and keep your customizations.

What if my team uses a block-based child theme but still loses changes?

Check whether the parent theme’s theme.json uses the "custom" section for settings that your child theme also defines. The merge logic is additive for most top-level keys, but if the parent removes a setting your child theme depends on, the resolved value can disappear. Your audit script should flag removed keys, not just changed values. Also verify that your child theme’s theme.json is valid JSON—a single syntax error causes WordPress to ignore the entire file.

How do I document Global Styles changes if I don’t have WP-CLI access?

If your host restricts WP-CLI, use the WordPress REST API. Send a GET request to /wp/v2/global-styles to retrieve the current styles. The response includes the merged theme.json data. Store this JSON in your project repository and diff it manually after updates. It’s slower but achieves the same result. For teams on managed hosts that block both WP-CLI and REST API access, export the Global Styles data using a plugin like “Create Block Theme,” which can save the current configuration as a physical theme.json file inside the theme directory.

What’s the risk of storing overrides only in the database?

Database-stored Global Styles are tied to the active theme’s text domain and structure. If the parent theme changes its slug or reorganizes its theme.json schema, the stored styles may no longer map correctly. WordPress attempts to migrate them, but the result is unpredictable. Without a documented snapshot, you won’t know what was lost. Always export before updating.

Should I version-control the entire resolved theme.json?

Version-controlling the resolved output is useful as a historical record, but it shouldn’t replace the override-focused documentation described here. The resolved file is a merge artifact; it doesn’t tell you which layer owns which value. Store it as a secondary reference, but make the child theme’s theme.json and the changelog your primary artifacts.