Building a WordPress Block Theme: Templates, Styles, and Accessibility
A WordPress block theme lets developers and site owners use blocks to edit every part of a site, including shared areas such…
In a WordPress block theme, blocks build page layouts and templates define each page’s structure. The theme.json file gives WordPress one place to read the theme’s design defaults and choose which design controls to show in the Site Editor. It also sets design options and styles that WordPress uses in the editor and on the site.
The file is optional, but it helps you set shared choices such as colors, font sizes, and content widths. Its main sections have different jobs: settings controls the options editors can use, while styles sets the default appearance. Together, they keep a theme consistent while leaving site owners room to customize it.
theme.json controlsPut theme.json in the theme’s root directory. WordPress reads its settings alongside the theme’s templates and stylesheets. A block theme works without this file; the Theme Handbook’s introduction explains how the file configures theme settings and styles.
Templates and template parts define page structure. theme.json configures design options and related metadata. The theme structure documentation explains how these files fit into a block theme.
Use settings to choose which options WordPress shows. For example, you can select a color palette or set preset font sizes. Use styles to set default colors and typography, along with other supported visual rules. A control appears for a block only if that block supports the feature.
settingsA setting can offer a design choice or define a reusable preset (a named value, such as a color or font size). It can also limit which values users can enter. For example, a theme can offer its own palette and disable custom colors. The color settings documentation describes these controls separately. Decide whether to restrict the palette, custom colors, or both.
Presets give named design values that can be reused. A color with the slug brand, for example, becomes available through a generated CSS custom property:
var(--wp--preset--color--brand)
A CSS custom property stores a named value that styles can reuse instead of repeating the color. Presets keep recurring values consistent, and WordPress makes them available to the editor and theme styles. The WordPress global styles documentation explains how presets become CSS variables.
Layout settings define the theme’s default content width and a wider width for aligned blocks. The wider value lets those blocks extend beyond the standard content width when the surrounding layout supports it. The appearanceTools setting turns on a group of design controls. Enable it only if those controls fit the theme. See the layout settings reference for available options.
stylesStyles can apply to the whole page, common elements such as headings and links, or individual blocks. A global text color sets the page’s starting color. A rule for an element or block adds a more specific style. To style a block, use its namespace and name, such as core/button or core/image. WordPress explains these levels in its styles application reference.
Here is a compact example for a theme that requires WordPress 6.6 or later:
{
"$schema": "https://schemas.wp.org/wp/6.6/theme.json",
"version": 3,
"settings": {
"appearanceTools": true,
"layout": {
"contentSize": "42rem",
"wideSize": "68rem"
},
"color": {
"palette": [
{
"slug": "ink",
"name": "Ink",
"color": "#202124"
},
{
"slug": "paper",
"name": "Paper",
"color": "#f7f5f0"
},
{
"slug": "brand",
"name": "Brand",
"color": "#2457a6"
}
]
},
"typography": {
"fontSizes": [
{
"slug": "small",
"name": "Small",
"size": "0.9rem"
},
{
"slug": "large",
"name": "Large",
"size": "2rem"
}
]
}
},
"styles": {
"color": {
"text": "var(--wp--preset--color--ink)",
"background": "var(--wp--preset--color--paper)"
},
"typography": {
"fontSize": "1rem",
"lineHeight": "1.6"
},
"blocks": {
"core/button": {
"color": {
"text": "#ffffff",
"background": "var(--wp--preset--color--brand)"
}
}
}
}
}
settings defines palette choices, font-size presets, and layout widths. styles sets the page’s text and background with palette variables and gives the Button block a brand-color background. Changing the brand color in the palette updates the button background.
The version field tells WordPress which theme.json format to read. The $schema field points to a description of the file’s expected structure, which helps code editors check the file and offer suggestions. For a new theme targeting WordPress 6.6 or later, the living reference identifies version 3 as supported. Choose a schema that matches your theme’s minimum WordPress version instead of copying the example for a theme that supports older releases. The version 3 FAQ explains the difference between the format version and the schema.
Theme styles set the starting defaults, and site owners can change them in the Site Editor. WordPress applies styles saved by the user over theme defaults. So changing theme.json does not necessarily replace customizations already saved for a site. The global settings and styles overview explains how WordPress combines its defaults with theme, child-theme, and user styles.
After editing the file, check the Site Editor and the front end of the site. Confirm that the intended controls appear, then compare the page with the theme defaults. If the page looks different, check saved Styles customizations before changing the theme rules.
theme.json does not covertheme.json supports WordPress’s standard design settings and style properties, but it does not replace stylesheets. Use a stylesheet when you need selectors or behavior that these properties do not cover. WordPress also lets you add custom CSS through its styles system. The styles reference documents the available options.
Use presets and global styles for shared design values. Add rules for specific elements or blocks when needed. This keeps the editor’s options aligned with the theme defaults and leaves CSS for more specialized design work.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com