Admin UI: ship shared WPDS design-tokens stylesheet on Jetpack admin pages

[CGastrell]

Part of #49285 (Phase 2b).

Proposed changes

Give every Jetpack admin page a single, shared runtime source for WPDS design tokens (--wpds-*) by registering one token-only stylesheet and enqueuing it at two chokepoints. This lets var(--wpds-*) consumers resolve to the design-system value instead of their hand-written hex fallback, and replaces the per-package bundled token copies (the version-skew vector) with one versioned handle.

• projects/packages/admin-ui — adds @wordpress/theme as a build dependency, emits a token-only build/design-tokens.css (sourced from @wordpress/theme/design-tokens.css, content-hash versioned via design-tokens.asset.php), and exposes a single reusable static API — Admin_Menu::enqueue_design_tokens() — that registers the jetpack-admin-ui-design-tokens handle on first use (idempotent) and enqueues it. Admin_Menu is the natural owner: it's the repo-wide chokepoint every modernized Jetpack admin page registers through, so it's the only class that knows their hook suffixes (tracked in $page_hooks) and scopes the enqueue to them. A local src/design-tokens.css re-export is used (rather than pointing the webpack entry straight at the package) so the import is inlined by css-loader instead of being externalized to a non-existent wp-theme/design-tokens.css script handle.
• projects/plugins/jetpack — admin-ui is a dependency of the Jetpack plugin, so the legacy/wrap_ui pages (Settings, Dashboard, Debugger) that aren't registered through Admin_Menu simply call the same Admin_Menu::enqueue_design_tokens() API from the central is_jetpack_admin_page() gate (admin_enqueue_scripts).

Both call sites keep only their own page-scoping gate and delegate the register+enqueue to the one shared API, so there is a single owner of the handle and no duplicated enqueue logic — one registered handle, one HTTP request, no per-plugin CSS duplication. Any future consumer can enqueue the tokens the same way.

The stylesheet is token-only: its only rules are :root{--wpds-*}, the [data-wpds-theme-provider-id][data-wpds-density=*] token-override blocks, and a retina @media wrapping :root. No component or class selectors, so there is no component-style bleed.

What this does and doesn't do on the legacy _inc pages

This is the subtle part, worth stating explicitly:

• This PR makes --wpds-* defined on :root at runtime on the legacy pages — but it does not change the visible Hello Dolly color there. The legacy _inc build runs postcss-custom-properties with preserve:false, which inlines var(--wpds-*, #fallback) to a literal and strips the var() at build time. So the _inc-compiled Dolly rule has no live var() left to consume the runtime token. Hello Dolly on Dashboard/Settings/Debugger is colored by the companion build-time PR Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750, which inlines the token to #707070 in the _inc build itself.
• The legacy-page enqueue is kept deliberately: it pre-stages the @wordpress/ui migration of those pages. As legacy surfaces move onto @wordpress/ui components (which ship live var(--wpds-*), not stripped _inc CSS), this runtime token source becomes load-bearing. Removing it now would just mean re-adding it mid-migration. It's a token-only, deduped, single-request stylesheet, so the cost of carrying it ahead of need is negligible.

Out of scope (later phases)

• Not removing the per-package bundled tokens from My Jetpack/Boost/etc. (later cleanup phase).
• Not retiring the legacy .wp-admin #dolly / .jetpack-pagestyles #dolly rules (Phase 4, separate PR).
• The visible Hello Dolly color shift on the legacy pages lands via Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750 (build-time) — see the note above. This PR provides the shared runtime token source the modernized pages and the upcoming migration depend on.

Related product discussion/links

• Issue: Normalize Hello Dolly across Jetpack admin pages + consistent WPDS token loading #49285
• Companion (build-time, legacy _inc pages): Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750
• Audit (no runtime --wpds-* source on wrap_ui pages): Normalize Hello Dolly across Jetpack admin pages + consistent WPDS token loading #49285 (comment)
• Decision (runtime enqueue vs. build-time postcss → hybrid): Normalize Hello Dolly across Jetpack admin pages + consistent WPDS token loading #49285 (comment)

Does this pull request change what data or activity we track or use?

No.

Testing instructions

In-browser probe on the dev site, run in the browser console on each page:

getComputedStyle(document.documentElement).getPropertyValue('--wpds-color-fg-content-neutral-weak').trim()

Expected: a non-empty #707070 (previously empty, so any var(--wpds-…, #87a6bc) consumer fell back to #87a6bc). Note: this confirms the custom property is now defined on :root — on the legacy _inc pages that is the token source, not the Dolly color (see "What this does and doesn't do" above).

Verified results:

Page	URL	--wpds-* defined on :root	design-tokens stylesheet enqueued
Dashboard	admin.php?page=jetpack	#707070 ✅	✅
Settings	admin.php?page=jetpack#/settings	#707070 ✅	✅
Debugger	admin.php?page=jetpack-debugger	#707070 ✅	✅

Source-of-token proof (Dashboard): disabling the enqueued design-tokens.css stylesheet makes the :root custom property go empty again, confirming this stylesheet is the sole runtime source of the property on the legacy page.

Token-only proof: the emitted build/design-tokens.css contains only :root, [data-wpds-theme-provider-id][data-wpds-density=*], and a retina @media{:root} — no component/class selectors. design-tokens.asset.php has 'dependencies' => array() (nothing externalized).

Gates run: phpcs (both PHP files), stylelint (new CSS), eslint, dev + production webpack build with validate-es, admin-ui PHP unit tests — all pass.

Screenshots: design tokens defined on the legacy Jetpack Dashboard

The visible #87a6bc → #707070 Hello Dolly shift is demonstrated/owned by #48750. The screenshots below show this PR's effect: with the stylesheet in place, --wpds-* resolves to the WPDS value on the legacy Dashboard (applying a live token-based #dolly rule for illustration).

Before (no runtime token source — property empty):

After (token resolves to #707070):

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the change/wpds-tokens-admin-pages branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack change/wpds-tokens-admin-pages

bin/jetpack-downloader test jetpack-mu-wpcom-plugin change/wpds-tokens-admin-pages

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

---

Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

Coverage changed in 2 files.

File	Coverage	Δ%	Δ Uncovered
projects/packages/admin-ui/src/class-admin-menu.php	156/199 (78.39%)	-6.22%	15 💔
projects/plugins/jetpack/class.jetpack-admin.php	77/249 (30.92%)	-0.76%	6 💔

Full summary · PHP report · JS report

_{If appropriate, add one of these labels to override the failing coverage check: Covered by non-unit tests Use to ignore the Code coverage requirement check when E2Es or other non-unit tests cover the code Coverage tests to be added later Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR I don't care about code coverage for this PR Use this label to ignore the check for insufficient code coveage.}