Support structured color options for wp_admin_css_color

[aduth]

Related Gutenberg issue: ​https://github.com/WordPress/gutenberg/issues/80766

Request: ​`wp_admin_css_color` should accept options for structured color values that can be used by WordPress itself to apply a color scheme without need for stylesheet overrides, and these options should be exposed on the user REST API endpoint when the associated color scheme is selected.

Background:

In its current state, wp_admin_css_color is largely concerned with providing a stylesheet be loaded associated with a color scheme of a given name. The color scheme itself is applied through the stylesheet targeting specific elements on WordPress pages. While the function accepts an array of $colors, those are only used in presenting an option on the user profile page for selecting the color scheme itself, and have no other purpose. They are an unordered, non-semantic set of colors that should not be inferred to carry any meaning in how they should apply to different elements of the admin experience.

WordPress 7.1 will include an ​initial theming implementation, including a new ThemeProvider component that accepts primary and background theme colors. In WordPress, this is already used to ​apply the user's color scheme to the Site Editor. But since these seed values can only be known ahead of time for the default WordPress color schemes, it does not support custom color schemes registered through wp_admin_css_color.

Technical Notes:

I included a ​comment on the associated Gutenberg GitHub issue which describes how I think this could be implemented:

In my mind, we could overload wp_admin_css_color so it could be called like this:

wp_admin_css_color( 'ectoplasm', __( 'Ectoplasm' ), [
  'primary' => '#646c3e',
  'background' => '#4f386e',
] );

$args as an array third argument helps support optionality of arguments and future growth. Relatively straight-forward to overload with backwards-compatibility by checking the whether the third argument is a string or array.

Current $colors and $icon arguments could be inferred from primary/background, or optionally provided explicitly with 'colors' and 'icon' to override. Same with $url being an optional argument 'url'.

Since we'd be applying theme colors dynamically to some parts of the admin, a plugin author may not care to provide their own stylesheet and $url is optional.

[christopherplus]

I hope to see this fixed in an upcoming WordPress 7.1.x release, as the issue breaks our custom admin color scheme in WordPress 7.1.

[aduth]

@christopherplus This ticket is primarily focused on enhancing the current wp_admin_css_color API in a way which would eventually support custom color schemes in pages like the site editor. Prior to WordPress 7.1, the Site Editor didn't support any scheming, and afterward it supports the built-in color schemes; this ticket is aimed at extending that support to custom color schemes.

If there was a specific regression of the changes in WordPress 7.1 that broke color schemes, it might be better to file that as a separate bug report.

[aduth]

The proposed primary and background seeds may be insufficient to express what we'll eventually want to be able to control as distinguishing between sidebar and main content areas to allow for true "dark mode" themes. Taking the ​Admin Design, ​earlier design concepts, and ​Admin Materials and Surfaces as reference, we can expect that both the sidebar and main content areas may need to be customizable. We could choose to limit this to background color and expect that the accent color would extend to both, or we could even go as far as to allow distinct accent and background colors per area.

These are decisions we can make further down the road, but as far as it impacts the proposal here, we'll want to design an API that is future-compatible to this consideration.

With that in mind, it could end up looking something more like:

wp_admin_css_color( 'ectoplasm', __( 'Ectoplasm' ), [
  'primary' => '#646c3e',
  'background' => [
    'base' => '#4f386e',
    'surface' => '#f3f3f3'
  ],
] );