How to add a style variation to a WordPress block theme

Style variations let a block theme come in more than one look. They show up under “Styles” in the Site Editor as a row of previews, and with one click, users can switch the colors, fonts and spacing of the whole site without touching any code.

For theme developers, they’re a cheap way to make one theme go a lot further. A style variation is just a JSON file with the values you want to change, so a dark mode or a version with different fonts can be a few dozen lines. That simplicity is what makes it possible to ship a lot of them: my theme Oaknut comes with 23 style variations, counting the default one, and since each one is a short file that only holds what makes it different, adding another doesn’t make the others any harder to maintain.

In this tutorial, we’ll take a look at how to add a style variation to a theme, and how to add color palettes and font pairings that users can mix and match. We’ll use Twenty Twenty-Five, the default theme in WordPress, as an example. It comes with eight style variations of its own, and the code examples below use its color names, so you can try them out as they are and build on them with personal touches of your own.

Creating a style variation

Style variations live in a folder called styles in the root of your theme. Each JSON file in it is one variation, and it uses the same format as theme.json. The difference is that you only include the values you want to change. WordPress merges the variation with your theme’s theme.json, so everything you leave out stays the same.

Twenty Twenty-Five already has a few dark variations, so let’s make something it doesn’t have: a high contrast version. If we added the file to Twenty Twenty-Five directly, it would be lost the next time the theme is updated, so we’ll put it in a child theme instead. If you’re building your own theme, add it to your theme’s folder. Create a styles folder in the child theme, and add a file called high-contrast.json to it:

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "High Contrast",
"settings": {
"color": {
"palette": [
{ "slug": "base", "color": "#FFFFFF", "name": "Base" },
{ "slug": "contrast", "color": "#000000", "name": "Contrast" },
{ "slug": "accent-1", "color": "#FFEE58", "name": "Accent 1" },
{ "slug": "accent-2", "color": "#F6CFF4", "name": "Accent 2" },
{ "slug": "accent-3", "color": "#2E1F80", "name": "Accent 3" },
{ "slug": "accent-4", "color": "#404040", "name": "Accent 4" },
{ "slug": "accent-5", "color": "#F2F2F2", "name": "Accent 5" },
{ "slug": "accent-6", "color": "color-mix(in srgb, currentColor 40%, transparent)", "name": "Accent 6" }
]
}
},
"styles": {
"typography": {
"fontWeight": "400"
},
"elements": {
"heading": {
"typography": {
"fontWeight": "600"
}
}
}
}
}

The palette makes the text pure black, and darkens the gray Twenty Twenty-Five uses for dates and other secondary text. Under styles, the body text goes from weight 300 to 400, and headings from 400 to 600, since thin text can be hard to read even when the color contrast is good.

The title is the name users see in the Site Editor. If you leave it out, WordPress uses the file name instead. I like to have a bit of fun with these in my free themes. The blog theme Beaumont is named after Thaddeus Beaumont, the main character in the Stephen King book The Dark Half, and the style variations continue on that theme with names like Pennywise, The Overlook and George Stark (the titular dark half in The Dark Half, and the dark style variation in the theme).

The palette uses the same slugs as the colors in Twenty Twenty-Five’s theme.json, from base and contrast to accent-6, but with new values. Since the rest of the theme refers to the colors by slug, everything that uses them switches over without any further changes. That’s why it’s a good idea to name colors by their role rather than their value. A color called white gets awkward fast in a palette like the one below, where the background is mustard yellow.

There’s one exception to only including what changes: lists like the color palette and font sizes are replaced as a whole, not merged item by item. Twenty Twenty-Five has eight colors, so if the variation only listed base and contrast, the six accent colors would be gone when it’s active. So include every color in the palette, even the ones that stay the same.

To try it out, go to “Appearance” → “Editor” → “Styles”, and click “Browse styles”. The new variation is listed next to “Default”, and clicking it previews it on the right. Click “Save” to make it active.

Adding color palettes and font pairings

Not every variation has to change the whole design. If a file only contains colors, WordPress lists it as a color palette instead, under “Colors” → “Palette” and further down in “Browse styles”. If it only contains typography, it’s listed as a font pairing under “Typography”. Users can then combine them freely: one palette with another pairing, on top of any of the full variations.

The snow has just made its late arrival as I’m writing this in the Swedish mountains, but before that, we had a month of unusually deep fall colors. Here’s a fall palette with two strong colors, mustard yellow and deep burgundy, in styles/fall.json:

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Fall",
"settings": {
"color": {
"palette": [
{ "slug": "base", "color": "#E0A033", "name": "Base" },
{ "slug": "contrast", "color": "#5E1F1F", "name": "Contrast" },
{ "slug": "accent-1", "color": "#F2EBE0", "name": "Accent 1" },
{ "slug": "accent-2", "color": "#B85829", "name": "Accent 2" },
{ "slug": "accent-3", "color": "#3D5A3A", "name": "Accent 3" },
{ "slug": "accent-4", "color": "#6A2E1E", "name": "Accent 4" },
{ "slug": "accent-5", "color": "#E8B24F", "name": "Accent 5" },
{ "slug": "accent-6", "color": "color-mix(in srgb, currentColor 20%, transparent)", "name": "Accent 6" }
]
}
}
}

WordPress decides what each file is based on what’s in it. A file that only changes colors is listed as a palette, and one that only changes typography is listed as a font pairing. That’s why the High Contrast variation above also changes the font weights: with just the new colors, it would show up among the palettes instead of as a style variation.

If you end up with a lot of files, you can organize them in subfolders of styles, like Twenty Twenty-Five does with colors and typography. WordPress reads those too, so it’s purely a matter of keeping things tidy.

Font pairings work the same way, with settings.typography and styles.typography instead of colors. If they use fonts that aren’t in your theme.json, register them in the pairing’s own fontFamilies, like I describe in how to add a variable font in theme.json.

Things to keep in mind

When someone picks a style variation, WordPress copies its values into the site’s own styles, the same place changes made under “Styles” are saved. That has a few consequences:

  • Picking a variation replaces earlier style changes. If you’ve adjusted colors or spacing under “Styles” and then switch to a variation, those adjustments are gone. Additional CSS is the exception, and stays, both for the whole site and for individual blocks.
  • Updating a variation doesn’t update sites that already use it. Since the values were copied when the variation was picked, changes to the file in a later theme update won’t show up until the user picks the variation again.
  • Child themes inherit the parent theme’s variations. If you add a file with the same name to the child theme’s styles folder, it replaces the parent’s version.