---
title: Standardizing theme.json color slugs
description: 'Standardizing key entries in WordPress’s theme.json can create interchangeable themes that maintain unique styles. Discover the benefits of this approach.'
doc_version: current
last_updated: '2026-04-03T10:29:03.000Z'
date: '2021-08-30T07:43:30.000Z'
author: Rich Tabor
summary: 'Standardizing key entries in WordPress’s theme.json can create interchangeable themes that maintain unique styles. Discover the benefits of this approach.'
tags:
  - Design
  - Gutenberg
  - Themes
  - WordPress
published: true
type: blog
url: /standardizing-theme-json-colors
canonical: https://richtabor.com/standardizing-theme-json-colors
id: 1247
---

**This is part one**, of three, in a series on standardizing how we build this next generation of WordPress block themes to accompany the [Full Site Editing](/full-site-editing/) effort. If you like this, read on about [standardizing font sizes](/?p=1254), and [standardizing site spacing](/?p=1256). Each of these are what I would consider design foundations of a website, of which should be functionally standardized.

I know —you’re probably thinking that by standardizing anything theme related, we’ll have unoriginal WordPress themes that lack creativity… but what if I told you that standardization would do just the opposite, and more.

By standardizing just a few key high-level entries within a WordPress theme’s theme.json file, we can finally create a class of themes that truly are interchangeable. Interchangeable in _function_, while remaining distinct in _style_. In particular, I’m referring to colors, font sizes, & site spacing — the design system components that every site leverages, theme.json based, or not. Let’s start making themes that act more like themes. So here’s my take on why this is important, and how we can get there.

## Theme color palettes generated from theme.json

When a background color is applied to a block, a `.has-{property}-background-color` class is added. Applying a text color works exactly the same way, but instead using the auto-generated `.has-{property}-color` class. Within WordPress block themes, these colors are added using the theme.json file, within the `settings.color.palette` object, like this:

```
{
"settings": {
     "color": {
	"palette": [
		{
			"slug": "primary",
			"color": "#36C5F0",
			"name": "Primary"
		},
		{
			"slug": "secondary",
			"color": "#2EB67D",
			"name": "Secondary"
		},
		{
			"slug": "base",
			"color": "#fff",
			"name": "Base"
		},
		{
			"slug": "contrast",
			"color": "#000",
			"name": "Contrast"
		}
	]
    },
}
}
```

The [theme.json resolver](https://developer.wordpress.org/reference/files/wp-includes/class-wp-theme-json-resolver.php/) creates the CSS classes with the appropriate value, along with the necessary custom properties to load within the block editor and on the front-end. The output looks of the above would look like this:

```
body {
  --wp--preset--color--primary: #36C5F0;
  --wp--preset--color--secondary: #2EB67D;
  --wp--preset--color--base: #fff;
  --wp--preset--color--contrast: #000;
}

.has-primary-background-color {
    background-color: var(--wp--preset--color--primary) !important;
}

.has-primary-color {
   color: var(--wp--preset--color--primary) !important;
}

.has-secondary-background-color {
    background-color: var(--wp--preset--color--secondary) !important;
}

.has-secondary-color {
   color: var(--wp--preset--color--secondary) !important;
}

.has-base-background-color {
    background-color: var(--wp--preset--color--base) !important;
}

.has-base-color {
   color: var(--wp--preset--color--base) !important;
}

.has-contrast-background-color {
    background-color: var(--wp--preset--color--contrast) !important;
}

.has-contrast-color {
   color: var(--wp--preset--color--contrast) !important;
}
```

This is great — as now themes don’t have to [manually declare a set of CSS classes](/gutenberg-color-palettes/) to cover colors. However, there is one caveat. If you switch to a different block theme, these s_pecific_ color classes are no longer generated — leaving nothing in their place. This means that anywhere you’ve used the `primary` color will result in no color at all — if the `primary` color does not exist within the incoming theme. Not a fantastic experience. In fact — it’s kind of destructive.

Blocks themes don’t have to be built this way. As theme developers, we should encourage the democratization of publishing… even if that means making it easy for folks to switch away from your products.

## Standard color slugs in theme.json

Just because all block themes should register at least `base`, `contrast` and perhaps `primary` colors, does not mean that every theme will have black text, a white background, and a blue accent color.

That saying, here are the `settings.colors.palette` slugs that I propose should be included in every block theme:

-   `base`
-   `contrast`
-   `primary` _(if the theme uses any other color)_

The \`base\` color is appropriately the site’s background color. This makes it easy to manipulate within the theme.json file, as well as the upcoming Global Styles interface.

The foreground color is the base color of elements applied to the page. I’d include all headings, text, list items, captions, etc — as realistically, this value could be the fallback color for just about anything. Again, this empowers the user within Global Styles, as now all text elements may be modified quickly.

And last, the `primary` is the block theme’s first accent color. And if a theme wants to add more colors, those should be registered sequentially, just like how the [Clove theme](https://github.com/anarieldesign/clove/blob/main/theme.json#L11-L33) does.

### Sequential accent color slugs

Let’s take a deeper look at the [Clove](https://wordpress.org/themes/clove/) and [Naledi](https://wordpress.org/themes/naledi) themes. If I activate Clove, create a page with blocks, and style using the theme’s standardized color palette (_which uses sequential accent color slugs_) I can then switch to another theme that uses the same standardized format — and all the colors properly map to the new theme’s color palette, like this:

![](https://i0.wp.com/rich.blog/wp-content/uploads/2023/01/686de-left.jpg?ssl=1&resize=1112%2C1052)

![](https://i0.wp.com/rich.blog/wp-content/uploads/2023/01/3e999-right-.jpg?ssl=1&resize=1112%2C1052)

In the image above, I am using the `tertiary` color for the pattern background and the `primary` color for the border around the Image block. Those colors are accurately reflected in both themes, as I switch between them. Nice. Now if had two themes that did not support a method of standardization between color slugs, this is what I’d end up with, now switching from Clove, to the [TT1 Blocks](https://wordpress.org/themes/tt1-blocks/) theme:

![](https://i0.wp.com/rich.blog/wp-content/uploads/2023/01/686de-left.jpg?ssl=1&resize=1112%2C1052)

![](https://i0.wp.com/rich.blog/wp-content/uploads/2023/01/123e9-mask-group.jpg?ssl=1&resize=1112%2C1052)

Right off you’ll notice how the `tertiary` color I applied to the pattern’s top-level Group block is missing, and the `primary` accent color applied to the Image block’s border is also gone. Not so nice anymore. I hope this illustrates how standardization helps the user. And sure, I understand that not every theme will include three accent colors — but systematizing `base`, `contrast`, and `primary` slugs across block themes would certainly be a massive step in the right direction.

## So why not use specific color slugs?

I’ve noticed that most block themes are rooting for slugs that are tied to a specific color — think `green` for a theme’s accent color that is perhaps a fun shade of lime green. The downside here is that in a world of Global Style, that color value — which was hard-coded as `green` — may easily be modified into _any_ other color. Block themes are not the end-all-be-all when it comes to design — the user is.

![Modifying a theme's color within the Gutenberg Global Styles interface](https://i0.wp.com/rich.blog/wp-content/uploads/2023/01/4354d-gs.png?ssl=1&resize=1753%2C1081)

_Modifying a theme’s color within the Gutenberg Global Styles interface_

In this most likely scenario, the `green` color slug is now irrelevant, and the class generated from the slug is no longer appropriate — in fact, it’s misleading. The class insists the color applied is green in nature, with the `.has-green-color` class, but the value may actually be any other color that the user has chosen.

## What do you think?

And as we continue to move towards more block and pattern-based site building, we should encourage themes to act more as a coat of paint, not a system of locked-in design components. Moving the theme.json `settings.colors.palette` object to use a standardized system of entries will support that effort and push us one step closer towards a friendlier WordPress theme ecosystem. If you’re interested, there’s [an issue on GitHub](https://github.com/WordPress/gutenberg/issues/29568) that reflects much of this thinking, as a potential direction to head towards. Consider adding your voice to the mix whether you agree or not, your opinion matters.

_If you like this article on colors, read the others in this standardization series covering [font sizes](/?p=1254) and [site spacing](/?p=1256)_.

## Sitemap

[Full site index](/sitemap.md)