theme.json is the control center for WordPress block themes. It sets global styles, color palettes, type scales, spacing presets, and block-level defaults. When a theme update ships a new version of its own theme.json, your customizations can disappear. This isn’t a bug. It’s a file-replacement mechanism. The only fix that lasts is a documentation and override strategy built to survive the update cycle. For small-to-mid publishing teams running a handful of editorial sites, the cost of rediscovering lost design tokens after an auto-update isn’t theoretical. It’s a recurring operational drag that steals time from content work. This article maps the failure modes, then gives you a repeatable documentation pattern that keeps your customizations intact and auditable.
Why theme.json Overrides Fail Silently
WordPress merges multiple theme.json sources at runtime. The cascade starts with core, then the parent theme, then a child theme if one is active. User customizations stored in the database via the Global Styles interface sit on top. The problem is that most small-to-mid teams don’t use a child theme for block themes. They edit the parent theme’s theme.json directly because it’s fast and obvious. When the theme author releases an update, the entire theme directory gets replaced. Your edits are gone. Even if you use a child theme, a parent theme update can introduce new default values that shift spacing, color assignments, or type scales in ways that break your intended design. The override cascade is not a backup system. It’s a resolution algorithm. Without explicit documentation of what you changed and why, you’re left reconstructing intent from memory.
What Actually Lives in theme.json
Before you can document changes, you need to know what you’re changing. The theme.json file is structured into two top-level sections: settings and styles. Settings define what the editor allows—color palettes, font sizes, spacing units, custom properties. Styles apply default values to blocks and elements. A third section, customTemplates, defines page templates. A fourth, templateParts, defines template part areas. Most customization work happens in settings and styles. When you adjust the default color palette, you’re editing settings.color.palette. When you change the base font size, you’re editing styles.typography.fontSize. When you remove a core block style, you’re editing styles.blocks.core/button.variations. Knowing the exact path matters because your documentation needs to reference it.
Settings vs. Styles: The Merge Behavior
WordPress merges settings and styles differently. Settings are merged recursively. If you define a partial color palette in a child theme, it replaces the entire parent palette unless you explicitly include the inherited values. Styles are merged shallowly at the top level but deeply within block-level styles. This means a child theme’s styles.blocks.core/button completely replaces the parent’s button styles unless you re-declare every property you want to keep. This merge behavior is the root cause of most update-related breakage. Teams that don’t understand the difference between shallow and deep merging will lose customizations and not know why.
A Documentation Pattern That Survives Updates
The core idea is to treat every theme.json edit as a patch with a reason. You don’t need a child theme to document changes, but you do need a system. The system I use on publishing sites has three parts: a change log, a diff archive, and a recovery script. The change log is a simple markdown file stored in the theme’s root or a /docs folder. Each entry records the date, the JSON path, the old value, the new value, and the reason. The diff archive stores a copy of the modified theme.json before and after each change. The recovery script is a small Node.js utility that reads the change log and applies the documented patches to a fresh copy of the theme’s theme.json. This is not a plugin. It’s a manual process that takes discipline but pays back in hours saved during theme updates.
Change Log Format
Use a structured but human-readable format. Here is an example entry:
## 2025-01-14 — Adjust heading font sizes
Path: styles.elements.h2.typography.fontSize
Old: var(--wp--preset--font-size--x-large)
New: clamp(1.5rem, 4vw, 2.25rem)
Reason: Default x-large too small on editorial article pages; fluid clamp matches reading comfort studies (see Minion Pro at 16px body).
This entry tells the next person exactly what changed, what it was before, and why. The reason field is the most important part. Without it, someone will revert your change thinking it was a mistake. With it, they can evaluate whether the reason still holds after a theme update.
Diff Archive
Store a copy of theme.json before and after each change. Name the files with the date and a short slug: theme-2025-01-14-pre.json and theme-2025-01-14-post.json. This gives you a forensic trail. When the theme updates and your customizations disappear, you can diff the new parent theme.json against your last post-change version to see exactly what the update overwrote. This is faster than reading the theme changelog and guessing which of your changes were affected.
Recovery Script
A simple Node.js script can read your change log and re-apply your customizations to a fresh theme.json. The script parses the markdown, extracts the path and new value, and uses a library like lodash.set to write the value into the JSON object. This is not a production deployment tool. It’s a recovery tool for the moment after a theme update when you realize your heading sizes, color palette, and block spacing have all reverted to the theme defaults. Running the script gets you back to your intended state in seconds instead of hours.
What to Document: The High-Risk Properties
Not every theme.json property is equally likely to cause problems after an update. Focus your documentation effort on the properties that theme authors change frequently and that have high visual impact when they revert.
Color Palette
Theme authors update color palettes to match rebranding or design system changes. If you have customized the palette—adding a brand accent color, adjusting contrast ratios, or removing unused swatches—document every change. Include the hex values and the semantic names. When the theme updates, the palette is one of the first things to break. Your content will suddenly display with the wrong accent color, and nobody will notice until a reader emails.
Typography Scale
Font size presets and fluid typography settings are tightly coupled to the theme’s layout grid. A theme update that adjusts the base font size from 16px to 18px will shift every relative unit in your design. Document your exact typography scale, including the fluid min and max values if you use them. Reference the body text size and line height you validated for readability on your actual content.
Block Gap and Spacing Presets
Spacing presets defined in settings.spacing.spacingSizes control the spacing options available in the editor. If you have tuned these to match your content density, document them. Theme updates often add or remove presets, which can shift the default spacing of blocks across your entire site. The visual impact is subtle but pervasive—paragraphs suddenly feel too tight or too loose.
Custom CSS Properties
If you define custom properties in settings.custom, they are at high risk. Theme updates can overwrite the entire custom object. Document every custom property you add, including its name, value, and where it is used in your templates or block patterns.
Child Themes Are Not a Complete Solution
A child theme with its own theme.json can override parent settings and styles. This is the officially recommended approach. However, child themes introduce their own maintenance burden. The child theme’s theme.json must be kept in sync with the parent’s structure. If the parent theme adds a new setting that you want to inherit, you must explicitly include it. If the parent theme changes the structure of a block’s styles, your child theme’s overrides may break. For small teams managing multiple sites, maintaining child themes for each site can become a version-control headache. Documentation is still required, even with child themes. The change log simply moves to the child theme’s directory.
When to Use a Child Theme
Use a child theme when you are making more than a dozen theme.json changes, or when you are modifying template files. For smaller changes, direct documentation and a recovery script are often more practical. The key is to make a conscious decision, not to drift into a pattern of editing the parent theme because it’s convenient.
Version Control for theme.json
If your team already uses Git for custom themes or plugins, extend that practice to your documentation artifacts. Commit the change log, the diff archive, and the recovery script to a repository. This gives you a history of every customization, who made it, and when. For teams managing multiple sites, store each site’s documentation in a separate branch or directory. The goal is to make the state of each site’s design tokens reproducible from versioned artifacts.
If you are not using version control, start with the change log. A single markdown file in the theme directory is better than nothing. You can add the diff archive and recovery script later. The important thing is to capture the intent behind each change while it’s still fresh.
Testing Theme Updates Locally
Before applying a theme update to production, test it on a staging environment. This is standard advice, but the specific test for theme.json changes is to diff the new parent theme’s theme.json against your last documented version. Look for changes in the sections you have customized. If the theme author changed the default color palette, your custom palette may need adjustment. If they changed the typography scale, your custom font sizes may no longer fit the new scale. Run your recovery script on the staging site and visually inspect key pages. This process takes 30 minutes and prevents days of debugging after an update breaks your production site.
Real Failure Modes from Publishing Sites
I have seen a news site lose its branded accent color after a theme update because the custom palette was stored only in the parent theme.json. The editor who noticed the change assumed it was intentional and spent two hours trying to fix it through the Global Styles interface before realizing the theme update had wiped the custom palette. Another site had its article heading sizes revert to defaults, making long-form features look like blog posts. The team spent a day adjusting individual block settings before discovering the root cause. A third site lost its custom block gap presets, which broke the layout of its category archive pages. The fix required manually re-entering spacing values for dozens of blocks. Each of these failures could have been prevented or resolved in minutes with a change log and a diff archive.
Integrating with the Global Styles Interface
WordPress stores user-made Global Styles changes in the database. These changes are applied on top of the theme.json cascade. If you make a change through the Global Styles interface, it persists across theme updates. However, the interface does not expose every setting available in theme.json. For example, you cannot add custom CSS properties or modify the duotone filter palette through the interface. You also cannot document the reason for a change. The interface is a convenience tool, not a documentation system. Use it for quick tweaks, but document any change that affects the design system in your change log. If a setting can be made through the interface, note that in the log so the next person knows they have two paths to achieve the same result.
FAQ
What is the difference between theme.json and the Global Styles interface?
theme.json is a file that ships with the theme and defines default settings and styles. The Global Styles interface is a visual editor in the WordPress admin that lets users override some of those defaults. Changes made in the interface are stored in the database and survive theme updates. Changes made directly to the theme.json file are lost when the theme updates. The interface does not expose all theme.json properties, so some customizations still require file edits.
Can I use a child theme to protect my theme.json changes?
Yes, but with caveats. A child theme’s theme.json file overrides the parent theme’s settings and styles. However, the merge behavior is not always intuitive. Settings are replaced entirely unless you explicitly re-declare inherited values. Styles are merged shallowly at the top level but deeply within block-level styles. This means a child theme can still break after a parent theme update if the parent changes the structure of a block’s styles. You still need documentation of what you changed and why.
How do I recover my customizations after a theme update?
If you have a change log and diff archive, you can manually re-apply your changes by editing the new theme.json file. If you have a recovery script, you can run it to automatically apply your documented changes to the new theme.json. If you have neither, you will need to reconstruct your changes from memory or from a backup of the old theme files. This is why documentation is critical.
What if the theme update changes the structure of theme.json?
Theme authors occasionally restructure theme.json, for example by moving settings into separate files or changing the way block styles are organized. In this case, your recovery script may fail. You will need to manually map your old changes to the new structure. This is where the reason field in your change log becomes essential. It tells you the design intent behind each change, so you can re-implement it in the new structure rather than blindly copying old values.
Next Steps for Your Team
Start with a single change log file. Pick a format, document your next three theme.json edits, and store the before-and-after files. Once you have a few entries, write a simple script to re-apply them. Test the script on a staging site after the next theme update. Refine the process based on what breaks. Over time, this becomes a standard part of your theme update checklist. For teams managing multiple sites, consider centralizing the change logs and recovery scripts in a version-controlled repository. This turns a recurring source of frustration into a predictable, low-effort maintenance task.
If you are dealing with broader site breakage after a theme or plugin update, the diagnostic approach is similar. Start by identifying what changed and when. Our guide on what to fix first when a new WordPress site says nothing found walks through a structured troubleshooting method that applies equally to theme.json issues.
