Developing CSS custom properties with theme.json for enhanced WordPress themes

Have you ever wanted to change the colors or fonts of your WordPress theme without touching a single line of CSS? Great news — with theme.json and CSS custom properties, it’s easier than ever! Let’s explore how you can make your themes smarter, faster, and a lot more fun to customize.

Wait…what is theme.json?

Theme.json is a magic file introduced in WordPress 5.8. It allows you to define global styles and settings for your theme. Things like:

Colors
Typography
Spacing

And guess what? Those styles get turned into nice, neat CSS variables you can use in your stylesheets. This means fewer hard-coded values and more reusable style tokens. Yay!

Let’s get practical

Here’s a mini example of a theme.json file:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#3498db",
          "name": "Primary Blue"
        },
        {
          "slug": "secondary",
          "color": "#2ecc71",
          "name": "Green"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "slug": "small",
          "size": "0.875rem",
          "name": "Small"
        },
        {
          "slug": "large",
          "size": "2rem",
          "name": "Large"
        }
      ]
    }
  }
}

Once you add this file to your theme’s root directory, WordPress turns the color palette into CSS variables. You can then use them like this:

.example-box {
  background-color: var(--wp--preset--color--primary);
  font-size: var(--wp--preset--font-size--large);
}

Let your themes breathe with design tokens

Custom properties — or CSS variables — are basically names for values. They’re reusable and make your CSS cleaner and smarter.

Use them smartly! For example, define a base spacing variable in theme.json and apply it everywhere consistently.

"custom": {
  "spacing": {
    "small": "8px",
    "medium": "16px",
    "large": "32px"
  }
}

Now in your CSS:

.section {
  padding: var(--wp--custom--spacing--large);
}

Neat, right?

No more guessing in the editor

Before theme.json, using the block editor was like cooking without knowing the ingredients. You’d guess the styles and hope it all worked.

Now, with your settings defined, the editor gives you a consistent look that matches your frontend like a mirror. When you register colors and font sizes, they show up right in the block settings!

Bonus: It scales like a dream

If you’re building themes for clients or publishing multiple themes, this system is your best friend.

You only update variables in one place. Everything else updates automatically. No hunting down ten different color declarations. Just one variable to rule them all.

Let’s wrap this up

Here’s a quick recap of why CSS custom properties and theme.json are awesome: