WordPress theme.json Colour Palettes and Style Variations

A colour swatch in the WordPress editor can come from WordPress itself, the active block theme, a style variation, or a change saved in the Site Editor. When a swatch looks wrong, first establish which of those layers supplied it. Changing a CSS rule before checking the selected style can hide the cause and make the next edit harder to understand.

This guide explains how to define a theme palette, offer an alternative through a style variation, and test the result in the editor and on the public site. The example uses three colours with roles rather than arbitrary labels, so the same test can be repeated after a design change.

Identify the palette you are editing

WordPress has default colour presets. A block theme can also register presets in the settings.color.palette section of its root theme.json file. Each entry has a colour value, a visible name, and a slug. The name helps an editor choose a colour; the slug identifies the preset in generated classes and CSS custom properties.

The settings.color.defaultPalette option controls whether users can select WordPress's default presets. Setting it to false removes those swatches from the selection controls, but does not remove their CSS custom properties. Existing content may still depend on them. The Theme Handbook’s colour settings guide explains that distinction. Check this setting before assuming every visible swatch comes from the theme.

A style variation is a named JSON file in a block theme's styles directory. It can provide different palette values without becoming a separate theme. WordPress stores the selected variation's data as a site customisation, according to the Theme Handbook’s style-variation guide. If you revise a variation file after selecting it on a site, select the variation again when testing the revised values.

Saved changes made through Styles add another layer. An editor can change a colour after selecting a variation, and that saved choice may take priority over the file. A mismatch between a variation file and a swatch therefore does not by itself show that the file was ignored.

Check which layer takes priority

WordPress describes a hierarchy of core settings, theme settings, child-theme settings where a child theme is active, and saved user configuration. A selected style variation sits with saved configuration because its data is stored when selected. Use the documented settings and styles hierarchy to trace an unexpected value:

Confirm the active theme. Read its root theme.json palette. If a child theme is active, inspect that file too rather than assuming the parent supplies the final value.
Record the selected style variation. Compare its palette entries with the baseline theme palette, matching presets by slug.
Inspect saved Styles changes. Check whether the site has a later colour choice that differs from the variation file.
Inspect the affected block. A colour assigned directly to one block can explain why it differs from an otherwise correct global palette.

Keep these checks separate. A palette defines available presets; it does not guarantee that every element uses one. A link or button may have another setting, while a block with an explicit colour can retain its own appearance. Test an unmodified block as well as one assigned a named preset.

Define a small palette and variation

For a controlled experiment, give the root theme.json file three palette entries under settings.color.palette. Name them Canvas, Text, and Accent, with the corresponding slugs canvas, text, and accent. Canvas describes a surface, Text the main reading colour, and Accent a deliberate point of emphasis. Choose colour values that remain readable together. The exact values are less useful than stable roles and a clear record of what each value is meant to do.

If the test should offer only the theme's swatches for new selections, set settings.color.defaultPalette to false. That setting leaves the theme palette available. It also does not erase uses of core presets already stored in content, so inspect an existing page rather than relying only on the picker.

Next, add a named JSON file such as styles/warm.json. Give it a readable title and a settings.color.palette containing new values for Canvas, Text, and Accent. Keep the same three slugs. This makes the comparison straightforward: each role should show the new value after the variation is selected. Changing a slug at the same time would also change the preset's identity, making it harder to tell whether a problem comes from the value or the reference to it.

For this first test, keep the variation focused on the palette. Style variations can change other settings and styles, but changing several things at once makes a colour problem difficult to locate. The Styles overview describes how WordPress presents available variations in the Site Editor, including colour-only variations when a theme provides them.

Run the test in the editor and on the site

Use a local or staging copy of the block theme. Before changing anything, record the active theme, whether a child theme is active, the selected variation, and any colour changes already saved in Styles. Make a test page with a heading, paragraph, link, button, one block assigned the Accent preset, and one block without an assigned colour. The uncoloured block helps reveal what the surrounding styles supply.

Establish the baseline. Open Appearance, then Editor and Styles. Note the available swatches and the values shown for Canvas, Text, and Accent. Check the test page in the editor and on the public front end.
Select the variation. Choose Warm and save. Reopen the colour controls. Confirm that the same three named presets show the intended new values.
Check assigned content. Compare the block using Accent in the editor and on the public page. Check the heading, link, button, and uncoloured block for readability, but do not assume all of them must change merely because Accent changed.
Test a saved adjustment. Change one colour through Styles, save, and reopen the editor. Record which value persists. This separates a saved site choice from the values in the variation file.
Switch away and back. Select the theme's default style, inspect the palette, then select Warm again. Recheck the public page after each save, especially if you have since revised the variation file.

Change one condition at a time. Editing the JSON file, adjusting Styles, and recolouring individual blocks in the same pass leaves no clear explanation for a mismatch. A test site with a known saved Styles state is easier to interpret than one with several undocumented edits.

Decide whether the palette works

A matching picker is only the first check. Review the public page at a narrow and a wide width, reload it without the editor open, and inspect every colour role in context. Read text against its background. Check that links and buttons remain recognisable and that their interactive states are distinguishable. Look at a block that uses Accent and one that inherits its appearance. A swatch can be correct while a template or block still uses a different colour.

If one element stays unchanged, find out how that element gets its colour before treating the variation as broken. If the editor and public page disagree, compare the selected variation, saved Styles values, and any colour set directly on the block. Record the layer responsible for the final value. That record gives the next editor a useful starting point when the palette changes again.