Theme.json Font Sizes

Standardizing across Themes

This is part two, of three, in a series on standardizing how we build this next generation of WordPress block themes to accompany the Full Site Editing effort.

If you like this article on font sizes, read on about standardizing color slugs, and standardizing site spacing. Each of these are what I would consider core design tenets of a website, of which should be functionally standardized. By standardizing a few entries within a WordPress theme’s theme.json file, we can finally create a class of themes that truly are interchangeable. Interchangeable in function, while remaining distinct in style.

Here’s a take on why this is important, and how we can get there.

How theme font sizes are generated from the theme.json file

When a font size is applied to a Gutenberg block, a class is added to the component, consisting of .has-font-size-(property). So here’s how you extend font sizes with theme.json, using what I’d say should be the standard fontSizes that every block theme should account for:

"settings": {
    "typography": {
	"fontSizes": [
			"name": "Small",
			"fluid": {
				"min": "0.875rem",
				"max": "1rem"
			"size": "1rem",
			"slug": "small"
			"name": "Medium",
			"fluid": {
				"min": "1rem",
				"max": "1.125rem"
			"size": "1rem",
			"slug": "medium"
			"name": "Large",
			"fluid": {
				"min": "1.75rem",
				"max": "1.875rem"
			"size": "1.875rem",
			"slug": "large"
			"name": "Extra Large",
			"fluid": {
				"min": "1.875rem",
				"max": "2.25rem"
			"size": "2.25rem",
			"slug": "x-large"

The theme.json resolver creates the CSS classes with the appropriate value, along with the necessary CSS custom properties within the block editor and on the front-end. The output looks something like this below:

body {
  --wp--preset--font-size--small: 0.8rem;
  --wp--preset--font-size--medium 1rem:
  --wp--preset--font-size--large: 1.25rem;
  --wp--preset--font-size--x-large: 1.563rem;

.has-small-font-size {
    font-size: var(--wp--preset--font-size--small) !important;

.has-medium-font-size {
    font-size: var(--wp--preset--font-size--medium) !important;

.has-large-font-size {
    font-size: var(--wp--preset--font-size--large) !important;

.has-x-large-font-size {
    font-size: var(--wp--preset--font-size--x-large) !important;

This is great — as now themes don’t have to manually declare a set of CSS classes to cover font sizes and colors. But there is one caveat…

Why standardization matters

If you switch to a different block theme, those specific font size are no longer generated — resulting in content that no longer is styled appropriately. To illustrate this hiccup — and the purpose behind standardizing these font size slugs — check out what happens when switching between the TT1 Blocks and Quadrat block themes.

To illustrate this, I’ve added paragraph blocks to the page, each with a corresponding font size assigned to it. The TT1 Blocks theme has a gigantic font size slug, but uses extra-small instead of tiny. Quadrat ignores both of those font sizes, resulting in both the “Gigantic” text and the “Tiny” text displaying as normal paragraph text. And this gets worse as the number of font size slugs that map in settings.typography.fontSizes is lower. This is not a fantastic experience. In fact—it’s destructive.

As WordPress developers, we should encourage the democratization of publishing… even if that means making it easy for folks to switch away from your products.

Suggested font size slugs

Just because block themes should include these six font size options, does not mean all of the values in each block theme are the same across all themes. That saying, here are the settings.typography.fontSizes slugs that I propose should be included in each block theme (at least):

  • small
  • medium
  • large
  • x-large

You could easily use the Type Scale tool to scale the typography appropriately, or come up with a clever scaling system in the theme itself — but ideally, each of these font sizes should be accounted for in the theme.json file.

What are block themes doing today?

A lot of block themes are actually close to this standard already. Others, not so much — even core WordPress themes have not landed on a standard yet. Here’s a look at some of the leading block themes and how they are registering font sizes:

  • BlockBase has most of these font sizes, but is missing extra-large and gigantic. The hierarchy is broken, skipping extra large entirely — jumping from large to huge
  • Aino uses its own t-shirt style font size system, resulting in none of the font sizes translating to and from other themes. I think using the t-shirt labels is interesting, but the actual slugs should still be mapped accordingly
  • Anariel Design’s beautiful Naledi and Clove themes are looking good, but are both using extra-small instead of tiny
  • Quadrat is close; just missing the gigantic font size
  • TT1-Blocks is nearly there; using extra-small instead of tiny

Just from looking at the leading theme.json based block themes, there is nearly a standard. But still, if you switched between any of these, and happen to have used font sizes within the editor, you will have text that is no longer sized the way you intended.

What’s your take?

And as we continue to move towards more block and pattern-based site building, we should encourage themes to act more as a coat of design, not a system of “locked-in” design components that break once you change a theme. If we can create themes that don’t require folks to double-back on every page they’ve ever published, we’ll foster a much deeper level of empowerment across WordPress publishing. I am excited about the potential this new paradigm of WordPress themes brings to the site building and editing experience. Combined with the Global Styles effort, Block Themes make WordPress personal again.

If you like this article on colors, read the others in this standardization series covering color slugs and site spacing.

%d bloggers like this: