# Introducing CSS Custom Properties…

Introducing CSSCSS Cascading Style Sheets. Custom Properties to the WordPress Adminadmin (and super admin)

As part of the Iterating on Colour Schemes ticketticket Created for both bug reports and feature development on the bug tracker. (#49999) the #core-css team have been working on how to go about implementing the use of CSS Custom Properties in the WordPress Admin.

The first step of this task was to iterate on the existing colours used and reduce them down to a workable color palette. This work was committed to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. on Tuesday January 26th 2021 thanks to the awesome work of @ryelle and the rest of the #core-css team. This reduced the number of unique colours used from 199 to 99!

The next step now is to look at how we can use this work to create a colour palette using CSS Custom Properties and ensuring we have all of the relevant fallbacks. This is where we would really like to invite some discussion (and is the point of this post).

From discussions we’ve already had on various tickets and during the #core-css meetings, there are a number of options currently being considered.

Naming Custom Properties

We all know naming is hard! However, there have been a number suggestions already that could be considered.

The colours already have names (see this codepen for an easy reference: https://codepen.io/ryelle/full/WNGVEjw) so we could continue to use the same names. For example:

-—color-blue-20: #72aee6;
—-color-blue-40: #3582c4;

—-color-green-20: #1ed14b;
—-color-green-40: #00a32a;

We could, instead of using the actual colour name, implement using primary, secondary, tertiary names. For example:

—-color-primary-20: #72aee6;
—-color-primary-40: #3582c4;

—-color-secondary-20: #1ed14b;
—-color-secondary-40: #00a32a;

There was also a name proposal for hues in this post: https://make.wordpress.org/design/2019/11/26/proposal-a-new-color-palette-for-wordpress/ which looked like:

--color-background: light gray background used in WordPress.
--color-surface: white background used for UI elements.
--color-border: border color used on UI elements.
--color-on-surface: default dark gray text/icon color.
--color-on-surface-subtle: light gray text/icon color.

Implementing CSS Custom Properties.

So far the general approach to this, that has generated the most discussion and agreement, is to create a base colour palette and then apply those colours to properties named after their usage. Something similar to:

// Base color palette.
—-color-gray-0: #f6f7f7;
—-color-gray-100: #101517;

// Properties used in CSS.
—-body-background-color: var( —-color-gray-0 );
—-text-default-color: var( —-color-gray-100 );

// Application.
body-background-color: var( —-body-background-color );
color: var( —-text-default-color );

(Exact property names and colours used here are examples only)

This would give us the flexibility to utilise the dynamic nature of CSS custom properties to change the value of properties based on certain criteria, and without the danger of the name becoming misleading or incorrect.

I imagine that, which custom properties should be created in the abstracted layer applied in the CSS, would generate a lot of conversation. However, if there are other ways to implement custom properties that you feel may be worth exploring as well, please do still mention them.

Additional Considerations

One of the overall goals of this work is to ensure the admin is inclusive to everyone by utilising some of the newer features coming to CSS and honouring peoples individual system preferences. At the moment the focus of this is honouring dark mode but more customisation options are becoming available so how we name custom properties and choose to implement them needs to account for that. For example, this wouldn’t be suitable because the name becomes misleading.

—-colour-black-background: #000;

@media (prefers-color-scheme: light) {
    —-colour-black-background: #fff;

The other big consideration is that there are a number of alternative admin colour schemes already available, all of which should be able to take advantage of the use of custom properties once implemented. Therefore we need to keep the number of custom properties created concise and how we implement them needs to easily extendable.

As well as this we do also need to consider fallbacks for browsers that do not support CSS Custom Properties and this could impact how we name or implement them.

Next Steps

There is a lot of options here that could be discussed and the purpose of this post is to start some of those discussions and invite you all to give your opinions. So if you have any thoughts on this please do add them here and/or join in the live discussions in the weekly #core-css meeting every Thursday from 10pm UTC.


#00a32a, #1ed14b, #3582c4, #72aee6, #f6f7f7, #fff