CSS Custom Properties Project Update

Based on the discussions in this previous post, a few of us over in #core-css have made some demos and explored the technical details around using custom properties with coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. as part of the larger goal to implement dark mode in WP-Adminadmin (and super admin), and allow for more sophisticated handling of color schemes (see #49999). The following post will summarize those thoughts and lay out a possible roadmap.

Given the IE11 phase-out plan, fallbacks for custom properties are not needed. If for some reason that changes, there are PostCSS tools for automating fallbacks.

Naming the custom properties – some demos to explore different naming schemes were shared in the core-CSSCSS Cascading Style Sheets. meetings (demo 1, demo 2, and demo 3). The aim is to create a consistent and understandable “APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.” for interacting with colors (custom properties won’t be used for typography or layout). One formula for creating names was decided on, --[prefix]--[location]--[property]--[state]. Those tokens will be refined further in future Core CSS meetings. The next meeting is Thursday 21:00 UTC.

How it (could) work

In this example, there are 4 screenshots of possible color schemes – default, light high contrast, dark, and dark high contrast. Custom properties would be used to set the background colors, text colors, link, and button colors so that each theme can set just what is needed. For example, the button’s CSS would look like this:

.button {
    background: var(--wp-admin--button--background);
    color: var(--wp-admin--button--color);

Then each theme would set those variables, inheriting from the default.

body {
    --wp-admin--button--background: #2371b1;
    --wp-admin--button--color: #fff;

body.is-theme-dark {
    /* No change, the same button is used. */

body.is-theme-light-high-contrast {
    /* Inherits the text color, but darkens the button. */
    --wp-admin--button--background: #0b4b78;

body.is-theme-dark-high-contrast {
    /* Overrides both background and text. */
    --wp-admin--button--background: #68de7c;
    --wp-admin--button--color: #1d2327;

PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party authors will also be able to use these colors in their CSS without creating separate rules for each color scheme.

.my-fancy-button {
    background: var(--wp-admin--button--background);
    color: var(--wp-admin--button--color);

Specific technical details – like how the schemes are registered & loaded, how to work with the existing properties in GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/, whether there should be a “default dark” for schemes to inherit from, etc – are still in progress. If this sounds interesting to you, please join the conversation in #core-css!

This project will likely also tie into the CSS deprecation discussion in #53070.

Next Steps

This is just a rough outline, and will depend on support and involvement across different teams.

Phase 1 (eta: early 5.9)

  • Start creating custom properties with an --experimental prefix. This will allow for use in trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. without committing to forever supporting them.
  • This will need more input from designers and UIUI User interface folks to help identify colors and make sure the naming schemes are coherent in the design system of WordPress.
  • Once some color custom properties have been created, use these for the current core color schemes. Maybe make improvements to the color schemes.

Phase 2 (eta: 6.0)

  • Remove the experimental prefix from the custom properties.
  • Create new color schemes for a dark mode, high contrast dark mode, and high contrast light mode.


Thanks to @melchoyce for quickly mocking up some possible color schemes, and thanks to @danfarrow, @notlaura, & @joyously for reviewing this post.