12. Global Styles and theme.json in WordPress Block Themes – A Step-by-Step Guide with Versana Theme

In this tutorial, we’ll configure the theme.json file to apply global settings and styles to our block theme, Versana. This approach lets us define color palettes, typography, layout widths, and other design system elements directly from one file.

🔧 Step 1: What is `theme.json`?

The theme.json file is the foundation of global settings in WordPress block themes. It controls:

Style options for blocks (colors, fonts, spacing)
Editor UI behavior (which settings are enabled/disabled)
Default theme styles for the frontend

📁 File path:
/wp-content/themes/versana/theme.json

We already created a basic version in Video 1. Let’s now extend it into a full design configuration.

📘 Official theme.json Documentation →

🎨 Step 2: Add a Global Color Palette

Inside the "settings" key of your theme.json, add a custom palette:

"color": {
  "custom": false,
  "palette": [
    {
      "slug": "primary",
      "color": "#1A73E8",
      "name": "Primary"
    },
    {
      "slug": "secondary",
      "color": "#E91E63",
      "name": "Secondary"
    },
    {
      "slug": "neutral",
      "color": "#F5F5F5",
      "name": "Neutral"
    },
    {
      "slug": "contrast",
      "color": "#111111",
      "name": "Contrast"
    }
  ]
}

✅ These colors will now appear in the Block Editor’s sidebar color pickers.

🔠 Step 3: Define Typography (Font Sizes & Line Height)

"typography": {
  "customFontSize": false,
  "fontSizes": [
    { "slug": "small", "size": "14px", "name": "Small" },
    { "slug": "medium", "size": "18px", "name": "Medium" },
    { "slug": "large", "size": "24px", "name": "Large" },
    { "slug": "x-large", "size": "36px", "name": "X-Large" }
  ],
  "lineHeight": true
}

✅ You’ll now see these font sizes available when editing text blocks in the editor.

📐 Step 4: Set Layout and Content Widths

To define the layout container sizes for your theme:

"layout": {
  "contentSize": "800px",
  "wideSize": "1200px"
}

✅ This helps control max-width of blocks (like Group or Cover blocks) in both normal and wide layouts.

📏 Step 5: Enable Spacing and Padding Controls

"spacing": {
  "padding": true,
  "units": ["px", "em", "rem", "%"]
}

✅ This allows spacing controls in the block sidebar like padding, margin, and gap.

🧾 Step 6: Final theme.json Snapshot (So Far)

Here’s a simplified version of the full file structure:

{
  "version": 2,
  "settings": {
    "color": {
      "custom": false,
      "palette": [
        { "slug": "primary", "color": "#1A73E8", "name": "Primary" },
        { "slug": "secondary", "color": "#E91E63", "name": "Secondary" },
        { "slug": "neutral", "color": "#F5F5F5", "name": "Neutral" },
        { "slug": "contrast", "color": "#111111", "name": "Contrast" }
      ]
    },
    "typography": {
      "customFontSize": false,
      "fontSizes": [
        { "slug": "small", "size": "14px", "name": "Small" },
        { "slug": "medium", "size": "18px", "name": "Medium" },
        { "slug": "large", "size": "24px", "name": "Large" },
        { "slug": "x-large", "size": "36px", "name": "X-Large" }
      ],
      "lineHeight": true
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    },
    "spacing": {
      "padding": true,
      "units": ["px", "em", "rem", "%"]
    }
  }
}

📝 Don’t forget to validate your JSON using this online schema:
https://schemas.wp.org/trunk/theme.json

🧪 Step 7: Test in the Editor

Go to Pages → Add New
Insert a Paragraph, Group, or Cover block
Check:
- Are your custom colors showing?
- Are font size and spacing controls available?
- Try “Wide” or “Full” alignments for layout testing

🎉 Your Versana theme now supports a powerful design system via theme.json.

🔗 References and Tools

Global Settings and Styles – WordPress Dev Docs
theme.json Reference
theme.json Visual Generator

🔧 Step 1: What is theme.json?