Global Styles and theme.json

Global Styles provide a site-wide design interface for colors, typography, layout and block appearance.

The theme.json file provides the underlying configuration system used by themes to define settings, presets and default styles. It works with block themes and can also enhance classic themes.

Together, they create a design layer between raw CSS and one-off block settings.

What Global Styles Control

With a compatible theme, authorized users can manage:

• Color palettes and gradients.
• Typography and font choices.
• Content and wide layout widths.
• Spacing and dimensions.
• Site background.
• Block-specific styles.
• Style variations.
• Additional CSS.

The available controls depend on the active theme and WordPress version. Themes can intentionally limit options to protect design consistency.

What theme.json Does

theme.json is a JSON configuration file placed in the theme.

It can define:

• Which design tools the editor exposes.
• Preset colors, font sizes, spacing values and other tokens.
• Default styles for elements and blocks.
• Template registrations.
• Template-part metadata.
• Custom design properties.

Because settings are machine-readable, WordPress can apply them consistently in the editor and frontend.

Settings vs Styles

The settings section controls capabilities and presets. It can enable typography tools, define a palette or restrict custom values.

The styles section defines actual visual defaults, such as body typography or button colors.

This distinction allows a theme to say both what editors may choose and what the initial design should be.

The Style Cascade

WordPress combines styles from several origins:

• Core defaults.
• Theme theme.json.
• Theme style variations.
• User Global Styles customizations.
• Block-level settings.
• Theme and plugin stylesheets.
• Additional custom CSS.

More specific or later rules can override earlier ones. When a file change appears to have no effect, stored Global Styles or block-level settings may be taking precedence.

Presets as Design Tokens

Presets provide named values such as a brand color, content width or spacing size.

Using presets instead of arbitrary values improves consistency and makes future redesigns easier. If every block references the same preset, changing the underlying token can update the system more predictably.

A focused theme should expose enough choices for real editorial needs without turning every block into an unconstrained design tool.

Style Variations

Style variations are alternative theme.json configurations distributed with a theme.

They can offer different palettes, typography systems or broader visual directions without changing the template structure. Users can select a variation in the Styles interface and then customize it further.

Variations should be tested as complete systems rather than isolated color swaps.

Using theme.json in Classic Themes

Classic themes can use theme.json to define presets, editor settings and styles even without the full Site Editor.

This can bring editor and frontend styling closer together and provide modern appearance tools while preserving PHP templates.

It does not automatically turn a classic theme into a block theme.

Maintenance Practices

• Store theme-controlled defaults in version control.
• Document whether administrators may edit Global Styles.
• Avoid duplicating the same rule in JSON, CSS and block attributes.
• Test editor and frontend output together.
• Review stored customizations before changing theme files.
• Use stable preset names where content references them.
• Export or document significant Site Editor changes before deployment.

Frequently Asked Questions

Is theme.json required for every theme?

No, but it is central to modern block-theme design and can also benefit classic themes.

Do Global Styles replace CSS?

No. They generate and coordinate many styles, but themes may still need CSS for behavior, unsupported properties and specialized components.

Why does my theme.json change not appear?

A user customization, block setting, cache or more specific CSS rule may override the file value.

Continue Learning

Previous: WordPress Patterns and Synced Patterns

Next: Navigation in WordPress