What should be custom properties in wp-admin?

In a recent post on make.wordpress.org/core, Kirsty started the conversation on implementing custom properties in the WordPress admin. One recurring question is – how do we balance customization and ease of use? Ideally we’ll come out of this with a system that is understandable, that both core and plugin creators can use to create new admin color schemes, without needing to override any CSS.


To think about the variable problem, I threw together what a dark mode might look like. This is currently very difficult with the current admin scheme system, and is a goal of the revamp. It had me asking questions like…

  • How does the page background color relate to the “cards” on the dashboard?
  • How many variables would we need for buttons, with primary and secondary designs, each with hover and focus states? That’ll add up…
  • What variables might we need for list tables?
  • Should the “error”/”warning”/”success” colors be variables? Do schemes need to change that?

I quickly mocked up the WordPress admin in sketch, showing two pages that are pretty representative of the whole thing, the dashboard (plus some extra button states), and a list table with actions.

Then I created a dark mode version (this was so easy using the new color palette!) (while I like this start, this isn’t meant to be a design proposal). I left the menu alone. I have a good idea what variables are needed for the menu & toolbar, since those already exist – I’m going to suggest reducing them though.

This let me pull out a number of things I would want to see as separate variables. In some schemes, these might use the same colors, but they should each be individually controlled.

Page background
Surface (card) background
Surface (card) border (maybe another for list tables? inputs?)
Main text color
Secondary text color
Link color
Link (hover & focus) color
Action-link colors
Notification border colors (info, success, warning, error)
Alternate row background (in list tables)
Row status backgrounds (in list tables)

A detour about buttons…

Buttons might need some more thought, but if we’re willing to simplify the current default scheme, we might only need 4 variables. I’m not sure how to name them though. I’ve split them up like this:

Color A (a primary color)
- Primary button background
- Secondary button text
- Secondary button border

Color B (a gray with contrast against A)
- Primary button text
- Secondary button background

Color C (lighter/darker of A)
- Primary button (hover & focus) background
- Secondary button (hover & focus) text
- Secondary button (hover & focus) border

Color D (a gray with contrast against C)
- Primary button (hover & focus) text
- Secondary button (hover & focus) background

The alternative, which would create more variables but be easier to name & conceptualize, would be to break them out into primary- / secondary-, -background- / -foreground- (or text and border), with separate properties for default, hover, and focus. This gives a lot of control to the scheme designer, but I’m not sure if that level of control is necessary.

Generating variables, or: Why can’t we use just one action color, and darken it for hover?

This has been brought up, but doesn’t work across all schemes. For example, on a dark background, decreasing the “action” color might decrease the contrast too much. Or darkening a light color might be a more noticeable difference than a dark color, so the change is not the same. A high contrast scheme will need more of a difference than a low contrast scheme. For all those cases, the calculation can’t be universal.

The way variables are calculated in the current admin color schemes has been a point of difficulty, which in an extreme example has led me to redefine a lot of the “internal” variables and still need to override styles with CSS.


There’s plenty here that I haven’t touched on – entire screens (the customizer), form inputs, modals, plugins, etc. But I hope this explains a little more my thought process in the custom properties discussion.

One thought on “What should be custom properties in wp-admin?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: