Good afternoon, class. Today’s topic has a reputation for sounding intimidating: block themes and theme.json. Don’t worry. By the end of this lesson you’ll understand what they are, why they matter, and how to make safe, useful changes, even if you’ve never edited a theme file before.
What Is a Block Theme?
A block theme is a WordPress theme built entirely from blocks. Instead of PHP template files for headers and footers, it uses HTML files containing block markup. That means you can edit every part of your site, including headers, footers, archive pages and the 404 page, visually in Appearance → Editor (often called the Site Editor).
This approach is known as full site editing, and it’s been part of WordPress core since version 5.9. Default themes such as Twenty Twenty-Four and Twenty Twenty-Five are block themes, so they make excellent study material.
Professor’s note: Think of a classic theme as a pre-built house where you need a builder (code) to move walls. A block theme is more like a set of high-quality building blocks: you can rearrange rooms yourself.
The Anatomy of a Block Theme
A minimal block theme only needs a few files. A typical structure looks like this:
my-theme/
├── style.css (theme name, author, version)
├── theme.json (global settings and styles)
├── templates/
│ ├── index.html (required fallback template)
│ ├── single.html
│ └── page.html
├── parts/
│ ├── header.html
│ └── footer.html
└── patterns/ (optional reusable layouts)Templates
Templates define entire page types: single posts, pages, archives, search results. Each is an HTML file of block markup.
Template parts
Template parts are reusable sections, most commonly the header and footer, that templates pull in.
Block markup
Block markup is regular HTML with special comments that tell WordPress which block is which. For example, a template part reference looks like this:
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
<!-- wp:post-title /-->
<!-- wp:post-content /-->
</main>
<!-- /wp:group -->You rarely need to write this by hand. Build visually in the Site Editor and WordPress writes the markup for you.
What Is theme.json?
theme.json is the control centre for your theme’s design system. It’s a single configuration file that tells WordPress:
- Settings: which options appear in the editor, such as your colour palette, font sizes, spacing presets and layout widths.
- Styles: the default look of your site and of individual blocks and elements (like links, headings and buttons).
- Template parts and custom templates: names and areas so the editor can label them.
Here’s a small, simplified example:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"color": {
"palette": [
{ "slug": "primary", "color": "#1e3a8a", "name": "Primary" },
{ "slug": "accent", "color": "#f59e0b", "name": "Accent" },
{ "slug": "base", "color": "#ffffff", "name": "Base" }
]
},
"layout": {
"contentSize": "720px",
"wideSize": "1200px"
}
},
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "#1f2937"
},
"elements": {
"link": {
"color": { "text": "var(--wp--preset--color--primary)" }
}
}
}
}Notice the var(–wp–preset–color–primary) syntax? WordPress turns each palette entry into a CSS custom property, so you can reference it anywhere and update the colour in one place.
Tip: The $schema line enables autocomplete and validation in code editors like VS Code. It makes editing theme.json far less error-prone.
The Style Hierarchy: Who Wins?
Styles can come from several places, and WordPress layers them in order:
- Core defaults from WordPress itself.
- Theme settings from theme.json (a child theme’s theme.json can override its parent’s).
- User customisations made in Appearance → Editor → Styles, which are saved in the database.
Later layers win. That’s why changes you make in the Styles panel override the theme file, and why editing theme.json sometimes seems to “do nothing”: a user customisation may be taking priority.
Warning: If you edit a theme’s files directly, your changes will be overwritten the next time the theme updates. Use a child theme, or make changes in the Site Editor, which saves them separately in the database.
Safe Ways to Customise
No code: the Styles panel
For most site owners, Appearance → Editor → Styles is all you need. Change typography, colours and layout globally or per block, and browse any style variations your theme offers.
Low code: a child theme
A child theme can include its own theme.json that overrides only the parts you want to change. The Create Block Theme plugin, maintained by the WordPress community, can help you export your Site Editor changes into a child theme or a brand-new theme.
Full code: build your own
If you enjoy development, building a block theme from scratch is a great project. Our web development hub covers the details, and our vibe coding guides show how AI assistants can help draft templates and theme.json (always review what they produce).
Common Beginner Questions
Do I need to know JSON? Not to use a block theme. Only if you want to edit theme.json directly, and the syntax is simple: keys, values, commas and brackets.
Can I use a page builder with a block theme? Often yes, but mixing systems adds complexity. Many sites find the block editor alone is enough.
Where do I learn more? The official Theme Handbook on developer.wordpress.org is the authoritative reference, and our course has step-by-step lessons.
Homework
Open WordPress Playground, activate Twenty Twenty-Five, and change one colour and one font in Appearance → Editor → Styles. Then install the Create Block Theme plugin and look at the theme.json it generates. Can you find your changes in the file? Extra credit: browse our resources for starter theme examples.
