Documenting theme.json Changes: A Field Manual for WordPress Publishing Teams

When a WordPress block theme breaks after an update, the culprit is almost always a silent overwrite of theme.json. This single file controls the global settings, styles, and block behaviors of your entire site. For small-to-mid publishing teams, losing custom typography scales, color palettes, or layout widths because a theme update wiped your changes is not a minor annoyance—it’s a content operations failure. The adjacent concepts here are child theming, version control, and the WordPress Styles Engine. The core problem is that theme.json merges settings from the parent theme, child theme, and user customizations, but a parent theme update can reset the baseline and discard your overrides if you haven’t documented what you changed and why. This article is a precise, failure-mode-driven guide to capturing those changes so the next person—or your future self—can rebuild them in under an hour.

Why Theme.json Documentation Is a Systems Problem, Not a Style Problem

Most teams treat theme.json as a design artifact. That’s the first mistake. It’s a configuration file that controls the WordPress Styles Engine, and it directly affects the block editor, global styles interface, and front-end CSS output. When a theme update ships a new theme.json, WordPress merges it with your child theme’s theme.json and any user customizations stored in the database. The merge logic is not always intuitive. A missing key in your child theme can cause a fallback to the parent’s default, while a key you set might be overridden by a higher-specificity rule in the parent’s update. Without documentation, you’re left diffing JSON files under deadline pressure, trying to remember if that "custom" block was yours or the theme author’s.

For small-to-mid publishing teams, the risk is compounded by role distribution. A developer might set up the initial theme.json, a designer tweaks values through the Site Editor, and an editor notices a broken block style six months later. No single person holds the full history. Documentation bridges that gap. It’s not about pretty changelogs; it’s about operational resilience.

What Actually Gets Stored in theme.json (and What Doesn’t)

Before you can document changes, you need to know what you’re documenting. A block theme’s theme.json can contain:

• Settings: Global control over features like custom colors, font sizes, spacing units, and block-specific options (e.g., enabling padding controls on the Cover block).
• Styles: Default values for colors, typography, spacing, and block-level CSS properties. These are the presets that the Site Editor exposes.
• Custom templates and template parts: Declared under "customTemplates" and "templateParts".
• Version: The "version" property, which tells WordPress which API version the file uses. A theme update might bump this from 2 to 3, changing how your settings are interpreted.

What theme.json does not store: user-created content, block patterns, or CSS from the Customizer. Those live elsewhere. But the line is blurry because the Site Editor’s “Global Styles” panel writes user modifications into the database, and those modifications are merged with theme.json at runtime. If a theme update changes a setting you previously overrode via the UI, the UI override might still win—or it might not, depending on the specificity of the new parent rule. This is why documentation must cover both file-level and database-level changes.

Step 1: Establish a Single Source of Truth for Your Theme.json Customizations

Most teams start with a child theme’s theme.json. That’s correct, but insufficient. The child theme’s file is your baseline, but it doesn’t capture changes made through the Site Editor. Those live in the wp_posts table as wp_global_styles custom post type entries. When a parent theme updates, the merge logic can produce unexpected results because the database values are applied on top of the file-based values. If you don’t document what you set in the UI, you can’t reconcile conflicts.

Practical step: Create a /docs/theme-json/ directory in your project repository. Inside, maintain a plain-text or Markdown file that lists every intentional deviation from the parent theme’s defaults. Use a format like this:

## 2025-03-15 — Added custom color palette
- Replaced parent palette with brand colors (see brand-guide.pdf)
- Added `--wp--preset--color--brand-primary: #1a73e8`
- Removed `tertiary` and `quaternary` presets
- Reason: Align with rebrand (JIRA TASK-421)

This is not a changelog for the file; it’s a decision log. The next person doesn’t need to know every line that changed. They need to know why a value exists so they can decide whether to keep it, update it, or discard it when the parent theme changes.

Step 2: Version Your theme.json Alongside the Parent Theme’s Version

WordPress themes carry a version number in style.css. Block themes also declare a "version" in theme.json. When the parent theme updates, that version number changes. Your documentation should tie your customizations to a specific parent version. This is critical because the parent’s theme.json structure can shift between versions—keys get renamed, deprecated, or moved. If you documented a customization against version 1.2 but the parent is now on 2.0, you know you need to re-audit every entry.

Create a file called theme-mapping.md that records:

• The parent theme name and version at the time of your last audit.
• A list of every theme.json key you’ve overridden, with the parent’s original value and your custom value.
• Whether the override is in the child theme’s theme.json, the database (Global Styles UI), or both.

When the parent theme updates, diff the new parent theme.json against the old one. Focus on the keys you’ve overridden. If a key you customized has been removed or restructured in the parent, your child-theme override might now be inert—or worse, it might apply in an unintended context. This is not a theoretical edge case. In one migration from a classic hybrid theme to a full-site editing theme, a team lost all custom font sizes because the parent theme moved them from settings.typography.fontSizes to styles.typography.fontSizes. The child theme’s overrides were silently ignored. A version-anchored doc would have flagged the mismatch immediately.

Step 3: Capture Global Styles Changes from the Database

When a user modifies a setting in the Site Editor—like adjusting the default heading font family—WordPress stores that change as a row in the wp_posts table with post_type = 'wp_global_styles'. These changes are merged on top of the theme.json cascade at runtime. The problem: they’re invisible to version control. If a theme update changes the underlying structure, the stored global styles can become orphaned or conflict in ways that are hard to debug.

To document these, export the global styles programmatically. You can use WP-CLI if it’s available on your environment:

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

Or, if you prefer a manual approach, navigate to /wp-admin/site-editor.php?path=%2Fwp_global_styles and use the “Export” option in the Styles panel. Save the resulting JSON file into your /docs/theme-json/ directory with a timestamp. This file is your record of UI-based changes. When a parent theme update lands, you can diff this export against the new parent’s theme.json to see exactly which user customizations might be affected.

Step 4: Build a Pre-Update Checklist That Forces Documentation

Most teams update themes reactively—a security notice or a feature request triggers it. Without a checklist, documentation gets skipped. Your checklist should be a plain text file in the repo, not a mental note. It must include:

1. Snapshot current state: Export the active theme.json from the live site (Appearance → Theme File Editor → theme.json) and the Global Styles export. Save both with the current parent theme version in the filename.
2. Diff parent theme.json: Compare the new parent version’s theme.json against the previous version. Focus on keys you’ve overridden.
3. Re-apply customizations: For each documented customization, decide: keep as-is, update to match new parent structure, or discard because the parent now provides an acceptable default.
4. Test in a staging environment: Apply the update, import your global styles export, and visually check key templates. Look for broken spacing, missing color swatches, and typography regressions.
5. Update the decision log: Record what changed, what you kept, and why. Link to the parent theme’s changelog if available.

This checklist is not busywork. It’s the difference between a 15-minute update and a 3-hour forensic debugging session while your site’s front page renders with system fonts and default black.

Step 5: Use a Child Theme the Right Way

A child theme’s theme.json is the safest place to store overrides because it survives parent theme updates. But many teams misuse it. They copy the entire parent theme.json into the child theme and then modify values. This is a trap. When the parent theme updates, your child theme’s full copy masks the parent’s new settings, so you miss out on improvements and bug fixes. Instead, your child theme’s theme.json should contain only the keys you are intentionally overriding. WordPress merges child and parent theme.json files, so a sparse child file is both safer and easier to audit.

Example of a minimal child theme.json that only overrides the color palette:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "brand-primary",
          "color": "#1a73e8",
          "name": "Brand Blue"
        },
        {
          "slug": "brand-secondary",
          "color": "#ea4335",
          "name": "Brand Red"
        }
      ]
    }
  }
}

This approach makes your documentation simpler: the child theme’s theme.json is the documentation for file-based overrides. Pair it with a comment in your decision log explaining why those colors were chosen, and you have a complete record.

Step 6: Document the Merge Behavior You Depend On

WordPress 5.9 introduced a two-layer merge for theme.json: the parent theme’s file and the child theme’s file. WordPress 6.0 added a third layer: user customizations from the Global Styles UI, stored in the database. The merge is additive for some properties (like color palettes) and fully overrides others (like settings.color.defaultPalette). If you set "defaultPalette": false in your child theme to disable core color palettes, a parent theme update that adds new default colors won’t affect you—but if the parent removes the defaultPalette key entirely, your override becomes meaningless. Document these dependencies explicitly. A simple table in your docs can map each customized key to the merge behavior you’re relying on.

Step 7: Automate the Diff When Possible

Manual diffing of JSON files is error-prone. If your team uses Git, add a pre-update script that diffs the parent theme’s theme.json against the new version and outputs only the keys you’ve overridden. A basic shell script can do this using jq:

diff <(jq --sort-keys . old-parent-theme.json) <(jq --sort-keys . new-parent-theme.json)

For teams without command-line access, online JSON diff tools work, but they compare entire files. The goal is to filter the diff to only the keys present in your child theme or documented overrides. This is where a sparse child theme pays off: you can diff your child theme’s theme.json against the new parent’s theme.json and immediately see conflicts.

Step 8: Train Editors to Recognize theme.json Regressions

Documentation is useless if the people who notice problems don’t know where to look. Editors and content managers are often the first to see a broken block style after an update. Give them a short, visual checklist:

• Are brand colors still appearing in the color picker?
• Are heading font sizes consistent with the style guide?
• Do buttons have the correct border radius and padding?
• Is the site’s maximum content width still correct on single posts?

If any answer is “no,” they should know to check the /docs/theme-json/ folder for the decision log and escalate to the developer who last touched the theme. This closes the loop between documentation and incident response.

Common Failure Modes and How Documentation Prevents Them

Here are three real scenarios I’ve seen on publishing teams, and how the practices above would have prevented each.

Failure 1: The Disappearing Font Stack

A team switched to a new block theme and customized the heading font family through the Site Editor. Six months later, a theme update reset all headings to the parent’s default serif font. The team had no record of the custom font choice. They spent two hours guessing which Google Font they had used. A simple export of Global Styles before the update would have captured the exact font family and weight.

Failure 2: The Broken Spacing Scale

A developer added custom spacing presets to the child theme’s theme.json to match a design system. The parent theme later introduced its own spacing scale with conflicting slugs. The merge resulted in duplicate presets and unpredictable spacing on live pages. A version-anchored decision log would have flagged the new parent presets, and the developer could have renamed the custom slugs to avoid the collision.

Failure 3: The Orphaned Block Setting

A team disabled the drop cap feature on the Paragraph block via theme.json. A parent theme update restructured the block settings array, moving the drop cap control under a new "typography" sub-key. The child theme’s override was silently ignored, and drop caps reappeared on old posts. A diff of the parent’s theme.json before and after the update would have revealed the structural change.

Integrating Documentation into Your Existing Workflow

This isn’t about adding a new process; it’s about capturing decisions you’re already making. When a designer asks for a new color, that request likely lives in a project management tool. Link the task ID in your decision log. When a developer modifies theme.json, the pull request should include an update to the /docs/theme-json/ file. When an editor changes a global style, the monthly maintenance window should include a fresh Global Styles export. These are small habits that compound into a durable system.

For teams that have already lost customizations and are rebuilding, start with a full audit of the current theme.json and Global Styles export. Document what you have now, even if you’re not sure why it’s there. Future you will thank present you for the breadcrumb trail.

FAQ

What’s the difference between theme.json in a child theme and Global Styles in the database?

The child theme’s theme.json is a file that lives in your theme directory and is version-controlled. Global Styles are user modifications made through the Site Editor and stored in the wp_posts table. At runtime, WordPress merges parent theme.json, child theme.json, and Global Styles. The child theme file is safer for intentional, team-wide defaults; Global Styles are convenient for quick tweaks but harder to track and audit.

How often should we export Global Styles for documentation?

At minimum, before every parent theme update. For active publishing teams where editors may adjust styles, a monthly export tied to your maintenance window is a good cadence. Store exports with a date stamp and the current parent theme version in the filename.

Can we just use a full child theme theme.json to avoid merge issues?

You can, but it’s not recommended. A full copy masks parent theme improvements and makes it harder to identify what you’ve actually customized. A sparse child theme theme.json that only contains your overrides is easier to audit, diff, and document. It also forces you to be intentional about every customization.

What if we don’t have a developer on staff to run diffs?

Non-developers can use the visual export tools built into WordPress. The Site Editor’s Styles panel has an export option that downloads a JSON file. Pair that with a simple checklist: before updating, export Global Styles and save the file. After updating, visually check the items on the editor checklist above. If something looks wrong, you have the export file to share with a contractor or support forum.

Next Steps for Your Team

Start with a single decision log entry for the most recent theme.json change your team made. Create the /docs/theme-json/ directory and commit it to your repository. Export your current Global Styles and save it there. These two actions take less than ten minutes and immediately reduce the risk of losing work on the next theme update. For teams managing multiple sites, consider a recurring column or internal wiki page that tracks theme versions and customization notes across your network. The goal is not perfect documentation; it’s documentation that prevents a 3 a.m. emergency rollback.

If you’re dealing with broader site configuration issues after an update, you might find our guide on What to Fix First When a New WordPress Site Says Nothing Found useful for diagnosing related problems.