Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 68 ยท Block Themes and the Site Editor

Style Variations, Fonts and Design Tokens

Learn how block themes ship style variations, section styles, local fonts, fluid typography with clamp() and spacing scales, and how to build a dark variation.

A block theme describes its look as design tokens: named colors, font sizes, font families and spacing steps that live in theme.json. Once the tokens exist, a style variation can swap them for a different set, so the same theme can offer a light look, a dark look and a high-contrast look that the site owner picks in the Site Editor with one click. This lesson covers variations, section styles, self-hosted fonts, fluid typography and the spacing scale.

You should know the basics of theme.json from theme.json. Everything here uses the same schema, so a variation is simply another theme.json-shaped file that sits on top of the main one.

How variations are layered

Global styles are merged in layers: WordPress core defaults first, then your theme's theme.json, then the chosen style variation, and finally the changes the site owner saved in the Site Editor. Each layer overrides the one before it, key by key.

flowchart TB
    A["Core defaults"] --> B["Theme theme.json"]
    B --> C["Chosen style variation<br/>(styles/dark.json)"]
    C --> D["User changes saved in the Site Editor"]
    D --> E["Final CSS and custom properties"]

Later layers win. A variation only needs to list what differs from the main theme.json.

Writing a style variation

A variation is a JSON file in the theme's styles/ folder. It needs a title and the same version as the theme, and then only the settings or styles that change.

JSON
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Midnight",
	"settings": {
		"color": {
			"palette": [
				{ "slug": "base",     "name": "Base",     "color": "#0f1220" },
				{ "slug": "contrast", "name": "Contrast", "color": "#f2f4ff" },
				{ "slug": "accent",   "name": "Accent",   "color": "#7aa2ff" }
			]
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--base)",
			"text": "var(--wp--preset--color--contrast)"
		},
		"elements": {
			"link": { "color": { "text": "var(--wp--preset--color--accent)" } }
		}
	}
}

The trick that makes variations easy is that the main theme refers to colors by slug (var(--wp--preset--color--base)), never by hex value. The dark variation redefines what base and contrast mean, and every block that uses them changes with no further edits. If your theme hard-codes #ffffff in many places, a variation cannot recolor it; use presets everywhere.

A dark variation is exactly this idea: same slugs, swapped values. Check contrast while you choose them; text on the background should reach at least a 4.5:1 ratio. A variation does not have to change colors only: it can change fonts, spacing, block styles or even the layout widths.

Section styles

A variation restyles the whole site. A section style restyles one part of it. Section styles live in styles/sections/ and apply to a chosen block, usually a Group, so an author can pick "Inverted" for just one band of a page. A section style declares which blocks it supports:

JSON
{
	"version": 3,
	"title": "Inverted",
	"slug": "section-inverted",
	"blockTypes": [ "core/group" ],
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--contrast)",
			"text": "var(--wp--preset--color--base)"
		}
	}
}

Section styles can also restyle the blocks inside the section (headings, buttons, links), so one choice recolors a whole band consistently. Use them for repeated page rhythms such as alternating light and dark strips.

Fonts

Block themes can bundle fonts and declare them in theme.json, so there is no need to load them from a third-party server. Each family lists its font faces, and WordPress writes the @font-face rules for you.

JSON
{
	"settings": {
		"typography": {
			"fontFamilies": [
				{
					"slug": "body",
					"name": "Body",
					"fontFamily": "\"Source Sans\", sans-serif",
					"fontFace": [
						{
							"fontFamily": "Source Sans",
							"fontWeight": "400",
							"fontStyle": "normal",
							"fontDisplay": "swap",
							"src": [ "file:./assets/fonts/source-sans-regular.woff2" ]
						},
						{
							"fontFamily": "Source Sans",
							"fontWeight": "700",
							"fontStyle": "normal",
							"fontDisplay": "swap",
							"src": [ "file:./assets/fonts/source-sans-bold.woff2" ]
						}
					]
				}
			]
		}
	}
}

The file:./ prefix means "relative to the theme folder". Prefer WOFF2, the most compact format, and only ship the weights you really use; each file is a request. fontDisplay: "swap" shows fallback text immediately and swaps the font in when it loads, which avoids invisible text. Always give a sensible generic fallback in fontFamily. Self-hosting also helps privacy because visitors' browsers do not contact an outside font provider. The Site Editor's font library can install more fonts, but fonts in your theme.json ship with the theme and are reliable.

Fluid typography and clamp()

Headings that are perfect on a desktop are often too big on a phone. Fluid typography makes a font size grow smoothly with the viewport width, using the CSS clamp(min, preferred, max) function: the size is never below min, never above max, and in between it follows a value that depends on the viewport width in vw units.

You turn it on in theme.json and can set a range per size:

JSON
{
	"settings": {
		"typography": {
			"fluid": true,
			"fontSizes": [
				{ "slug": "medium", "name": "Medium", "size": "1.125rem" },
				{
					"slug": "x-large",
					"name": "Extra large",
					"size": "2.25rem",
					"fluid": { "min": "1.75rem", "max": "2.75rem" }
				}
			]
		}
	}
}

WordPress converts each size to a clamp() and exposes it as a custom property such as --wp--preset--font-size--x-large. By default the growth runs between a minimum viewport of about 320px and a maximum of about 1600px, and both ends can be tuned in the fluid settings. The math is a straight line between two points: at the minimum viewport the size is min, at the maximum viewport it is max.

The stand-in calculator below shows how such a rule is derived. It is not WordPress's own code, and the real output can differ in rounding and format, but the line-through-two-points idea is the same.

PHP A fluid font-size clamp calculator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice that at 960px the size is exactly halfway between 28px and 44px, and at 2000px it stops at 44px because of the max clamp. Fluid sizes need no media queries, which keeps your CSS small.

Keep the ratio between min and max moderate. A heading that doubles in size is usually too aggressive, and fluid text must still respect user zoom, which is why the limits use rem rather than px.

The spacing scale

Spacing works the same way as colors and sizes: you define named steps and refer to them everywhere. In theme.json, settings.spacing.spacingSizes holds a list of { slug, size, name } entries, and WordPress generates properties like --wp--preset--spacing--40. Using slugs such as 10, 20, 30, 40 keeps room to insert steps later.

JSON
{
	"settings": {
		"spacing": {
			"spacingSizes": [
				{ "slug": "20", "name": "Small",  "size": "0.5rem" },
				{ "slug": "40", "name": "Medium", "size": "clamp(1rem, 0.75rem + 1vw, 1.5rem)" },
				{ "slug": "60", "name": "Large",  "size": "clamp(2rem, 1rem + 4vw, 4rem)" }
			]
		}
	},
	"styles": {
		"spacing": { "blockGap": "var(--wp--preset--spacing--40)" }
	}
}

Spacing sizes may themselves be clamp() values, so the whitespace grows with the screen just like the text. A variation can override the spacing scale to produce a roomier or tighter version of the same design.

Practical advice

  • Name tokens by role (base, contrast, accent), not by appearance (dark-blue), so a variation can change the value without making the name a lie.
  • Put variations in styles/ and keep each focused; a variation that changes everything is really a new theme.
  • Test every variation with real content. A palette that looks good on a sample page can fail contrast on a link inside a quote.
  • Ship fewer font files rather than more; weight and style variants add up quickly.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where do style variations live in a block theme?

    Each variation is a theme.json-shaped file in styles/, with a title and the settings or styles that differ.
  2. 2. Why should a theme use color slugs instead of hex values in its styles?

    Because blocks reference var(--wp--preset--color--base), a variation only needs to change what base means.
  3. 3. What does clamp(1rem, 0.875rem + 0.625vw, 1.5rem) guarantee?

    clamp() keeps the middle value between the minimum and the maximum, so the size grows with the viewport but stays within limits.
  4. 4. What does the file:./ prefix in a fontFace src mean?

    file:./ points to a font file inside the theme, so the theme can ship its own fonts.
  5. 5. What is a section style?

    Section styles live in styles/sections/ and let authors restyle one block and its contents, for example an inverted band.

Summary

  • Design tokens (colors, font sizes, spacing) live in theme.json; variations in styles/*.json override them.
  • Layers merge in order: core, theme, variation, user changes.
  • Use slugs, not raw values, so variations such as a dark look need only swap values.
  • Section styles in styles/sections/ restyle a single block and its children.
  • Declare self-hosted fonts with fontFace, file:./ paths, WOFF2 and fontDisplay: "swap".
  • Fluid typography turns a size range into clamp(); the spacing scale can use clamp() too.
  • The calculator above is a stand-in for the idea, not WordPress's own implementation.

Next up: PHP in Block Themes.