Fix #54: adopt wp-admin native scheme accent at runtime (and live preview)

[lucasmendes-design]

Fixes #54. Linear: DES-640. Off trunk directly — no stack dependencies.

Summary

May 2026 usability testing surfaced three related visual issues with the redesigned sidebar:

1. Multiple hand-picked blues (#71aee2, #3858e9) inconsistent with wp-admin's native palette.
2. Save CTA hard to read on the previous saturated #3858e9 background.
3. 'SF Pro Text' font silently falling through to Helvetica everywhere except Apple platforms.

On top of those, the sidebar accent had no awareness of wp-admin's colour-scheme system — switch from Default to Sunrise / Midnight / Ectoplasm and the rest of admin recoloured while our sidebar stayed stuck on the Fresh blue.

Approach

Read wp-admin's actual scheme highlight at runtime instead of hard-coding hex values for each scheme. The CSS keeps two accent tokens with Fresh-scheme defaults; a small JS module probes .button-primary's computed background-color (the canonical scheme highlight wp-admin uses) and writes the real value into both tokens at boot. Works for every built-in scheme AND any third-party scheme registered via wp_admin_css_color().

Live preview

On the Profile screen the colour-picker can swap schemes without saving. WP's color-picker.js updates <link id=\"colors-css\">'s href attribute — that's the single point every click target (radio, label, swatch) funnels through. A MutationObserver on that attribute catches every variant and re-probes after a setTimeout(100) so the new stylesheet has been applied.

Why not just listen to radio change

An earlier revision did exactly that and turned out to be the bug source: WP's color-picker.js sets radio.prop('checked', true) from a .color-option click handler, and a programmatic jQuery prop() does NOT fire change. So clicks on the wrapper / label / swatch silently bypassed the listener. Watching the stylesheet swap is the single trigger that catches every UI path.

Why not just hard-code per-scheme values in CSS

An earlier revision tried body.admin-color-{scheme} overrides with extracted hex values. Two problems:

• Duplicates values from wp-admin/css/colors/<scheme>/colors.min.css that would drift over time.
• Silently mismatches third-party schemes registered via wp_admin_css_color().

What changed

• src/browse-rail/styles.css — drop 'SF Pro Text' from the font stack (use wp-admin's native system stack). Token defaults updated to Fresh-scheme actuals (#2271b1). Comment block at top rewritten to describe the runtime-token approach.
• src/browse-rail/color-scheme-preview.js (new) — applyColorSchemePreview() exported, called from bootstrap. Probes .button-primary once on load, then MutationObserver re-probes after each colors-css href swap.
• src/browse-rail/browse-rail.js — dynamic import of the new module + call from bootstrap.
• wp-admin-sidebar.php — new file in the \$bust_sources array so its mtime feeds the cache-bust query.

Manual verification

Local Studio site (PHP 8.4 / WP 6.9.4, SQLite). Verified across saved and preview states on all nine built-in admin colour schemes.

• Saved state: switch admin colour scheme via Users → Profile → Update Profile, reload. The MY PLUGINS label, customize icon, chevron, Save button background, focus rings, and drag indicator all match the scheme's highlight (Sunrise → #dd823b orange; Midnight → #e14d43 red; Modern → #3858e9 purple-blue; etc.).
• Preview: on Profile, click any colour-option (radio, label, or swatch). Every click path correctly retints the redesigned sidebar within ~100ms — same trigger handles all three.
• Font: typography on the group header reads as part of the native sidebar (no more 'SF Pro Text' fallthrough).
• Save button: previous #3858e9 (which testers called "hard to read") replaced with the scheme's primary action colour — #2271b1 in Fresh, matching .button-primary everywhere.

Tests

JS-only logic + CSS values. No existing test asserts the scheme-driven token values (they're runtime). PHP suites not run locally (Studio's PHP is WASM-only); CI gates the rest.

🤖 Generated with Claude Code