Step 1: Measure first

Before changing any markup, build the instrument that tells you whether a change helped. Without it you will polish what you notice, not what costs the most.

What to build

A check that, for each test page, takes two full-page screenshots of the same URL on the same WordPress: once as WordPress renders it (native) and once through Flx. It then compares them pixel by pixel, on a desktop and a phone viewport.

In the package this is the validation harness in tests/validation/:

A reference fixture (tests/fixtures/reference-fixture/) seeds a throwaway WordPress with pages covering the theme's blocks: text, media, layout, dynamic blocks, embeds and typography, plus sample posts.
Capture (Playwright, Chromium) takes native.<viewport>.png and headless.<viewport>.png per page. For the native shot it sends a secret header that a CI-only mu-plugin (tests/mu-plugins/flx-ci-native-render.php) turns into flx_modernize_should_render = false.
Compare (pixelmatch, threshold 0.1) counts differing pixels. The match is 100 − diff%.

Two rules that keep the number honest

Pad mismatched heights with an opaque colour (magenta), not transparent. If one page is taller, the extra rows must count as different. With transparent padding, missing content was blended onto white and counted as matching, which overstated the first measurement by about 15 points.
Measure on a throwaway site in CI, never on a live site: the run seeds content, flips plugins and hammers pages.

Read where the difference is, not just how big

The single average hides the cause. Split each page's differing pixels into bands: header (top 150 px), body, footer (last 700 px), and rows only one page has. On Twenty Twenty-Five the first measurement looked like this:

	Desktop	Phone
Total difference	39.4%	41.7%
Rows only the native page has	32.1	28.1
Footer band	4.5	7.5
Body	2.6	5.4
Header	0.3	0.8

Most of the loss was height: Flx pages were far shorter than native ones. That one table decided the order of steps 4–6: the tall theme footer first, then the spacious post lists, then the 404 template.

Gate it

Once you have a baseline, make CI fail when the score drops (ci/check-fidelity.mjs, run as the "Fidelity gate" step). Name the compared pages explicitly: some pages are captured but never compared, so counting folders gives false alarms.

Check: a CI run produces a per-page table, and changing a threshold above the current score makes the run fail.

← Tutorial: building a theme renderer, the Twenty Twenty-Five way Step 2: Connect plugin and renderer →

Published from rickey29/twenty-twenty-five at commit 2541c1d · Flx Modernize 1.0.0 · Flx Render 1.0.0