From b066d5022aa444171ebe5054fce92f28ef47944b Mon Sep 17 00:00:00 2001 From: Dan Knauss <273554+dknauss@users.noreply.github.com> Date: Fri, 21 Aug 2026 13:08:10 -0600 Subject: [PATCH] docs(compat): close WP71-02 by measuring 7.1's design tokens MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WP71-02 asked for a decision on adopting 7.1's --wpds-* tokens. Measured it instead of arguing it: wp-env on 7.1.1-alpha-63326, driven through the existing e2e auth harness, reading computed values off :root across five admin colour schemes. Zero of 167 tokens track the admin colour scheme, while the menu surface Maestro draws on does. The palette is also Gutenberg's rather than classic wp-admin's, so every value is a near-miss (#fcfcfc vs #fff, #1e1e1e vs #1d2327, #3858e9 vs #2271b1). Staying hardcoded keeps its conclusion and gains a live reason. WP71-03 half closes on the same run. Phase 25's 6.74:1 and 9.11:1 reproduce exactly, because they were always measured against Maestro's own #1d2327 rather than core's sidebar — a correction to how that entry was framed. Adds the five-scheme figures for chrome on the real menu surface, which had never been measured. Core's own --wpds-color-stroke-focus turns out to fail 1.4.11 on every scheme (2.83:1 down to 1.46:1) where Maestro's #72aee6 passes all five, so adopting it there is contraindicated rather than safe. Also corrects two claims the file outlived: #159 and #157 are merged, not open. Co-Authored-By: Claude Opus 5 --- .planning/STATE.md | 16 ++- .planning/compat/WP-7.1-COMPAT.md | 188 ++++++++++++++++++++++-------- 2 files changed, 151 insertions(+), 53 deletions(-) diff --git a/.planning/STATE.md b/.planning/STATE.md index 83e379c..8f42ebb 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -512,11 +512,17 @@ Recent decisions affecting current work: (#156: the persistent 7.1 toolbar made the Edit Menu toggle reachable in the Post and Site Editors; guard keys on FULLSCREEN, not the screen, because with fullscreen off the Post Editor still shows the menu and Maestro works there). - Three open: **WP71-02** Phase 23's "no admin CSS variables exist" rationale - expired against 7.1's `--wpds-*` tokens (99 hardcoded hex, 0 `var(--)` — wants a - decision, not a fix); **WP71-03** Phase 25's contrast ratios were measured against - 7.0 and #65382 moved the sidebar palette; **WP71-04** #65250 fixed collapsed-menu - cursor behaviour inside Phase 28-01's work area — read it before, not after. + **WP71-02 is CLOSED** (2026-08-21, by measurement on a running `7.1.1-alpha-63326`: + zero of 167 `--wpds-*` tokens track the admin colour scheme, while the menu surface + Maestro draws on does — and the token palette is Gutenberg's, not classic wp-admin's. + Staying hardcoded now has a live reason rather than a stale one; core's own + `--wpds-color-stroke-focus` would in fact have been an accessibility regression on the + dark surfaces, failing 3:1 on all five schemes). **WP71-03 is half-closed** — Phase 25's + 6.74:1 and 9.11:1 reproduce exactly, because they were always measured against + Maestro's own `#1d2327`, not core's sidebar; the untested half is core's own focus-state + changes (#65645, #65765, #65726). Two open: **WP71-03**'s focus-state half, and + **WP71-04** #65250 fixed collapsed-menu cursor behaviour inside Phase 28-01's work + area — read it before, not after. - **Human screen-reader pass on the person picker** — consolidates the two surviving v1.5.0 caveats into one task (21-05 Task 5 is struck as superseded by Phase 25's human pass). axe is clean and still passing, which is not the same diff --git a/.planning/compat/WP-7.1-COMPAT.md b/.planning/compat/WP-7.1-COMPAT.md index 654b003..eb801ea 100644 --- a/.planning/compat/WP-7.1-COMPAT.md +++ b/.planning/compat/WP-7.1-COMPAT.md @@ -1,8 +1,10 @@ # WordPress 7.1 — compatibility register **Opened:** 2026-08-18 -**Maestro baseline:** v1.5.2 (shipped), `main` at `68f7d6f` -**7.1 status at time of writing:** RC (CI has run against a real `7.1-RC4-63322` build) +**Last updated:** 2026-08-21 — WP71-02 closed and WP71-03 half-closed by measurement on `572f472` +**Maestro baseline at opening:** v1.5.2 (shipped), `main` at `68f7d6f` +**7.1 status at opening:** RC (CI had run against a real `7.1-RC4-63322` build); the +2026-08-21 measurements were taken on `7.1.1-alpha-63326` This file exists because `#156` introduced the **`WP71-nn`** identifier in code comments and there was nowhere for `WP71-02` onward to land. It is the registry @@ -119,46 +121,126 @@ Three known violations, only one of them 7.1-related — see `todos/pending/2026-08-18-mobile-edit-mode-does-not-open-the-menu.md` for the third, which is pre-existing and has the *opposite* answer. -### ◻ WP71-02 — the "no admin CSS variables exist" rationale has expired +### ✅ WP71-02 — the rationale expired; the conclusion survives, for a better reason -**Open. Not urgent; nothing breaks.** - -Phase 23 recorded that Maestro's panel/toolbar colours stay hardcoded because *no -WP admin-colour-scheme CSS variable exists for a custom-drawn surface to inherit*. -That was true when written. 7.1's `--wpds-*` tokens make it false. - -Measured on `68f7d6f`: **99 hardcoded hex values in `assets/maestro.css`, zero -`var(--)` usages, zero `wpds` references** across both stylesheets. - -Nothing is broken — hardcoded colours still render. What changed is the *reason*: -a plugin whose stated aim is looking native to wp-admin now has a supported way to -actually be native, and its recorded justification for not doing so no longer -holds. Any adoption must stay back-compatible to the 6.4 floor (`var(--wpds-x, #hex)` -fallbacks), which is also what makes this safe to do incrementally rather than as -a sweep. - -**Blocked on nothing. Wants a decision, not a fix:** adopt tokens progressively, -or record a *current* reason for staying hardcoded. Either is fine; the stale -rationale is the actual defect. - -### ◻ WP71-03 — Phase 25's contrast ratios were measured against 7.0 - -**Open. Low risk, cheap to settle.** - -#65382 boosted sidebar contrast in the admin colour schemes. Phase 25 measured and -recorded specific ratios against 7.0 values — the focus ring at **6.74:1** on -`#1d2327`, toolbar glyphs `#c3c4c7` at **9.11:1** — and chose `#72aee6` -deliberately as a robustness margin over a value that passed by 0.07. - -Those numbers are almost certainly still fine, and may well have improved. But -they are currently *asserted* against a palette core has moved. Re-measure against -7.1 and update `25-VERIFICATION.md` with the new figures, or note that they were -re-checked and held. - -Related and unexamined: core standardising focus indicators to ≥2px (#65645) and -improving focus states on the admin bar and admin menu (#65765, #65726). Maestro -draws its own 2px ring on its own toolbar, so this is likely alignment rather than -conflict — but "likely" is not "checked". +**Closed 2026-08-21 by measurement.** Read on `572f472` (v1.5.3) against a running +`7.1.1-alpha-63326` wp-env instance. First entry in this file backed by observation +rather than by reading a dev note. + +Phase 23 recorded that Maestro's colours stay hardcoded because *no admin-colour-scheme +CSS variable exists for a custom-drawn surface to inherit*. That **wording** is now +false: 7.1 puts **167 `--wpds-*` custom properties on `:root`**, and `wp-theme` is both +registered *and* enqueued by default on admin screens (`wp_style_is()` true for both). + +The **conclusion** survives anyway, on two findings the dev note does not state. + +#### 1. The tokens are scheme-blind. The surface Maestro draws on is not. + +| Scheme | `#adminmenuwrap` | current item | `--wpds-…-surface-neutral` | `--wpds-color-stroke-focus` | +|---|---|---|---|---| +| fresh | `rgb(29,35,39)` | `rgb(34,113,177)` | `#fcfcfc` | `#3858e9` | +| midnight | `rgb(51,60,66)` | `rgb(207,67,57)` | `#fcfcfc` | `#3858e9` | +| ocean | `rgb(57,83,90)` | `rgb(86,121,88)` | `#fcfcfc` | `#3858e9` | +| sunrise | `rgb(138,49,45)` | `rgb(173,99,30)` | `#fcfcfc` | `#3858e9` | +| coffee | `rgb(92,76,64)` | `rgb(145,103,69)` | `#fcfcfc` | `#3858e9` | + +**Zero of 167 tokens changed value across all five schemes.** Scheme-following was the +entire prize in adopting them, and it is not on offer: a token cannot make +menu-adjacent chrome native to a scheme it has no knowledge of. The `#adminmenuwrap` +subtree does not re-scope the tokens either — it reports root's `#fcfcfc`, i.e. the +light-canvas value, on a surface that is dark in every scheme. + +#### 2. The palette is Gutenberg's, not classic wp-admin's. + +Every value is a near-miss against what Maestro already uses: + +| Role | wpds | Maestro now | contrast between the two | +|---|---|---|---| +| card surface | `#fcfcfc` | `#fff` | 1.03 | +| body text | `#1e1e1e` | `#1d2327` | 1.05 | +| brand / accent | `#3858e9` | `#2271b1` | 1.09 | +| stroke | `#dbdbdb` | `#c3c4c7` | 1.26 | +| secondary text | `#707070` | `#50575e` | 1.48 | + +Adopting these would not align Maestro with the classic screens it draws on — it would +align it with the **editor**, by a margin too small to read as deliberate. Of the three +available outcomes (match, differ clearly, almost-match), near-miss is the worst. + +#### Decision: stay hardcoded — and this is now the recorded reason + +Not "no variables exist" but: *the tokens describe a different design language than the +surface this plugin draws on, and they are scheme-blind where that surface is +scheme-aware.* That is a live justification rather than a stale one, which is what this +entry was opened to obtain. Revisit if core ever seeds `--wpds-*` from the admin colour +scheme — that single change would reverse the decision. + +**`ThemeProvider` is separately out of scope.** It is a React component from +`@wordpress/theme`; Maestro has no React and no build step (`class-assets.php:113` +enqueues hand-written JS). It also exists so a plugin can express *brand identity*, +which is the inverse of this plugin's premise. + +**Worth taking opportunistically** — the non-colour scales, when that CSS is open for +another reason. `--wpds-border-radius-*` is `1/2/4/8/12px`, and Maestro's `3px` is off +that scale entirely; `--wpds-cursor-control` covers the six `cursor: pointer` sites but +**not** the deliberate `cursor: default` ones (`maestro.css:238`, where the absent hand +cursor *is* the design). These are static too — adoption buys alignment with core's +scale, not the following of a user setting. + +**If any of it is adopted, guard the dependency:** test +`wp_style_is( 'wp-theme', 'registered' )` before appending it. `WP_Dependencies` drops +an item whose dependency is unregistered, so an unguarded +`array( 'dashicons', 'wp-theme' )` would mean `maestro.css` does not print **at all** on +the 6.4–7.0 floor. + +### ◻ WP71-03 — Phase 25's ratios re-measured against 7.1: they hold + +**Ratio half closed 2026-08-21. Focus-state interaction half still open.** + +Phase 25's two recorded figures reproduce **exactly** under 7.1 — focus ring `#72aee6` +at **6.74:1**, toolbar glyphs `#c3c4c7` at **9.11:1**. + +They were never at risk, and the reason is worth recording because this entry was +framed slightly wrong when it was opened: both were measured against **Maestro's own** +`#1d2327` toolbar background (`maestro.css:536`), not against core's sidebar. #65382 +moved core's palette; it cannot move a colour Maestro hardcodes for itself. + +What *does* vary by scheme is the chrome Maestro draws on the **real** menu surface. +Those ratios had never been measured on any version: + +| Scheme | menu surface | `#c3c4c7` text (needs ≥4.5) | `#72aee6` ring (needs ≥3) | +|---|---|---|---| +| fresh | `#1d2327` | 9.11 ✅ | 6.74 ✅ | +| midnight | `#333c42` | 6.45 ✅ | 4.78 ✅ | +| ocean | `#39535a` | 4.71 ✅ | 3.48 ✅ | +| sunrise | `#8a312d` | 4.71 ✅ | 3.48 ✅ | +| coffee | `#5c4c40` | 4.70 ✅ | 3.48 ✅ | + +All pass on all five. `ocean`, `sunrise` and `coffee` sit within **0.0003** relative +luminance of one another (0.07795 / 0.07789 / 0.07814) — which is why a single +dark-surface choice covers three schemes at once. That is robustness Maestro already +had and had not recorded. + +#### Core's own focus token would have been a regression + +`--wpds-color-stroke-focus` (`#3858e9`) against the menu surface: **2.83:1** on fresh, +**2.00:1** on midnight, **1.46:1** on the other three — under WCAG 1.4.11's 3:1 floor on +**every** scheme. Phase 25 chose `#72aee6` as a robustness margin over a value that +passed by 0.07; it now also beats the token core ships. Adopting +`--wpds-color-stroke-focus` on Maestro's dark surfaces is specifically contraindicated, +which is the opposite of the assumption that core's token is the safer default. + +#### Still open + +The `#3c434a` divider (`maestro.css:651`) is hardcoded against a scheme-aware +background — 1.12–1.58:1 across the five. **Not** a 1.4.11 failure: a subtle zone +divider is decoration, and the comment there says subtle is the intent. But it is cool +grey against `sunrise`'s red and `coffee`'s brown, which is a hue question rather than a +contrast one, and it is unexamined. + +**Also unchanged:** core standardising focus indicators to ≥2px (#65645) and improving +focus states on the admin bar and admin menu (#65765, #65726). Maestro draws its own 2px +ring on its own toolbar, so this is likely alignment rather than conflict — none of it +was exercised by the probe, so "likely" is still not "checked". ### ◻ WP71-04 — #65250 lands inside Phase 28's work area @@ -176,7 +258,7 @@ first is cheap insurance against designing around a bug core has already fixed. ## What the green 7.1 suite does and does not prove -[#159](https://github.com/dknauss/Maestro/pull/159) (open, CI green, and built on +[#159](https://github.com/dknauss/Maestro/pull/159) (merged as `0e3b45e`, CI green, built on top of the WP71-01 guard) declares `Tested up to: 7.1` and moves the wp-env pin to `#7.1-branch`. Its backing is real: the full suite ran against `7.1-RC4-63322` — unit 167, JS 83, integration 129, e2e 56, phpcs and PHPStan clean. @@ -197,8 +279,8 @@ on re-run. The suite shares one WordPress instance and one option row, which `tests/e2e/fixtures.ts` already documents as an isolation hazard. It will bite CI eventually and is worth its own todo. -**Also open, and unrelated to 7.1:** [#157](https://github.com/dknauss/Maestro/pull/157) -(dependabot, `@axe-core/playwright` 4.12.1 → 4.13.0). +**Landed since, and unrelated to 7.1:** [#157](https://github.com/dknauss/Maestro/pull/157) +(dependabot, `@axe-core/playwright` 4.12.1 → 4.13.0) merged as `ffc83ed`. --- @@ -206,7 +288,17 @@ eventually and is worth its own todo. - Items 1–3 in the changes table are read from the linked dev notes. - WP71-01's implementation is read from `68f7d6f`'s diff. -- WP71-02's counts are measured on `68f7d6f`. -- **Nothing here was observed running under 7.1 by the author of this note.** - #159's suite run is the only runtime evidence in the file, and it is quoted from - that PR rather than reproduced. +- WP71-02's original hex/`var()` counts were measured statically on `68f7d6f`, and + re-derived unchanged on `572f472` (99 hex, 0 `var(--)`, 0 `wpds` in + `assets/maestro.css`): `grep -oE '#[0-9a-fA-F]{3,8}\b' assets/maestro.css | wc -l`. +- **WP71-02 and WP71-03 were observed running under 7.1** on 2026-08-21, on `572f472`: + a wp-env instance on `7.1.1-alpha-63326`, driven with Playwright through the existing + e2e auth harness, reading computed `--wpds-*` values off `:root` and computed + backgrounds off `#adminmenuwrap` across five admin colour schemes. Contrast figures + are derived from those measured values with the WCAG 2.x relative-luminance formula, + not read from a source. Two caveats: the build is `7.1.1-alpha`, slightly ahead of + 7.1.0, so specific hex values could still move — the structural findings + (scheme-blindness, Gutenberg palette) would not. And **the probe was a throwaway spec, + not committed**, so re-running it means rewriting it; if these figures are ever load + bearing again, that spec should land env-gated like the capture specs. +- **Everything else here is still unobserved.** WP71-04 and WP71-05 are read, not run.