Understanding theme.json: A Guide for Devs Who Hate CSS Bloat

If you’ve ever opened a WordPress theme’s style.css and been overwhelmed by hundreds of lines of utility classes, duplicate rules, and overly specific selectors — you’re not alone. Good news: with theme.json, we can finally ditch much of that bloat and manage design from a single, centralized place.

Whether you build custom block themes or tweak existing ones, understanding theme.json is key to writing less CSS, faster.

🚀 What is theme.json?

theme.json is a configuration file introduced in WordPress 5.8 that allows you to define theme styles, block support, and editor settings using structured JSON instead of traditional CSS or PHP functions.

• ✅ Set global colors, typography, layout, and spacing
• ✅ Control block support (like font sizes, drop cap, padding, etc.)
• ✅ Apply consistent design tokens across the block editor and frontend

🛠 Sample theme.json

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "name": "Primary", "slug": "primary", "color": "#1a73e8" },
        { "name": "Accent", "slug": "accent", "color": "#ff4081" }
      ]
    },
    "typography": {
      "fontFamilies": [
        { "name": "Raleway", "slug": "heading", "fontFamily": "Raleway, sans-serif" },
        { "name": "Roboto", "slug": "body", "fontFamily": "Roboto, sans-serif" }
      ],
      "fluid": true
    },
    "spacing": {
      "units": ["px", "em", "rem"]
    }
  },
  "styles": {
    "elements": {
      "h1": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--heading)",
          "fontWeight": "700"
        }
      },
      "body": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--body)"
        }
      }
    }
  }
}

💡 Why Use It?

• Less CSS: Define styles once and apply them everywhere.
• Editor parity: What you see in the editor is what you get on the frontend.
• Cleaner codebase: Move design decisions from scattered stylesheets to structured config.
• Performance: Fewer custom classes = smaller CSS payload.

⚙️ Pro Tips

• Use a code editor with JSON schema support — it’ll auto-suggest properties.
• Pair with theme.json viewers like jsonformatter.org for better formatting.
• If using Frost or WP Rig, start by customizing their base theme.json — they’re already well structured.

📦 Bonus: Combine with Patterns

theme.json shines even more when paired with block patterns. Define your styles globally, then reuse them with consistent design tokens across all patterns.

🎯 Final Thoughts

theme.json isn’t just a trend — it’s the future of WordPress theming. The more you lean into it, the less repetitive code you’ll write, and the more predictable your styling will be.

Have a favorite tip or setup using theme.json? Hit me up — I’d love to hear how others are using it in the wild.