theme.json: Global Styles and Settings

The theme.json file revolutionizes WordPress theme development by centralizing design system configuration in a single, structured JSON file. This powerful configuration layer controls global styles, design presets, and editor settings, creating consistent design tokens that cascade throughout your entire block theme.

The Purpose and Power of theme.json

Before theme.json, WordPress themes scattered styling across multiple files: CSS stylesheets, PHP template files, functions.php hooks, and Customizer configurations. This fragmentation made maintaining consistent design systems challenging and required extensive coding knowledge for simple design changes. The theme.json specification unifies these concerns into a declarative configuration file that both humans and WordPress can read and understand.

Theme.json serves three primary purposes: defining global style presets like color palettes and typography scales, configuring which editor features are available to users, and setting default styles for blocks and elements. This separation of concerns between configuration and implementation creates cleaner, more maintainable themes while enabling visual editing through the Global Styles interface.

Schema Structure and Versioning

Theme.json files begin with a version declaration that indicates which schema specification the file follows. The current version is 2, declared with "version": 2 at the root level. This versioning allows WordPress to maintain backward compatibility while evolving the schema to support new features.

The root object contains three main sections: “settings” controls what options are available in the editor and defines design presets, “styles” applies default styling to elements and blocks, and “customTemplates” registers custom template types. Additional top-level properties include “templateParts” for defining template part areas and “patterns” for registering pattern categories.

Settings: Defining Your Design System

The settings section establishes your design system’s foundation. Color settings define palettes, gradients, and duotone filters that appear in color pickers throughout the editor. A color palette entry includes a name, slug, and color value: {"name": "Primary", "slug": "primary", "color": "#007cba"}. WordPress automatically generates CSS custom properties from these definitions.

Typography settings control font families, font sizes, line heights, and letter spacing presets. Font family definitions can reference system fonts, Google Fonts, or custom font files. Font size presets create a typographic scale: {"name": "Small", "slug": "small", "size": "14px"}. These presets appear in editor controls, encouraging consistent typography choices.

Spacing settings define padding and margin presets using the spacingScale object or explicit spacingSizes array. A spacing scale generates consistent increments: "spacingScale": {"steps": 5, "unit": "rem"} creates five preset sizes. Custom spacing sizes provide precise control: {"name": "Medium", "slug": "medium", "size": "2rem"}.

Layout Configuration

Layout settings control content width and spacing behavior. The contentSize setting defines the default content width for narrow content: "contentSize": "640px". The wideSize setting specifies the width for wide-aligned blocks: "wideSize": "1200px". These values establish consistent layout boundaries across your site.

You can disable specific layout features using boolean flags. Set "appearanceTools": false to hide advanced styling panels, reducing interface complexity for less technical users. Individual feature flags like "border": false or "color.custom": false provide granular control over available customization options.

Block-Level Settings

Settings can be scoped to specific blocks using the blocks object. Define block-specific settings under "settings": {"blocks": {"core/button": {...}}}. This allows different features for different blocks—perhaps buttons get custom colors but headings use only preset colors to maintain consistency.

Block-level settings override global settings for that specific block type. You might allow custom font sizes globally but restrict headings to preset sizes only: "blocks": {"core/heading": {"typography": {"customFontSize": false}}}. This selective restriction maintains design integrity while providing flexibility where appropriate.

Styles: Applying Default Styling

The styles section sets default styling values applied throughout your site. Top-level style properties affect all elements: "styles": {"color": {"background": "#ffffff", "text": "#000000"}} sets default background and text colors. Typography styles define default font families, sizes, and spacing.

Element-level styles target HTML elements directly. Under "styles": {"elements": {...}}, you can style links, headings, buttons, and more: "link": {"color": {"text": "var(--wp--preset--color--primary)"}}. These styles use CSS custom properties generated from your settings presets, maintaining consistency.

Block styles work similarly but target specific block types: "styles": {"blocks": {"core/heading": {"typography": {"fontWeight": "700"}}}}. You can style blocks at different heading levels: "core/heading": {"variations": {"h1": {"typography": {"fontSize": "var(--wp--preset--font-size--x-large)"}}}}.

CSS Custom Properties and Presets

WordPress automatically generates CSS custom properties from theme.json presets. A color preset with slug “primary” becomes --wp--preset--color--primary. Reference these custom properties in your styles: "color": {"text": "var(--wp--preset--color--primary)"}. This creates a design token system where changing preset values updates all references automatically.

The naming convention follows a pattern: --wp--preset--{type}--{slug}. Font sizes become --wp--preset--font-size--{slug}, spacing presets become --wp--preset--spacing--{slug}. This systematic approach makes styles predictable and maintainable while enabling programmatic style generation.

Advanced Features and Techniques

Theme.json supports advanced features like custom block style variations. Register variations under "styles": {"blocks": {"core/button": {"variations": {"outline": {...}}}}}. These variations appear in the block style picker, letting users switch between pre-defined styling options.

You can define custom CSS using the “custom” property: "settings": {"custom": {"baseSize": "16px"}}. Access these custom values in styles as var(--wp--custom--base-size). This mechanism lets you define arbitrary design tokens beyond the standard preset types.

Template part areas are declared in theme.json: "templateParts": [{"name": "header", "title": "Header", "area": "header"}]. This registration makes template parts discoverable in the Site Editor with proper categorization and labeling.

Style Variations Through theme.json

Create complete theme style variations by placing additional JSON files in your theme’s /styles directory. Each file contains a subset of theme.json focusing on the styles section. Users can switch between these variations from the Global Styles interface, instantly transforming their site’s appearance.

A dark mode variation might override color presets and default colors. A minimal variation might adjust typography and spacing. These variations share the same settings and structural configuration while providing different aesthetic presentations, enabling multiple design options within a single theme package.

Performance and Best Practices

Theme.json generates optimized CSS automatically, loading only styles needed for blocks in use. This reduces payload size compared to monolithic stylesheets. Define semantic preset names that communicate purpose: “primary”, “secondary”, “base”, rather than color-specific names like “blue” or “red”. This enables design changes without breaking naming semantics.

Keep your theme.json organized and well-commented (in documentation, as JSON doesn’t support comments). Consider breaking complex configurations into logical sections mentally even though they’re in one file. Validate your theme.json against the schema to catch errors early—several online validators and editor plugins can help.

Use preset values consistently in your styles section rather than hardcoding values. This ensures changes to presets propagate throughout your styling. Test your theme.json with different Global Styles customizations to ensure preset inheritance works as expected. Version control your theme.json carefully, as it’s central to your theme’s design system.

Mastering theme.json is essential for modern WordPress theme development. This configuration file embodies the design system approach, creating maintainable, consistent, and user-customizable themes. As WordPress continues evolving toward full site editing, theme.json becomes increasingly powerful, making it a critical skill for theme developers building for WordPress’s future.