Normalize Hello Dolly across Jetpack admin pages + consistent WPDS token loading

[CGastrell]

Tracking issue for the multi-PR effort to give Hello Dolly a single, consistent treatment across Jetpack admin pages, built on WPDS design tokens.

Background

Hello Dolly renders <p id="dolly"> outside the React mount, at the top of #wpbody-content. Today it's styled by three overlapping, inconsistent rules: .wp-admin #dolly (admin-static.scss, #87a6bc), .jetpack-pagestyles #dolly (_main.scss, desaturated ≈#a1a1a1), and the central :global(.jetpack-admin-page #dolly) (components mixin). Color also drifts page-to-page because the WPDS token (--wpds-color-fg-content-neutral-weak = #707070) only resolves where tokens are loaded (e.g. Boost) and falls back to #87a6bc elsewhere (e.g. AI).

Part of the broader @wordpress/components → @wordpress/ui migration: the token-loading groundwork the migration depends on.

Phases

• Track 1 — central rule normalize (Hello Dolly: normalize centrally, drop per-page duplicates #48472): expand the components-mixin rule to the full treatment (var(--wpds-color-fg-content-neutral-weak, #87a6bc)); drop per-page Boost/Newsletter overrides. Merged.
• Phase 2 — token-loading, shipped as a hybrid by page architecture (see decision and the implementation correction below). 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 a runtime :root{--wpds-*} has nothing to bind to on those pages, and preserve:true is not viable (breaks calypso-color-schemes' generic vars, which aren't loaded at runtime). Hence two complementary PRs:
  • 2a — build-time, legacy _inc pages (Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750): feed @wordpress/theme/design-tokens.css into the jetpack plugin's postcss-global-data so var(--wpds-*, #fallback) inlines to the token value (#707070). This is what actually colors Dolly on Dashboard/Settings/Debugger. Merged (trunk 390f6821f84).
  • 2b — runtime tokens-only stylesheet (Admin UI: ship shared WPDS design-tokens stylesheet on Jetpack admin pages #49345): register one token-only :root{--wpds-*} stylesheet from @wordpress/theme and enqueue it on every Jetpack admin page (admin-ui Admin_Menu chokepoint + jetpack is_jetpack_admin_page() gate). Fixes the modernized pages, dedupes per-package token copies (kills version skew), and pre-stages the @wordpress/ui migration of the legacy pages (where live var() will replace the stripped _inc CSS). Both PRs pin @wordpress/theme@0.13.0 → no skew. Ships a single reusable Admin_Menu::enqueue_design_tokens() API both call sites delegate to. Merged (trunk eea718ca7fd).
• Phase 3 — confirm components-mixin CSS loads on wrap_ui pages (Settings/Dashboard/Debugger): PASS — the central .jetpack-admin-page #dolly rule loads on all three. Phase 4 unblocked on the CSS-presence front.
• Phase 4 — retire legacy rules Use class_exists() guard for Featured_Content. #1/Allow plugins to inject additional template-specific open graph tags #2 so the central .jetpack-admin-page #dolly rule governs everywhere. Merged (Hello Dolly: retire legacy per-page #dolly rules (#49285 Phase 4) #49402, trunk d8a6dee01e0) (verified live: Dashboard #dolly → #707070, no layout shift).
  • Delete .wp-admin #dolly block — _inc/client/scss/shared/admin-static.scss:204-217.
  • Delete .jetpack-pagestyles #dolly block — _inc/client/scss/shared/_main.scss:45-63 (its <660px{display:none} is already covered by rule Edit and rename the readme for GitHub #3's @media(max-width:659px)).
  • Preserve: My Jetpack p#dolly{display:none} (packages/my-jetpack/_inc/style.module.scss:113); JITM adjacency.
  • Risk: rule Edit and rename the readme for GitHub #3 deliberately omits position/top/left/right/padding/font-size, so removing Use class_exists() guard for Featured_Content. #1/Allow plugins to inject additional template-specific open graph tags #2 drops those on the legacy pages (Dolly → WP hello.php defaults + rule Edit and rename the readme for GitHub #3). Verify layout/positioning visually on Settings/Dashboard/Debugger + My Jetpack, not just color. Color converges to #707070 (intended; needs sign-off).

Risks / decisions

• Build-time inline = no runtime theming — accepted and scoped: build-time (2a) is used only for the legacy _inc pages, which can't consume runtime tokens anyway; modernized pages get the runtime path (2b), which stays themeable.
• Retiring rule Allow plugins to inject additional template-specific open graph tags #2 also clears the Allow plugins to inject additional template-specific open graph tags #2↔Edit and rename the readme for GitHub #3 specificity tie on Settings/Dashboard.
• Dolly shifts #87a6bc/≈#a1a1a1 → #707070 on the exception pages (Settings/My Jetpack/Dashboard) once 2a/2b land — intended, needs sign-off.
• Cross-plugin enqueue coordination is handled by the single shared Admin_Menu handle (2b), not per-plugin duplication.

[CGastrell]

Gap: Hello Dolly on the viewport-pinned modernized dashboards

The phases above implicitly assume Dolly renders in normal flow and only needs its overlapping rules unified + tokens loaded. That holds for the AdminPage React pages (Boost / Protect / Search / Social / AI), which are normal-flow scrolling pages — Dolly sits top-right there as the normalized strip and converges to #707070 once tokens load.

It does not hold for the fully-modernized dashboards — VideoPress, Forms, Newsletter — where Dolly is absent today for three different, unplanned reasons that share one root: these pages flip #wpbody-content to a fixed, clipped chrome that a floated legacy <p> doesn't fit into.

• Forms — remove_all_actions( 'admin_notices' ) on the dashboard page (projects/packages/forms/src/dashboard/class-dashboard.php:194). Dolly is never emitted.
• VideoPress & Newsletter — emitted via admin_notices, but swallowed by layout. Both include the shared jetpack-admin-page-layout mixin (projects/js-packages/base-styles/admin-page-layout.scss), which sets #wpbody-content { position: fixed; overflow: hidden } (lines 109/120). The React dashboard fills that pinned/clipped box, so the admin_notices-injected <p id="dolly"> at the top of #wpbody-content is covered/clipped. (Newsletter even loads the central #dolly rule and gets the jetpack-admin-page body class — the styling is just never visible.)

So on these three the question isn't "what color?" — it's "should Dolly be present at all, and if so how does a fixed-chrome layout host it?" The current state is incidental, not designed: removed in one, clipped in two.

Proposed Phase 5 — pinned-dashboard policy

Rather than force Dolly into layouts it doesn't fit, make the intent explicit and uniform per layout class:

• Normal-flow admin pages → Dolly shows, normalized, → #707070 after Phases 1–2 (already covered by the plan).
• Viewport-pinned modernized dashboards (VideoPress / Forms / Newsletter, and any future ones built on jetpack-admin-page-layout) → Dolly intentionally absent, done the same way everywhere (a single explicit remove_action, not the current mix of "removed here / clipped there").

This makes the behavior consistent and intentional. Open question for sign-off: confirm we're fine with Dolly being deliberately absent on the pinned dashboards (vs. investing in a layout slot to host it).

[simison]

Dolly intentionally absent,

Not sure if intentional; feels more like a bug in WP Build/WP Boot. 😅 I'll think a bit how to solve it potentially (noted in WordPress/gutenberg#77628 (comment)) and upstream ideas for all this welcome!

[CGastrell]

Decision: commit to runtime tokens (Phase 2), retire the build-time stopgap (Phase 1)

Now that Track 1 (#48472) has landed, we need to pick the token-loading approach before Phases 3–4. Recommendation: commit to Phase 2's runtime tokens-only stylesheet as the end-state, and close Phase 1 (#48750) rather than merge it.

Why not Phase 1 (build-time inline): It's nearly done, but it's a stopgap with a permanent tax:

• Values are frozen at build time → no runtime theming (dark mode / theme switching can't work).
• It must be repeated in every build pipeline (jetpack _inc/, Boost, each modernized package's webpack) — every new pipeline/plugin is an opt-in trap that silently falls back to hand-written hex if forgotten.
• It creates the build-time + runtime mix → version skew this issue already warns against.
• Its only cited consumer, Componentry: migrate Status to @wordpress/ui Text in plugin consumers #48711, has already merged (with hex fallbacks), so Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750 no longer unblocks anything live.

Why Phase 2 (runtime tokens-only) is both better and tractable: The cross-plugin coordination is smaller than it looks because there's a genuine shared chokepoint:

• Admin_Menu::add_menu() (projects/packages/admin-ui/src/class-admin-menu.php) already enqueues a stylesheet via asset.php (deps + version) on admin_enqueue_scripts — the exact template for a tokens handle. This covers the modernized package dashboards (VideoPress/Forms/Newsletter and friends).
• The jetpack plugin already has a central is_jetpack_admin_page() gate (add_footer_removal_styles) for the legacy/wrap_ui pages.
• @wordpress/theme (design-tokens.css) is already in the dependency tree.

So the implementation is roughly: register @wordpress/theme/design-tokens.css as a versioned WP style handle, enqueue it token-only (not full @wordpress/ui CSS — avoids component-style bleed) at those ~2 chokepoints, ensure it loads before consumer CSS. After that, var(--wpds-*) resolves at runtime everywhere a Jetpack admin page renders, themeable, single-versioned — and hex fallbacks go back to being purely defensive.

Developer-experience payoff: under Phase 2, building a new admin surface means just using var(--wpds-*) and it works — no postcss wiring, no load-bearing fallbacks, no per-pipeline opt-in. Under Phase 1 the opposite is true. That alone argues for the runtime path.

Proposed checklist change:

• Phase 1 — tokens on legacy dashboard (Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750) → close/park (superseded; no live consumer)
• Phase 2 — runtime tokens-only stylesheet at Admin_Menu + jetpack central gate (token-only, versioned handle, load-order verified)
• Phase 3 — confirm components-mixin CSS loads on wrap_ui pages (unchanged; still gates Phase 4)
• Phase 4 — retire legacy rules Use class_exists() guard for Featured_Content. #1/Allow plugins to inject additional template-specific open graph tags #2 (unchanged)

One thing to verify during Phase 2: that the legacy _inc/ Settings/Dashboard surfaces actually receive the runtime stylesheet (that's what #48750 would have covered via build-time) before we retire the legacy #dolly rules in Phase 4.

[CGastrell]

Phase 2 audit (token-loading map) + Phase 3 confirmation — live results

Probed the running admin pages directly (computed --wpds-* on :root, plus which loaded stylesheet defines the tokens and whether the central .jetpack-admin-page #dolly rule is present):

Page	jetpack-admin-page	Central #dolly rule loads	--wpds-* resolves at runtime	Token source
Jetpack Dashboard (wrap_ui)	✓	✅	❌ unset → falls back to #87a6bc	none
Jetpack Settings (same SPA)	✓	✅	❌ unset	none
Jetpack Debugger (wrap_ui)	✓	✅	❌ unset	none
My Jetpack (modernized)	✓	✅	✅ #707070	per-package build (my-jetpack/build/index.css)

Phase 3 → PASS. The central .jetpack-admin-page #dolly rule loads on all three wrap_ui pages (Settings/Dashboard/Debugger). That was the gate before retiring the legacy rules, so Phase 4 is unblocked on the CSS-presence front — the broad rule is present to take over once the legacy rules are dropped.

Phase 2 → gap + shape confirmed. Tokens resolve only where a package bundles its own :root{--wpds-*} block into its build CSS (My Jetpack here; Boost per earlier notes). The legacy _inc dashboard (Settings/Dashboard) and Debugger have no token source at all, so var(--wpds-color-fg-content-neutral-weak, #87a6bc) falls back to #87a6bc and Dolly never converges. The per-package bundling is also the concrete version-skew vector this issue warned about — each build ships its own copy at its own @wordpress/theme version.

Implication for the implementation: enqueue one shared, token-only :root{--wpds-*} stylesheet (from @wordpress/theme/design-tokens.css, no @wordpress/ui component CSS → no style bleed) on every Jetpack admin page, at the two chokepoints identified earlier:

• Admin_Menu::add_menu() (packages/admin-ui) → covers the modernized package dashboards.
• the jetpack-plugin central is_jetpack_admin_page() gate → covers the legacy/wrap_ui pages (the actual gap above).

Once that lands, the legacy _inc dashboard + Debugger get tokens, Phase 4 retires the legacy #dolly rules, and Dolly converges to #707070 everywhere it renders. Starting Phase 2 implementation on this basis.

[CGastrell]

Correction to the audit above: the legacy _inc dashboard needs the build-time path, not runtime

My audit comment said a runtime token stylesheet would "light up the legacy pages." That's incomplete — verified while implementing:

The _inc/ dashboard's postcss runs postcss-custom-properties with preserve: false, which inlines var(--wpds-*, #fallback) to its hex fallback at build time and strips the var(). So on the legacy dashboard, Dolly (and every fallback-bearing token reference) is already a literal #87a6bc before it ships — a runtime :root{--wpds-*} has nothing to bind to. Runtime tokens only help (a) the modernized pages and (b) no-fallback var(--wpds-x) consumers.

Flipping preserve: true so the vars survive to runtime is not viable: calypso-color-schemes (732 generic vars like --color-text) is build-time-inlined and not loaded at runtime, so preserving would break every no-fallback calypso var — the exact "generic vars" blocker the postcss.config.js comment flags.

So Phase 2 is hybrid by page architecture:

• Modernized (admin-ui) pages → runtime token stylesheet (Admin UI: ship shared WPDS design-tokens stylesheet on Jetpack admin pages #49345). Themeable; var() is preserved there.
• Legacy _inc dashboard (Settings/Dashboard/Debugger) → build-time inline by feeding @wordpress/theme/design-tokens.css into postcss-global-data (Jetpack: resolve WPDS design tokens in legacy dashboard CSS #48750, revived). var(--wpds-*, #fallback) now inlines to the token value (#707070) instead of the fallback.

No version skew — both halves source @wordpress/theme@0.13.0. Verified in the built admin.css: #87a6bc occurrences → 0, #707070 → 6. Phase 4 (retire legacy #dolly rules) is unaffected and still gated only on the central rule loading, which the audit already confirmed.