Default Colors, Theme Colors, and Custom Colors

[mtias]

What is the problem?

Color handling in Gutenberg comes in two forms: colors picked from a palette and custom colors. Core provides a default color palette which can be overwritten by a theme. Colors assigned to a palette are expressed through classes. The same model applies to gradients. This is issue is not about the technical aspects of when to classes, inline styles, variables, etc, are employed but about the user expectations and theme integration.

At the moment, it’s frustrating as a user that upon switching to a theme that overwrites the default color palette you lose access to the rainbow-color set that comes with core. The core palette aims to provide quick access to distinct hues reliably. A theme palette generally aims to define a restricted set of semantic colors for branding.

The heart of the issue is the conflict that arises since colors are not always used semantically but also for individual expression. A theme might have added a color palette with just two colors — a green and a black — to define its aesthetics. Now, if a user is interacting with a pattern that contains an image with a rural landscape and the green color is picked because it matches the tone of the image, that use is not semantic in the sense the user wouldn’t expect it to change if they switch themes. Gradients are even more pronounced given there’s no sense of “primary”, “secondary”, not even distinct color names and they can be a lot more decorative (the theme Seedlet is a good example, with gradients that work more as background patterns). Assembling a gradient from scratch is also more laborious.

This distinction between semantic colors and local colors has implications for theme switching, global styles, etc. So we need to expand the handling of colors.

Another problem is tying user customization to globally used colors. Right now a custom color can only be replicated by remembering and replicating its color code. There should be an easier way to transfer a local color choice into the shared palette.

Finally we have the situation of patterns, which need to set inline colors right now to ensure they work as expected. This shouldn’t be needed if the pattern wants to use a color from the default color palette.

Proposal

Separate the core palette from the theme palette

A first step is to make the theme color palette something that works in addition to the default palette. That would allow themes to register preferred colors without necessarily overwriting the default palette. Of course, it still needs to be possible to fully disable the default palette since sites that have stricter branding guidelines might prefer to remove it entirely, the same way the custom colors interface can be disabled, but it should not be the default behaviour that a theme palette overwrites the color palette.

Treat theme colors semantically

The other part is treating theme colors as colors that should change upon a theme switch. This is obvious for the global styles context, where headings or link colors set to a theme color should change when switching themes. But it can also be extended to theme colors employed locally.

There is always going to be some uncertainty in determining what the intention is when applying a local color, but by having a more clearly defined “Theme” group we can set a better expectation than what is currently the case — if I apply a theme color rather than a color from the spectrum to a button block, it’s easier to expect it to change upon theme switching.

The approach of having theme colors more clearly presented in the UI, in addition to the default color-spectrum, will allow us to finally tackle a big part of the conundrum outlined in #7553. Theme colors (of the primary and secondary kind) will be expected to map to the same variables on the next theme while dark-red and light-blue are consistently provided by core but could still be tweaked within their hue range in a still predictable way (for example, we might update the default color palette with a "vibrant" or "muted" variant of the same color-coded names).

Extending the default palette

The default palette should be user customizable (as it is now in Global Styles), so a user can add, edit, or remove from it and sustain it through theme changes. That doesn't change. It's conceivable that the current colors in the default palette would need to be added, updated, or removed in the future. We should work with the assumption that we might add more default palettes in the future and that we should retain the current mappings indefinitely.

Bubble up local changes

Colors picked locally could automatically become part of the custom user palette so that the next time they want to pick the same color it's present there. A user should be able to remove a custom color at any time so that the custom palette doesn’t grow indefinitely if you use many custom colors locally. A tricky implementation detail is how to go from inline disposable color to a class-based one for this reuse, but this also helps address that problem by making it more obvious that adding a color (at least in certain contexts) automatically creates a class mapping for it.

Integration with patterns

By ensuring the default colors are present through their class mappings patterns can reliably work with them even in cases where they might not figure out in the UI for whatever reason. This is important to support a wide range of patterns and limit the need to resort to inline styles for effects.

[aristath]

Implementing multiple palettes as described above would go a long way and improve things both for end-users and developers.
The only thing I would like to add to the above proposal is that ideally we'd also have some sort of universal naming convention for theme-defined colors.
This way the "primary" color will most likely be named primary and not mytheme-primary-dark, sothings won't break when switching themes.

[pbking]

Reading the above I imagine:

Gutenberg by default will provide a given set of styles. "Semantic" styles. These are the agreed-upon colors that will always be provided. Themes depend on it, patterns depend on it, blocks depend on it.

--wp--preset--colors--primary is always something we can depend on. This is what you mean by "core palette".

A theme can use that variable to style blocks. "Primary goes in this color, foreground goes in that color"
A theme can set those variables. Maybe even from colors in the palette it provides.
"Primary = 'golden pond'"

A user can set that value to whatever they want. When they do change that value it sticks between themes. If they change any value of the primary, etc set that it's locked in. That's their global palette. If they reset the global styles then that palette goes to whatever the theme expressed or whatever Gutenberg defaults it to if the theme doesn't express anything.

Templates and blocks can use those variables and styles in their templating. ".has-primary-color" will always be available what you (and the user) think it is.

[mtias]

@nosolosw one of the quick steps I imagine here would be to introduce a new defaultColorPalette = true property in theme.json, which themes can disable if they don't want default colors at all.

[oandregal]

one of the quick steps I imagine here would be to introduce a new defaultColorPalette = true property in theme.json, which themes can disable if they don't want default colors at all.

Thinking on UI: what do you think would be a good first step to match that change? Do we need to create separated palettes in the UI or can we start by having a long list of colors with what we have today (sorted: first core, then theme)?

The default palette should be user customizable (as it is now in Global Styles), so a user can add, edit, or remove from it and sustain it through theme changes. That doesn't change.

So, the user can change all palettes (core, theme, user). In terms of theme.json shape/keys, everything can remain the same, we just need to change behavior (don't overwrite palettes).

What are your thoughts on themes changing the color value of the color palette? For example, does it make sense that a theme can change the core yellow's value to a different sort of yellow? I'm thinking we don't need this to start, it seems to go against the spirit of this issue. If we wanted to do this, we could offer the option to only change the values but not the slug (so the generated classes still have the same names) or the UI name (so there's an incentive that themes that change the color don't do things like changing a yellow to a purple).

We should work with the assumption that we might add more default palettes in the future and that we should retain the current mappings indefinitely.

I'm thinking that we may want to cross that bridge when we get to it? Food for thought: depending on our needs, we could do different things such as allow multiple palettes per origin (multiple palettes for core, multiple for themes, etc), allow for having colors that aren't shown in the UI but still generate classes (deprecated colors, so to speak), etc.

[mtias]

Do we need to create separated palettes in the UI or can we start by having a long list of colors with what we have today (sorted: first core, then theme)?

Yes, listing one after the other is fine for now.

For example, does it make sense that a theme can change the core yellow's value to a different sort of yellow? I'm thinking we don't need this to start, it seems to go against the spirit of this issue.

Right, this is not planned to be changeable at first through themes. In the future we might unlock the values like you describe.

I'm thinking that we may want to cross that bridge when we get to it?

Agreed :)

[oandregal]

I've prepared a PR that could be a first step for this #31669

[dashkevych]

one of the quick steps I imagine here would be to introduce a new defaultColorPalette = true property in theme.json, which themes can disable if they don't want default colors at all.

This is a great idea! I was recently looking for a solution on how to add additional colors to the default colors. I am happy to hear there will be a solution to it.

I am wondering, would it be possible to add additional colors via PHP in classic themes?

Will we be able to use, for example add_theme_support( 'editor-color-palette' ); to extend default colors?

[youknowriad]

Initial version of this landed, we have a couple follow-up PRs to address some related issues but for now, I'm removing this issue from the must-have board as the UI is not expected in 5.8.

[colorful-tones]

I love where this is going! I think having colors coming from core is ideal and gives a great baseline API for theme authors to work with.

Naming variables is never easy. Leveraging a baseline set of semantic variable names and then adding a layer of aliasing on top for theme authors to override is ideal (to me).

[justintadlock]

Splitting theme and core palettes:

Yes, absolutely, yes. This will be a good thing for the block directory since we would have standard names from core that are always available.

What I'd like to see is the ability for themers to disable the UI part of core colors though while still supporting them as part of the core CSS package. Freelancers/agencies might not want clients choosing something outside of the color scheme.

Semantic theme color palette naming:

I've been working on a solution for this in the last few weeks. Here's a theme.json look at the result: https://gist.github.com/justintadlock/0003b82a1fc753b8bae54fad5b8cfd55

It is a combination of a Tailwind-like "shade" system based on the feedback from several theme designers on what they need on the average project. There are 4 groups of colors: 1) always-available, 2) neutral, 3) primary, and 4) secondary.

The shading system goes from 100, 200...900 (lightest - darkest). Using this system gives us 30 colors in total, which may be complete and utter overkill for many. An easy way to cut back on that is to skip the even shades, going from 100, 300...900. That will cut it down to 18 in total.

I also think such a shading system could have applications as we consider dark mode down the line.

Group 1: Always Available

.wp--preset--color--transparent
.wp--preset--color--black
.wp--preset--color--white

Group 2: Neutral Color

These are often text, borders, backgrounds, etc. Usually your "grays".

.wp--preset--color--neutral-100
.wp--preset--color--neutral-200
.wp--preset--color--neutral-300
.wp--preset--color--neutral-400
.wp--preset--color--neutral-500
.wp--preset--color--neutral-600
.wp--preset--color--neutral-700
.wp--preset--color--neutral-800
.wp--preset--color--neutral-900

Group 3: Primary Color

This would be the primary/brand color used throughout the site. Links, buttons, etc.

.wp--preset--color--primary-100
.wp--preset--color--primary-200
.wp--preset--color--primary-300
.wp--preset--color--primary-400
.wp--preset--color--primary-500
.wp--preset--color--primary-600
.wp--preset--color--primary-700
.wp--preset--color--primary-800
.wp--preset--color--primary-900

Group 4: Secondary Color

Often unneeded, but this is for a secondary or accent color that is separate from the primary.

.wp--preset--color--secondary-100
.wp--preset--color--secondary-200
.wp--preset--color--secondary-300
.wp--preset--color--secondary-400
.wp--preset--color--secondary-500
.wp--preset--color--secondary-600
.wp--preset--color--secondary-700
.wp--preset--color--secondary-800
.wp--preset--color--secondary-900

[colorful-tones]

Instead of having all those -100 and -800 variants. I would rather maybe see a mechanism like a stepper, slider UI that can be controlled via API. So, if a purple exists but theme developer only wants to allow for certain steps (e.g. --200, --400, --900) then it would have just those increments on slider.

[colorful-tones]

Instead of having all those -100 and -800 variants. I would rather maybe see a mechanism like a stepper, slider UI that can be controlled via API. So, if a purple exists but theme developer only wants to allow for certain steps (e.g. --200, --400, --900) then it would have just those increments on slider.

Upon second thought, the existing color picker UI would still be more suitable for this, as opposed to input type="range". Surfacing the colors as visual color is always more ideal user experience 😄

[colorful-tones]

@justintadlock @kjellr and I discussed this in #themereview the other day.

I've come to appreciate @justintadlock approach and naming convention.

I think this lays a solid foundation for theme authors to work with. Standardizing on these variable names is critical to setting up a scaffolding for themes to operate, while allowing interoperability when users switch themes.

[colorful-tones]

I've also gone ahead and put this on the radar for #core-css weekly, as we're currently having ongoing discussions about CSS Custom Property naming conventions.

Recently we've been focused on @ryelle experimental work on WP Admin color schemes with Custom Properties. Here is our single source of truth in shared Google Doc: WordPress Core CSS custom property naming

[richtabor]

A couple thoughts after diving into colors lately:

I've been playing around with the Automattic theme.json supported themes and across a few other points. BlockBase, Seedlot Blocks, and Blank Canvas all have primary, secondary, background, and foreground colors added. Quadrat does not, but perhaps it will (or should).

1. Should we consider background and foreground also standard colors that should be accounted for in block themes?

If so, it would enable patterns to do flex a bit more creatively, if for example, they used a primary color for a background, and the site background color for the foreground/text — like this:

Looks great — and can make for interesting styles. However... that only works if the primary color and background color are contrasting. In the case of BlockBase and Seedlet, the primary colors are dark, whereas the background color is white (high contrast). So naturally, swapping the two works. 🤨

2. So, should we account for light & dark colors?

Should we have --light or --dark appended to slugs to indicate a primary--dark or primary--light color? This way, a pattern could declare that it should have a dark background with light text (via the theme's color declarations) — instead of working some of the time?

And this wouldn't happen:

3. And (or instead of #2) should we have baseline mono--light and mono--dark colors?

They don't have to be white/black but variations of the like.

These may be a lot to standardize, but if we're really trying to open up flexibility between themes/patterns/block styles, I think we need to lean in this direction.

🎨

[leeshadle]

How about a required minimum default palette for themes?

Like @richtabor, I've also been doing a deep dive into handling global colors in block-based themes, here are some findings:

Global Color handling in Elementor = Sensible Defaults + Flexibility

Elementor has done an excellent job as far as handling global colors by offering both sensible defaults and lots of flexibility. In Elementor, you can easily achieve a Tailwind-esque palette as @justintadlock is proposing as well as a more semantic approach like @pbking is referring too.

The default palette naming strategy in Elementor is Primary, Secondary, Text, and Accent. The palette labels can be changed but the underlying custom properties remain the same and can't be deleted: --e-global-color-primary, --e-global-color-secondary, --e-global-color-text, --e-global-color-accent

Tailwind-esque & Semantic Global Colorl Color handling in Gutenberg

I've found myself testing both versions of these palettes in block-based themes and ultimately it comes down to the design and what colors I need.

In one site build I need multiple shades of a primary color (tailwind-esque variants), in another I need 4 distinctly different but semantically named colors:

So far I've landed here as my default for block-based themes, which also echos @richtabor's light & dark palette slugs:

Required minimum default palette for themes?

With all that being said, how about a required minimum default palette for themes that uses a standard naming convention?

• with semantically named slugs such as primary, secondary, accent
• theme builders/users can easily extend the minimum default palette
• theme/pattern/plugin builders can know that a theme is going to have a minimum default palette and its custom properties available and ready to consume
• If a theme can opt-out of the default core palette, it will ( at least I probably would ), which again becomes a problem if people are searching for patterns in the pattern directory and the theme they're using has opted out of the default core palette
• theme/pattern/plugin users can rest easy knowing their chosen colors will persist

[karmatosed]

I do like the idea of cornerstones of colours you can count on across all themes. Background and foreground make sense to me as meaningful terms. Whatever naming appending numbers seems a slippery slope, so avoiding that seems great to me.

What I find problematic actually is the use of primary/secondary and other words that tend to mean less - but that might be because I really want my theme.json right now to read like a recipe, not code. I don’t know if this is going to change for me with time and a personal feeling. Accent also feels strange to me as a term, accent to what? If we settle on some core fixed words, we have to think about translation, their comprehension, meaning and implications. All very doable as this process happens.

I really am intrigued by the light/dark append @richtabor suggested, which reminds me of the approaches in various preprocessors. I think that is also needed to get around some block and pattern issues I think anyone who has played with this for even a short while has encountered now.

[johnstonphilip]

DaisyUI has a pretty great system that includes things like focus states:

{
          'primary': '#570df8',
          'primary-focus': '#4506cb',
          'primary-content': '#ffffff',
          'secondary': '#f000b8',
          'secondary-focus': '#bd0091',
          'secondary-content': '#ffffff',
          'accent': '#37cdbe',
          'accent-focus': '#2aa79b',
          'accent-content': '#ffffff',
          'neutral': '#3d4451',
          'neutral-focus': '#2a2e37',
          'neutral-content': '#ffffff',
          'base-100': '#ffffff',
          'base-200': '#f9fafb',
          'base-300': '#d1d5db',
          'base-content': '#1f2937',
          'info': '#2094f3',
          'success': '#009485',
          'warning': '#ff9900',
          'error': '#ff5724'
}

https://daisyui.com/core/colors/

[overclokk]

I think now it's too late to create a good pattern for color names.

2022 theme is in place, all developer will use the pattern used in that theme as default now, you can only create your own using custom preset and not with regular preset.

[skysarwer]

Can we revive this thread? I think it's really odd that there is no option for theme developers to cleanly opt-out of having the default color palette rendered on the frontend.

I understand that "some plugins might use these variables" -- but that is a weak excuse to not have an opt-out option.

There are SO many websites that do not need "vivid-luminous-orange" and "vivid-luminous-amber" -- to state just the tip of the iceberg here.

Sorry for the strongly stated opinion, but this convo has been ongoing for over 3 years and decision makers seem to be missing the forest for the trees here.

[naumanahmed19]

is this possible to get color style with hex instead of slug in markup? it will make it more consistent for API building each theme has its own naming conventions.

<!-- wp:paragraph {"style":{"color":{"text":"#cf2b2b"}}} -->

<!-- wp:paragraph {"textColor":"vivid-red"} -->

[daviedR]

Reviving this thread...

---

I think we already have color naming standards as mentioned in the Developer Handbook (https://developer.wordpress.org/themes/advanced-topics/theme-json/#color-palette).

Themes should use at least 2 colors:

• base
• contrast

And then more colors could be added using the sequential color slugs, just like what TwentyTwentyThree theme does:

• primary
• secondary
• tertiary
• ... and so on ...

---

Possible Issues

There are cases in designs, we need more than 1 contrast color or more than 1 base color.

Here are a few examples:

1. The page body has a white background color, while the footer area has a subtle gray background color.
2. For text colors, designers might use different colors for the heading and body text, or even use 3rd color for small meta text.

We could have assigned the alternative colors to one of the sequential slugs.
For example:

• the subtle gray color is assigned to the tertiary slug.
• heading text color is assigned to the quarternary slug.

But some theme designers might assign the opposite. tertiary is for the heading text color and quarternary is for the subtle gray background.

This might cause consistency issues when switching between themes.

Any thought on this?

[erikjoling]

I'm using base, contrast, primary, secondary [...] for color naming as well. For subtle color differences I use derived names, like base-x or primary-2.

So if I have a base color of white, I use base-2 (or base-x) for a light shade of gray.

[timnicholson]

I've been following this thread and have taken a look at what color naming the new TwentyTwentyFour theme is going to use and it looks to me from earlier commits that they started out with base, contrast, primary, secondary, tertiary but then started converting them over to the following. I thought we were at least standardized on primary, secondary, tertiary and then could debate background/foreground vs. base/contrast. Now we are looking at shades of base and contrast and various "accent" colors.

			"palette": [
				{
					"color": "#f9f9f9",
					"name": "Base",
					"slug": "base"
				},
				{
					"color": "#ffffff",
					"name": "Base / Two",
					"slug": "base-2"
				},
				{
					"color": "#00000025",
					"name": "Base / Three",
					"slug": "base-3"
				},
				{
					"color": "#111111",
					"name": "Contrast",
					"slug": "contrast"
				},
				{
					"color": "#636363",
					"name": "Contrast / Two",
					"slug": "contrast-2"
				},
				{
					"color": "#A4A4A4",
					"name": "Contrast / Three",
					"slug": "contrast-3"
				},
				{
					"color": "#cfcabe",
					"name": "Accent",
					"slug": "accent"
				},
				{
					"color": "#c2a990",
					"name": "Accent / Two",
					"slug": "accent-2"
				},
				{
					"color": "#d8613c",
					"name": "Accent / Three",
					"slug": "accent-3"
				},
				{
					"color": "#b1c5a4",
					"name": "Accent / Four",
					"slug": "accent-4"
				},
				{
					"color": "#b5bdbc",
					"name": "Accent / Five",
					"slug": "accent-5"
				}
			]

I also think that core WordPress shouldn't have used such unique color names. I assume they were purposely trying to NOT conflict with names that a theme might use. However, I think it would have been better to have more generic names to set the standards for themes to ADJUST those colors and add their own. So perhaps some basic colors, like red, orange, yellow, green, blue, and then maybe some like dark, light, and neutral.

For the FSE theme I just published, Flat Blocks, I'm using background and foreground, primary, secondary, and tertiary, but also neutral and dark as well as "alt" versions of most of those that are a darker shade of those colors.

[karmatosed]

@luminuu or @MaggieCabrera do you have some perspective you could give on how Twenty Twenty Four?

[richtabor]

The way I proposed colors for Twenty Twenty Four (WordPress/twentytwentyfour#106) is to provide variants of base, contrast and accent. These represented as base-2, contrast-2, accent, accent-2, accent-3, etc.

Key concepts:

• Uses numeral values, instead of primary/secondary/tertiary/etc, as those are indicative of priority, instead of alternatives.
• Uses "$colorType / $variant" structure for naming colors, instead of actual color representation. Example: "Accent / Three" instead of "Red". This way users can edit the color in Global Styles and it won't always render the color title as "Red". The / $variant notation helps attribute this color as an intended alternate.

This affords an approach like proposed #53996 for even better theme interoperability than simply matching slugs, as it wouldn't matter what the slug terms are—and colors could fallback, just like how spacing presets do. This comment explains the fallback concept well.

We're not at a point where themes can 1:1 switch and expect no color conflicts with existing content.

If your accent-4 (or quaternary) is a dark value, but your base-2 (or base-secondary) is also dark — there is nothing to catch those instances.

As Gutenberg leans in on section specific theme.json (colorways if you would) then a theme could define color/style combinations. Those would all have core-defined slugs (say colorway-1, colorway-2, etc) and colorway-2 would map to whatever your theme provided, if it provided one.

At that point color slug standardization isn't needed at all, but the fallback mechanism above would still work nicely.

[justintadlock]

I've been following this thread and have taken a look at what color naming the new TwentyTwentyFour theme is going to use and it looks to me from earlier commits that they started out with base, contrast, primary, secondary, tertiary but then started converting them over to the following. I thought we were at least standardized on primary, secondary, tertiary and then could debate background/foreground vs. base/contrast. Now we are looking at shades of base and contrast and various "accent" colors.

The only slugs that have become sort of standardized are base and contrast. Look at them as a best practice until a better system is implemented. More info on that here:

• Use "background" and "foreground" color slugs instead of "base" and "contrast" for consistency and compatibility twentytwentythree#36
• Theme handbook: color naming best practices Documentation-Issue-Tracker#563

[richtabor]

The only slugs that have become sort of standardized are base and contrast.

And perhaps eventually those could be ref values, from the actual background/color values from the styles.color.background and styles.color.text top-level values.

You wouldn't need to register base/contrast in the color palette, dropping the need to standardize those as well.

[MaggieCabrera]

I think Rich's concept in #53996 makes a lot of sense. TT4 has a wider palette range than TT2 or TT3 did and there's no consensus on how to handle that from core. I'm happy that it's helping get fire under this discussion so we finally move towards a global solution in the editor.