Tutorial: building a theme renderer, the Twenty Twenty-Five way

This tutorial walks through how the Twenty Twenty-Five renderer was built, in the order it was built, so you can repeat the process for another theme. Every step names the real files in the renderer package, a check that proves the step works, and the result it had on Twenty Twenty-Five.

You need: the Flx Modernize plugin, the Twenty Twenty-Five renderer package, Node.js 22, PHP 8, a GitHub account (the checks run on GitHub Actions), and a disposable WordPress test site. Never measure or experiment on a live site.

The header (step 4) moved the score only from 75.4% to 76.1%, but it lined up every page below it.

The one idea behind every step

Render the theme's own markup and let the theme's own CSS style it. WordPress already computes the theme's complete stylesheet (global styles), and the plugin hands the renderer a link to it. If the renderer outputs the same block markup the theme uses (wp-block-group, wp-block-navigation, has-global-padding, …), that stylesheet styles it exactly as on a native page. Writing new CSS to imitate the theme is slower and drifts.

How the steps are verified

Each change goes through the same loop: branch → CI run (fidelity score + safety check) → pull request → merge → automatic deploy → live check. The fidelity gate fails the CI run if the score drops, so a step can only move forward.