Theme handbook: color naming best practices

[mikachan]

What is the new page you are requesting?

It may not require an entirely new page, but it would be great to include a section which encourages the use of a standardized naming convention for theme colors.

It could work well in a new section here, on the theme.json page: https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#css-custom-properties-presets-custom

Or perhaps on this page: https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-color-palettes

How will this new page help you?

This has been brought up as part of the development of the Twenty Twenty-Three default theme: WordPress/twentytwentythree#36 (comment)

If the new default theme uses base and contrast, IMO this naming convention should be written in the theme handbook to promote its use throughout the theming community. And from now on, the default themes (2024, 2025...) should stick to it. It would also be helpful for plugins.

Twenty Twenty-Three uses the names 'base' and 'contrast' for its main contrasting colors, and as preferrable alternatives to 'background' and 'foreground'. There is more information for the reasoning in this discussion, but to summarise:

• These names do not conflict with element names. For example, 'background' is an element, but a color named 'background' may not always be used for the background element, which can lead to confusion.
• These names result in readable generated slugs for CSS class names.

Note that it's probably best to update the handbook with these changes only once Twenty Twenty-Three has been released.

[DaisyOlsen]

I'd like to take this on if that works for you, @mikachan If you have done any work on this already just let me know.

[mikachan]

Yes, that's fine with me! Please let me know if I can help/review.

[DaisyOlsen]

From this issue, I'm going to suggest that we add a short snippet about base and contrast being recommended as the minimum for the color palette here

I'm torn about investing the effort, small as it is, to implement it on the block editor handbook side(which are the links mentioned above). ideally, we should promote the Theme Developer Handbook over Block Editor for most developers.

In any case, the issue for changes to the Block Editor Handbook will need to be in the Gutenberg Repo with a corresponding PR.

Happy to hear any other thoughts on this, but this seems pretty straight forward from a Theme handbook perspective. Will come back around with some copy to suggest.

[carolinan]

I think the page and the section you linked to is a good place to add it.

[github-actions]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[mikachan]

I think the page and the section you linked to is a good place to add it.

I agree, the Theme Developer Handbook page makes sense 👍

[DaisyOlsen]

Here's what I'm thinking, would love feedback on the phrasing and inclusion within the Color palette section. I am not necessarily tied to anything in the phrasing but wanted to get something in here for feedback.

Color palette

The color value for the palette item can be any valid CSS color value such as “blue” or a hex color such as “#00FF00”.

When creating a custom color palette in your theme, it is recommended to include colors with the slugs base and contrast for setting the two main colors, typically the background and text colors, for your site.

[carolinan]

I like it.
Should it explain why the other types of slugs (background, red etc) are problematic?

[DaisyOlsen]

Sure I may be able to rework some of what @mikachan put in the original comment

[richtabor]

When creating a custom color palette in your theme, it is recommended to include colors with the slugs base and contrast for setting the two main colors, typically the background and text colors, for your site.

Perhaps separating the concerns a bit to reduce potential confusion for folks:

"...include colors with the slug base for the background of your site, and contrast for the main text color"

[DaisyOlsen]

I agree that is more clear, thank you. I'm still pondering the expansion of this to include the "why not these other things" section. Right now it feels to me that the ideal would be something short that links out to something more detailed along the code standards vein...

[carolinan]

I have a small reservation about the use of primary in "..,and contrast for the primary text color"", since I think primary will be the first go-to slug for a third color, like in Twenty Twenty-Three.

[DaisyOlsen]

Leaving this here for my own reference. Thanks, @richtabor fie both writing and updating the post. https://richtabor.com/standardizing-theme-json-colors/

Editing to add this relevant issue for future reference WordPress/gutenberg#48228

[richtabor]

I have a small reservation about the use of primary in "..,and contrast for the primary text color"", since I think primary will be the first go-to slug for a third color, like in Twenty Twenty-Three.

Good point. Perhaps 'main' is better.

"...include colors with the slug base for the background of your site, and contrast for the main text color"

[DaisyOlsen]

Here's what I'm thinking right now about moving forward with this issue.

Let's wrap up this issue to address just the naming convention with this copy:

Color palette
The color value for the palette item can be any valid CSS color value such as “blue” or a hex color such as “#00FF00”.

When creating a custom color palette in your theme, it is recommended to include colors with the slug base for the background of your site, and contrast for the main text color.

As a follow-up, I believe a new issue should be created for adding more detail about recommendations for using more semantic slugs My opinion is that a mention of good/bad slug names should be linked out to another page with a more complete explanation that might be more broadly applied since slug names are used across all presets in theme.json.

[DaisyOlsen]

What's the best way to get this change pushed live? I already have access to publish directly on developer.wordpress.org but want to ensure I follow protocol. @carolinan, can you advise?

[DaisyOlsen]

@carolinan I've scheduled this change to go live in one week, allowing plenty of time for review. Feel free to trigger it to publish sooner if you agree with the change as it has been implemented.

https://developer.wordpress.org/wp-admin/post.php?post=144996&action=edit

[carolinan]

Published.