Gutenberg & theme.json: The Complete Guide to Global Styles

Dec 03, 2025 |

12 minutes read

Introduction to theme.json in WordPress

When WordPress introduced Gutenberg, it marked the beginning of a new era of block-based websites. Instead of relying on PHP templates and large CSS files, Gutenberg encourages a more structured, modern, and modular approach to designing full websites. But as blocks multiplied, styling them consistently across themes became a challenge. Developers needed a cleaner way to manage typography, spacing, colors, and block settings without relying on bulky stylesheets or endless customizer options.

That’s exactly why theme.json was created. Introduced in WordPress 5.8, theme.json gives theme developers a single configuration file that controls everything from global styles to block settings, spacing presets, color palettes, font sizes, and even editor behavior. It reduces CSS bloat, standardizes design across the block editor and front end, and makes themes easier to maintain and update.

In this guide, we’ll explore everything you need to know about the theme.json file, from how it works to how you can use it to create powerful, modern, block-based WordPress themes.

What is theme.json?

theme.json is a JSON-formatted configuration file placed inside the theme folder that allows you to:

Define global styles for your entire sit

Customize block-specific style

Control editor tools and option

Provide color palettes, fonts, and spacing preset

Enable or disable block feature

Reduce the need for external CSS files

Instead of writing long CSS files or using multiple style overrides, theme.json helps you manage your theme’s design in a structured, centralized way.

For block themes, it’s essential. For classic themes, it’s optional—but extremely useful.

Why theme.json Is a Game-Changer

Before theme.json, developers relied heavily on:

style.cs

editor-style.cs

Customizer setting

Block override

Inline CSS via PHP

This often led to messy, inconsistent styling.

Theme.json solves these problems by:

Providing consistency

The same styles apply to both the frontend and the block editor.

Reducing CSS

WordPress generates CSS automatically based on your settings.

Making themes more maintainable

Changing one value in theme.json updates styles globally.

Offering design control

You can restrict user options to ensure brand guidelines are maintained.

Structure of theme.json :

A typical theme.json file includes two main sections:

1. settings – Controls options available in the edito

2. styles – Controls the actual styling applied

Here’s a basic structure:

As your theme grows, these sections can become extensive, but the layout stays clean and predictable.

Global Settings You Can Control with theme.json

1. Color Palette :

You can define your own brand colors:

These colors appear as options in the editor for buttons, text, backgrounds, and block accents.

2. Typography :

Customize fonts, sizes, and weight options:

You can also restrict users from altering font sizes or line heights if needed.

3. Spacing :

Define spacing presets so your layout remains consistent:

This eliminates the guesswork of inconsistent margins and paddings.

4. Layout Controls

You can define content width and wide width settings:

This ensures blocks like images, groups, and covers align properly.

Using theme.json for Global Styles :

The styles section applies actual styling to the whole site:

These styles apply to both the front end and the editor, keeping the design fully synchronized.

Block-Specific Styles in theme.json :

One of the most powerful features is the ability to style individual blocks.

Example: Styling paragraph block:

Example: Button block custom styling:

This prevents the need for extra CSS files or selectors.

Enabling or Disabling Editor Features :

You can lock down options you don’t want users to edit.

Example: Disable custom colors:


"color": { 
 		 "custom": false 
}

Example: Disable spacing tools:


"spacing": { 
 		 "customSpacing": false 
}

This is extremely helpful for agencies and brand-focused themes that must maintain strict consistency.

How theme.json Improves Performance

Theme.json improves site speed in several ways:

Fewer CSS files: WordPress auto-generates minimal CSS for the selected styles.

Less DOM complexity: No redundant inline styles or overrides.

Optimized editor loading: The block editor loads faster because it knows exactly which tools are enabled.

Cleaner code: No large CSS files slowing down rendering.

Using theme.json in Classic Themes

Even if you’re not building a block theme, you can still use theme.json to:

Add a color palette

Define block spacing

Apply global typography

Style blocks consistently

Simply add the theme.json file to your classic theme, and WordPress handles the rest.

Gutenberg unlocks cleaner, faster WordPress theme designs

The Way Forward

The introduction of theme.json signals a major shift in WordPress theme development. It centralizes all design settings into one clean configuration file, reduces CSS overload, and creates a unified experience between the block editor and the front end. With this system, developers gain unprecedented control over global styles, block settings, palette creation, typography, and layout design, all without writing extensive CSS.

Whether you’re building a full site editing theme or enhancing a classic one, theme.json simplifies your workflow, improves performance, and ensures a consistent, scalable design system. As Gutenberg continues to evolve, theme.json will remain the backbone of modern WordPress styling, making it an essential tool for every developer aiming to create high-quality, future-proof WordPress themes.