Font Management: Theme Fonts, Baked Fonts & Performance

WP Rig ships two complementary font pipelines: theme fonts (a Google Fonts download pipeline that works in every paradigm) and baked fonts (Site Editor Font Library assets persisted into the theme by rig:bake). Both are performance-tuned — automatic preloading, FOUT prevention, and asset inlining are built in. The one rule to remember: one home per font family.

Theme fonts: the Google Fonts pipeline

The inc/Fonts component localizes Google Fonts into your theme — no third-party requests at runtime:

  • Declare families through the wp_rig_google_fonts filter (or wp rig fonts-download on WP-CLI).
  • Files download to assets/fonts/<family>/; @font-face rules are generated in assets/css/src/google-fonts.css.
  • The CSS is enqueued on the frontend and in the editor, and is marked for inlining through the Asset_Provider system, cutting an initial HTTP request.

Font performance: preload + FOUT fix

  • Automatic preloading: component-managed fonts are preloaded via <link rel="preload"> so they arrive before the browser starts rendering.
  • Optimized display: localized fonts default to font-display: block, which waits for the font instead of flashing fallback text — eliminating the visual FOUT jump.
  • Preload discipline: the preload list is strictly scoped to families the component itself downloaded (marked by google-fonts.css). Font Library files that happen to live in the same directory are never preloaded — WordPress serves them through theme.json instead.

Baked fonts: the Site Editor layer

In block-based (and universal) themes, users can activate fonts from the Font Library in the Site Editor. rig:bake fonts persists those activations into the theme: files land in assets/fonts/<slug>/ (magic-byte validated), and the activation record goes into config/user-styles.json — merged into theme.json fontFamilies by rig:tokens. The Fonts component also registers Font Library collections (modern-stacks, local-fonts) so users can browse fonts in the editor in the first place.

Two layers, one home per family

LayerOwnerSource of truthOutput
Theme fonts (all paradigms)wp_rig_google_fonts filter + wp rig fonts-downloadGoogle Fonts listassets/fonts/ + google-fonts.css
Baked fonts (block-capable)Site Editor / Font Library + rig:bakedatabase activationsassets/fonts/<slug>/ + user-styles.json → theme.json
  • One home per family. If a family is in the Google Fonts list, serve it through the component CSS — don’t also bake the same family from the Font Library. Same in reverse.
  • After baking, baked families win in the editor. The user-styles overlay replaces the token-derived fontFamilies list in theme.json wholesale. Frontend styling is unaffected — token CSS variables keep working. Re-bake after token font changes, or run rig:bake:clean to re-home families to tokens.
  • Removing baked fonts: remove the family in the editor’s Font Library and re-bake. Deleting the files manually leaves orphan references in the overlay.

Typography tokens

Font usage (sizes, line heights, family roles in your design system) is owned by the token system — see Design Tokens v2. The pipelines above decide which font files ship and how they load; config/tokens.json decides how they are used.

Site Editor Bake & Sync covers the bake workflow; Theme Configuration covers the config layer both pipelines read from.