[wp-trac] [WordPress Trac] #65085: Expose admin design tokens (radius, spacing, grayscale, typography) as CSS custom properties via wp-base-styles

[WordPress Trac]

#65085: Expose admin design tokens (radius, spacing, grayscale, typography) as CSS
custom properties via wp-base-styles
----------------------------+-----------------------------
 Reporter:  jillq           |      Owner:  (none)
     Type:  enhancement     |     Status:  new
 Priority:  normal          |  Milestone:  Awaiting Review
Component:  Administration  |    Version:  trunk
 Severity:  normal          |   Keywords:
  Focuses:  ui, css         |
----------------------------+-----------------------------
 == Background ==

 WordPress 7.0's admin visual reskin (#64308) introduced a comprehensive
 design token system in `src/wp-admin/css/_tokens.scss`, covering:

  * '''Border radius:''' `$radius-xs` (1px), `$radius-s` (2px), `$radius-m`
 (4px), `$radius-l` (8px), `$radius-30` (12px), `$radius-full` (9999px)
  * '''Spacing:''' `$grid-unit-05` through `$grid-unit-60` (4px increments)
  * '''Grayscale:''' `$gray-100` through `$gray-900` (a unified neutral
 palette)
  * '''Typography:''' `$font-size-xs` through `$font-size-xl`, `$font-
 weight-regular`, `$font-weight-medium`
  * '''Elevation:''' `$elevation-xs` through `$elevation-l`

 These tokens are used internally by core CSS during the Sass build, but
 the resulting values are not exposed as CSS custom properties at runtime.
 Plugin authors who want to align with Core's design system therefore have
 to hardcode the values (e.g. `border-radius: 8px` to match dashboard
 widgets).

 The existing `wp-base-styles` stylesheet handle already exposes admin
 color scheme tokens this way (`--wp-admin-theme-color`, `--wp-admin-theme-
 color--rgb`, `--wp-admin-theme-color-darker-10`, `--wp-admin-theme-color-
 darker-20`, `--wp-admin-border-width-focus`). This proposal extends that
 pattern to the rest of the token system.

 == Problem ==

 Plugins and themes that want to follow WP 7.0's modernized visual language
 currently have three suboptimal choices:

  1. '''Hardcode the values''' — brittle, silently drifts when Core updates
 the token values
  2. '''Conditionally override with version-gated CSS''' — what WooCommerce
 currently does; adds maintenance burden
  3. '''Don't align''' — fragments the admin visual experience, which is
 exactly what #64308 was trying to fix

 == Proposal ==

 Extend `wp-base-styles` (or introduce a sibling handle) to emit CSS custom
 properties for the public subset of `_tokens.scss`:

 {{{
 :root {
     /* Border radius */
     --wp-admin-radius-xs: 1px;
     --wp-admin-radius-s: 2px;
     --wp-admin-radius-m: 4px;
     --wp-admin-radius-l: 8px;
     --wp-admin-radius-30: 12px;
     --wp-admin-radius-full: 9999px;

     /* Grid units */
     --wp-admin-grid-unit-05: 4px;
     --wp-admin-grid-unit-10: 8px;
     --wp-admin-grid-unit-15: 12px;
     --wp-admin-grid-unit-20: 16px;
     --wp-admin-grid-unit-30: 24px;
     --wp-admin-grid-unit-40: 32px;
     --wp-admin-grid-unit-50: 40px;
     --wp-admin-grid-unit-60: 48px;

     /* Grayscale */
     --wp-admin-gray-100: #f0f0f0;
     --wp-admin-gray-200: #e0e0e0;
     --wp-admin-gray-300: #dddddd;
     --wp-admin-gray-400: #cccccc;
     --wp-admin-gray-600: #949494;
     --wp-admin-gray-700: #757575;
     --wp-admin-gray-900: #1e1e1e;

     /* Typography */
     --wp-admin-font-size-xs: 11px;
     --wp-admin-font-size-s: 12px;
     --wp-admin-font-size-m: 13px;
     --wp-admin-font-size-l: 15px;
     --wp-admin-font-size-xl: 20px;
     --wp-admin-font-weight-regular: 400;
     --wp-admin-font-weight-medium: 500;
 }
 }}}

 Naming follows the existing `--wp-admin-[thing]` convention already
 established for `--wp-admin-theme-color`, `--wp-admin-border-width-focus`,
 etc.

 == Benefits ==

  * '''Plugins align automatically''' — When Core updates a token value (as
 happened with the reskin itself), anything depending on these custom
 properties updates with it. No plugin PR required.
  * '''Consistent admin visual experience''' — Fragmented admin styling is
 a merchant pain point. This unlocks plugin-side alignment without
 duplicating Core values.
  * '''Extends an existing pattern''' — No new architecture; just the next
 step of the work #64308 already started with color tokens.
  * '''Low risk''' — CSS-only change, additive, no functional impact.
 Existing styles unchanged.

 == Implementation notes ==

 The `wp-base-styles` handle is already loaded on admin pages (from
 #64308's sub-tickets). This change would extend that stylesheet's contents
 to include the additional custom properties listed above, likely sourced
 from the same `_tokens.scss` during the Sass build.

 An optional follow-up could also migrate existing hardcoded token usage
 inside Core admin CSS to reference these custom properties, but that's not
 required for this ticket — exposing the values is sufficient to unlock
 plugin alignment.

 == Prior art ==

  * #52623 — "Proposal: Add CSS variable for admin-bar height to core" —
 same pattern: expose an existing value as a CSS custom property for
 plugin/theme use.
  * [https://make.wordpress.org/core/2021/01/29/introducing-css-custom-
 properties/ Introducing CSS Custom Properties to the WordPress Admin (Make
 Core, 2021)] — the original project that gave us `--wp-admin-theme-color`.
  * #64308 — the WP 7.0 admin reskin that introduced the token system this
 proposal would expose.

 == Alternatives considered ==

 Core could instead publish admin tokens via an NPM package similar to
 @wordpress/base-styles. That approach works well for plugins with modern
 build pipelines, but doesn't help plugins without one, and can't respond
 to runtime preferences like the user's admin color scheme. A CSS custom
 property approach (like the existing `--wp-admin-theme-color`) complements
 the NPM package route rather than replacing it.

 == Related ==

 I've been doing plugin-side alignment work for WooCommerce (see
 [https://github.com/woocommerce/woocommerce/pull/64196
 woocommerce/woocommerce#64196] for a recent example) and ran into this
 friction directly. To be clear, I'm not waiting on this to ship the
 plugin-side work — WooCommerce is already adopting the existing `--wp-
 admin-theme-color` pattern with hardcoded fallbacks where Core tokens
 aren't exposed. This ticket is about making the next round of that work
 more systemic.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65085>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform