The Client-Proof Site Editor: A theme.json Playbook

Summary

When a client opens the WordPress Site Editor for the first time, the ability to edit every block, color, and layout can feel like a feature to them — and like a threat to you. This article explains how to use theme.json to draw a clear line between content editing and design control. Instead of fighting the Site Editor, you set up presets, defaults, and boundaries that make it safe for non-technical clients to update their own site. We'll walk through what to lock down, what to leave open, and why over-locking is a real risk. The approach is built around design tokens and template-level constraints, so it works consistently across every client site you maintain. By the end, you'll have a repeatable workflow for handing over the Site Editor without handing over the keys to your design system.

What's the first thing you do when a client emails to say they "just tried to update the headline" and the entire site's spacing has collapsed?

If you maintain more than one WordPress site, you've probably received that message in some form. The Site Editor gave your client the keys to a car with five gear shifts and no brake. They think they're making a simple text change, and suddenly the global typography is off, the homepage hero has a neon color you didn't choose, and two blocks are now stacked instead of side-by-side.

Meanwhile, you're thinking about the six other client sites you support, and the last thing you need is a maintenance trap where every "helpful" client edit requires a restore from backup.

The answer isn't to take away the Site Editor. It's to set boundaries inside it using theme.json. According to the WordPress Developer Resources, theme.json is the central source of truth for block editor settings and styles — it defines the color palettes, typography, and layout options that appear to the client. That means the same file that controls your design can also control what your client can and cannot edit.

Let's walk through how to think about this, because most tutorials focus on what theme.json can do for developers. The question for an agency is different: how do we use it to make clients safe without making them feel boxed in?

Why does the Site Editor feel so dangerous?

Your client is not trying to break the site. They're trying to do what you've been training them to do for years in the old editor: change a headline, swap an image, maybe add a paragraph. The danger isn't their intention — it's that the Site Editor surfaces global controls in the same place as content controls.

Here's a common scenario. A client opens a template in the Site Editor and sees a heading block. They change its color to match the new brand swatch. But because that heading is in a template, the change applies everywhere that template is used. To the client, it looked like one edit. To the site, it was a global change.

The general principle: when you hand someone a page builder, they will eventually find the "settings with guardrails" and turn them off. But with theme.json, you can hide the guardrails themselves. Instead of telling the client "don't touch the global styles," you simply don't show them a color palette that can produce a bad result. You define a palette of approved colors, a scale of font sizes, and a set of spacing presets — and the client chooses from those, not from the full spectrum of CSS.

That's the first shift: stop thinking about rules, and start thinking about factories. theme.json is your production line. You configure the options the client sees, and the constraints are enforced by the interface itself, not by a set of instructions in a handover document.

What should you actually lock down?

Not everything. If you lock the content area too tightly, the client will either call you every time they need to add a paragraph, or they'll find a way around you — often by adding a one-off plugin or copying HTML from their old site.

Here's a practical table of what to lock, what to leave, and why:

Editing surface	Lock down?	Why
Template structure and block layouts	Lock	Prevents accidental removal or reordering of core layout blocks
Global styles (colors, fonts, spacing presets)	Lock with presets	Clients pick from an approved set, not arbitrary values
Content text and images	Leave open	This is their job; let them do it without asking permission
Spacing between blocks	Partially lock	Provide spacing presets so they can adjust rhythm without breaking alignment
Curated block patterns	Leave open if you've vetted them	A safe way for clients to add new sections without building from scratch

The important nuance is "lock with presets," not "lock out." For global styles, you're not hiding the settings panel; you're reducing the number of choices to a curated set. For template structure, you can lock certain blocks so they can't be removed, but still allow clients to edit the text inside them.

One word of caution: locking a block in a template is different from locking it in a specific page. Template locks affect all content that uses the template. If you need different lock levels on different pages, you'll need to work at the block level inside the editor, which is more fragile. For repeatable agency work, design your templates so the locked areas are consistent.

How do you set boundaries without making the editor feel like a trap?

The technique is to define your design tokens in theme.json and then resist doing anything else in CSS.

For example, instead of letting the client set an arbitrary color on a button, you define a button style in theme.json that uses a specific color from your palette. The client can still select the button and change its text, but the color picker only shows your approved swatches. It's the same for font sizes, line heights, and spacing.

The same principle applies to templates. You can use the "lock" feature on specific blocks within a template — for example, locking the column structure of a testimonial block so a client can change the quote text but not turn three columns into two. If you haven't used block locking yet, it's available in the editor toolbar; when you lock a block, you can choose whether the client can edit content, move it, or both. You can even apply this in theme.json for block-level defaults.

What you're aiming for is an editor where the client never sees a control that can break the design. That doesn't mean they can't do anything wrong; it means the worst wrong thing they can do is change a headline's wording, not the entire site's look.

If you're using custom post types, the same principles apply beyond the default templates — see our guide on extending theme.json to custom post types and plugin output.

What happens when you lock too much?

Here's the contrarian point: over-locking is just as harmful as under-locking. A client who cannot resize a heading or add a gap between sections will eventually ask you to "just make it look right" — and then you're back to doing small edits for free. Worse, they might decide the Site Editor is useless and go back to a third-party page builder, which gives them too much control again.

The tradeoff is real. Locked-down editors produce fewer emergency calls, but they also produce more "can you just move this button up by five pixels" requests. Locked-open editors produce the opposite. Your job is to find the balance point for each client, not to apply one configuration universally.

A good starting heuristic: lock everything that affects all instances of something (global styles, template structure), and leave open everything that affects one instance (a single page's text and images). If a client breaks a single page, it's a 5-minute fix. If they break a global style, it's a 20-minute fix and a security concern.

How do you make this repeatable across clients?

This is where the agency workflow comes in. You should have a base theme.json that defines your design tokens — the color palette, typography scale, and spacing presets — and then a per-client override file that extends or changes specific values.

Start by creating a "starter" block theme. Here's how to build a custom block theme with theme.json — once you've developed and documented it, copying it to a new client is a matter of swapping brand colors and fonts. You're not rebuilding the wheel; you're swapping out tokens. This is exactly the stop rebuilding every WordPress site mentality, but applied to the editor rather than the backend.

Because theme.json is a single file, it's also easy to version-control and deploy across multiple environments. You can review changes, see what a client has modified in the global styles, and diff those changes against your base file. That gives you a strong audit trail for support requests.

If you're maintaining multiple sites and you haven't set up a base theme yet, this is your chance. It's the one piece of custom WordPress work that pays for itself every time a client opens the editor.

What about clients who keep asking for "one more color"?

Your palette is a promise. If you define five brand colors, and a client asks for a sixth, the answer isn't "no" — it's "yes, but it arrives as a deliberate addition to the palette, not as a one-off hex code in a heading." When you add a color to theme.json, it becomes available throughout the site consistently. That's the right way to handle those requests.

This is also where you need to communicate with the client. Explain that the Site Editor shows them only the colors and fonts that match their brand standards. If they want to expand those standards, you'll handle it in the design system, and then every new color will be available everywhere — including on future pages they haven't built yet. That's a much better answer than "we don't do that."

At the same time, don't accumulate a palette of forty colors. Revisit it quarterly and remove anything that was a one-time accident. The goal is a small, intentional set of options.

If you lock the layout but leave the content, and you make the palette a living part of your client relationship, the Site Editor stops being a threat. It becomes a way to hand your clients real autonomy without sacrificing the design standards you're paid to protect.