Global Styles in the Site Editor

What global styles are: the changes you make in the site editor's Styles panel, saved as a database record layered on top of the theme's own theme.json rather than written into any theme file. They are the fastest way to customise a WordPress theme without editing code, and the reason those adjustments are theme-specific rather than site-specific.

Where the Styles panel sits in the stack

theme.json defines the baseline. Global styles are a second, later layer WordPress compiles and merges on top of it, without touching the original file. The merge means an untouched setting still falls back to whatever theme.json specified — global styles only need to record what you actually changed, not the whole design system, and the override reaches every template and template part alike.

That single fact explains most of the surprising behaviour people report:

• Editing in the Styles panel never modifies theme.json. The file on disk stays exactly as the theme author shipped it.
• The override is theme-specific. It is stored against the currently active theme, so it has no effect, and is not even visible, once a different theme is active.
• Removing the override reverts cleanly to theme.json's own values, because those values were never overwritten, only outranked.

What the panel can change

The Styles panel groups controls into a few areas that map directly onto theme.json's styles section:

The per-block section is worth knowing about specifically: clicking into an individual block type from the Styles panel (rather than selecting a block on canvas) lets you set a default for every instance of that block sitewide — every button gets the new padding, not just the one you were looking at when you opened the panel. That is different from selecting one button on a page and changing it there, which is a block-level style scoped to that instance alone, not a global one.

Style variations

A theme can ship a styles directory containing extra JSON files, each a self-contained alternative set of settings and styles — a different palette, different type pairing, sometimes different spacing. These show up in the Styles panel as a grid of preview thumbnails. Clicking one applies its settings and styles as your starting point.

Choosing a variation is not a live toggle you can flip back and forth between afterwards expecting your other edits to persist untouched — it applies that variation's values into your global styles record, on top of (or replacing, for anything the variation defines) whatever was there. If you have already customised colours by hand and then pick a variation that also defines colours, the variation's colours take over. Applying one is closer to a starting point you then continue to adjust than a saved preset you switch among freely.

Reverting to theme defaults

The Styles panel carries a reset action — worded along the lines of "Reset to defaults" — that discards the saved global styles record and returns every control to whatever theme.json specifies. This is a full revert of the whole record, not a per-control undo, so a targeted "undo just this one colour change" is better handled with the editor's regular undo before saving, or by manually setting that one control back.

Why global styles do not travel with the theme

Because the override lives in the database, keyed to the currently active theme, it is bound to that theme and not portable by switching. Two consequences that catch people out:

• Deactivating and reactivating the same theme keeps the styles, since the database record persists as long as the theme it's keyed to does.
• Switching to a different theme shows that theme's own defaults, with no migration. Switching back to the original theme later brings the old global styles back too — nothing was deleted, it simply had no effect while inactive.

If a look genuinely needs to survive a theme change, it has to be rebuilt in the new theme's Styles panel, or set at the theme.json level of a child theme built for that purpose, as in creating a WordPress child theme.

When to edit theme.json instead

Global styles are the right tool for a site owner adjusting their own instance of a theme. theme.json is the right tool when the change should be the theme's baseline for anyone using it — a theme you are building, a child theme meant to distribute a look, or a default you want new global-styles resets to fall back to. If you find yourself repeating the same Styles panel changes across every new site built on a given theme, that repetition is a sign the change belongs in theme.json instead.

Common mistakes

• Expecting Styles panel changes to appear in the theme's files. They never do; they are database-only.
• Assuming a style variation is reversible with one click. Reverting after applying one means resetting to defaults or manually undoing, not selecting the variation again.
• Being surprised colours vanished after a theme switch. They are still saved, just inactive until the original theme is active again.
• Setting per-block defaults through the wrong path. Selecting an instance on canvas changes only that instance; the block-specific section of the Styles panel is what changes every instance.
• Not checking cached CSS after a reset. As with any styling change, confirm on the front end per how to clear WordPress cache before concluding a reset didn't work.

Verify

Open the Styles panel, change the global text colour, save, and confirm it applies across different templates and post types on the front end. Then use Reset to defaults and confirm the colour returns to theme.json's original value rather than staying overridden. Finally, switch to a different installed theme and back, and confirm your saved global styles for the original theme reappear unchanged.