← Back to Blog

Global Styles and theme.json

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

Veyra Admin

5 min read

  • Guide
  • Beginner
  • 5 minutes read
  • Reviewed August 5, 2026
  • WordPress themes and templates

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.

Applying Global Styles and theme.json in a Real WordPress Project

Separate content, presentation and permanent functionality. Test the editing workflow as well as the public output, because a theme decision affects templates, design controls, accessibility, performance and future redesign work.

A connected concept is Classic Themes vs Block Themes. Reading the two together helps separate the immediate task from the wider WordPress responsibility.

A useful implementation begins by writing down the current state, the intended outcome and the evidence that will prove the change worked. This prevents a configuration screen, plugin recommendation or code snippet from becoming the entire strategy.

A Practical Example

Imagine a team making this decision for a production WordPress site. The useful question is not only “Can WordPress do this?” but “Which layer owns it, who maintains it, what data does it affect and how will we verify it after an update?”

Write the answer in operational terms. Name the content, user, setting, file, API or service involved. Then identify what should remain true if the theme changes, a plugin is replaced or the site is migrated.

Questions to Ask

  • What user or system problem does this solve?
  • Which WordPress layer owns the behaviour?
  • What data is created or changed?
  • Who may perform the action?
  • What can fail, and how will that failure be visible?
  • How is the result tested after updates?
  • What is the migration or removal path?

Review Editor and Frontend Behaviour

A block feature has at least two user experiences: the editor used to create it and the frontend used to consume it. Dynamic data, responsive behaviour and accessibility can differ between the two.

Test insertion, selection, keyboard operation, saved markup, server rendering, theme styles and backward compatibility with previously saved content.

Official Reference Context

The Theme Handbook is the primary version-specific reference for this topic. Use the current documentation to verify interface labels, supported APIs and behaviour before applying instructions to a production site.

How to Verify the Result

  • Test representative templates on mobile and desktop.
  • Check keyboard navigation, headings, contrast and focus.
  • Switch editing contexts and confirm that the team knows where each design decision is stored.

Sources and Further Reading

Continue Learning