Style Variations and Section Styles

Every .json file in the theme’s styles/ folder, including subfolders, is read as a theme.json partial. The file carries version, an optional title (the file name is used without one), and the settings and styles to apply on top of the theme’s own theme.json. A variation does not need to repeat anything it does not change; it is merged over the theme’s data in the same way the theme’s data is merged over the core defaults. The theme’s theme.json itself is the "Default" entry of the list.

The decision of what kind of variation a file is follows two rules, both visible in the WordPress source:

The Lumen files used on this page:

Source: Theme Handbook: Style Variations

The variations below only make sense against the base palette, so here is the part of lumen/theme.json they rely on (the complete file, with layout, spacing and fluid type, is built in theme.json Settings). The styles.blocks entry at the end customizes the section style for one block type and is explained in Overriding a section style per block type.

Source: Block Editor Handbook: Theme.json Reference (version 3)

The most useful habit for variations is visible here: styles refer to palette slugs, never to hex values. A variation then only has to redefine the colours behind the slugs, and every style, block and pattern that uses paper or ink follows. A variation that introduces new slugs instead leaves blocks that saved the old slugs with no colour at all.

"Paper" is the print look: pure white, black text, underlined links that lose the underline on hover, and lighter headings. It keeps every slug and only changes the values.

Source: Theme Handbook: Style Variations

"Midnight" is the dark look. Because the base styles say "background is paper, text is `ink`", swapping the two values is enough to invert the whole site; the file then adds what only the dark look needs: the sans-serif font, filled buttons and a coloured rule on quotes.

Source: Theme Handbook: Style Variations

The slugs keep their names in Midnight even though paper is now dark: variations may change preset values but must never rename slugs, or content that saved them loses its colours. Check the contrast of each variation’s text and link colours (4.5:1 for body text) as described in Accessibility; a palette that passes in the default look does not automatically pass in the dark one.

Since WordPress 6.6 a theme can ship partial variations that a site owner combines freely: the Colors panel lists palettes and the Typography panel lists typesets, so the owner can, for example, keep the default layout, take the "Archive" palette and the "Sans Headings" fonts. Neither appears in Browse styles. The Archive preset contains colour data only:

Source: Theme Handbook: Style Variations

The typography preset contains typography data only; it reuses the font families declared in theme.json (a preset may also declare its own settings.typography.fontFamilies, including fontFace entries, which is how a typeset can bring new self-hosted fonts, see Typography and Fonts):

Source: Theme Handbook: Style Variations

A single extra property breaks the classification. Adding "styles": { "spacing": … } to Archive, or a color value to the typeset, turns either file into a full variation that appears in Browse styles instead. The Site Editor makes the decision in the browser (the isVariationWithProperties() check in the global styles code), so there is no server-side warning; the quickest check is to open the Colors and Typography panels after adding a file.

WP_Theme_JSON_Resolver::get_style_variations() returns the parsed files of the active theme (and of its parent, see Child themes and variations). Its $scope argument, added in 6.6, selects theme variations (theme, the default) or block style variations (block). The REST route /wp/v2/global-styles/themes/<stylesheet>/variations, which the Site Editor calls, returns the theme scope. The script below lists both scopes, then reads the merged global styles, which is also the moment the JSON section styles are registered as block styles:

Source: Code Reference: WP_Theme_JSON_Resolver::get_style_variations()

On the Lumen site, with the functions.php of the next section active:

Applying a variation in the Site Editor copies its values into the user layer; no "active variation" is stored, so later edits to styles/midnight.json do not reach a site that applied Midnight until the owner applies it again (see Site Editor and Global Styles). Three more details: the files are sorted by path, so colors/archive.json comes before midnight.json; a theme that wants a particular order in Browse styles prefixes the file names (01-paper.json, 02-midnight.json), as Twenty Twenty-Five does. The resolver returns presets and full variations together; only the Site Editor separates them. And a variation file’s strings (title, palette name) are translated with the theme’s text domain, so they belong in the theme’s translation files like any other string.

Since 6.2 a child theme inherits its parent’s variations: the resolver reads the child’s styles/ folder, then the parent’s, and drops a parent file when the child has a file with the same base name. A lumen-child that ships styles/midnight.json therefore replaces the parent’s Midnight entirely (it does not merge with it), while Paper and the presets still come from lumen. Because only the base name is compared, lumen-child/styles/dark/midnight.json also hides lumen/styles/midnight.json. Child themes are covered in Child Themes.

register_block_style( $block_name, $style_properties ) (5.3) registers a style on the server, which makes it available in the editor and, if it carries CSS, prints that CSS on the front end only on pages that use the block. The properties are:

Since 6.6 the first argument may also be an array of block names, registering one style for several blocks. Lumen registers a classic CSS style for Quote and a section style in PHP for Group and Columns:

Source: Theme Handbook: Block Style Variations

The inline_style route is what older tutorials teach, and it still has its place for effects that theme.json cannot express. Its drawback is that the CSS is invisible to Styles: the site owner cannot change the pull-quote’s size in the Site Editor, and its selector (0-2-0) beats the 0-1-0 global styles. style_data styles are generated from theme.json data, are listed under Styles > Blocks > Group > Style variations, and follow the active variation’s palette. A theme can also override them from theme.json (as shown for section-dark below), which the Theme Handbook page on block style variations still describes as unsupported; the 7.1.3 resolver merges styles.blocks.<block>.variations.<name> over registered style_data as it does for JSON partials.

Styles can also be registered in the editor only, with wp.blocks.registerBlockStyle() in a script enqueued on enqueue_block_editor_assets; such styles need their CSS from a stylesheet loaded on both sides. Removing styles follows where they came from:

On the Lumen site unregister_block_style( 'core/quote', 'plain' ) returns false and unregister_block_style( 'core/quote', 'pull-quote' ) returns true. Removing a style only hides the button; content that already carries is-style-plain keeps the class, and whether it still looks styled depends on whether the CSS for that class is still loaded.

Before 6.6 a block style variation could only style the block it was applied to. Since 6.6 the data of a variation may contain elements (links, headings, buttons inside the block) and blocks (styles for inner block types), so a single "Section dark" style on a Group can turn the whole section dark: background, text, link and heading colours, and the buttons and separators inside it. This is what the 6.6 release calls section styles. Nesting works because 6.6 also reduced global styles selectors to 0-1-0 specificity with :root :where(…), so the rules of an inner section override those of an outer one by source order, not by selector weight.

The recommended way for a theme is a theme.json partial in styles/ with three extra top-level keys: blockTypes (the block types that offer the style), slug (the class name part) and title (the label). Lumen’s dark section for newsletter sign-ups and featured quotes, styles/section-dark.json:

Source: WordPress Developer Blog: Styling sections, nested elements, and more with Block Style Variations in WordPress 6.6

When WordPress reads the theme data it calls the private wp_register_block_style_variations_from_theme_json_partials() for every file with blockTypes, registering section-dark for each listed block unless a style of that name already exists, and copies the file’s styles into styles.blocks.<block>.variations.section-dark. A partial has no settings (only styles are used), and a file without blockTypes or without styles is skipped.

Because the colours are preset references, the section adapts to the theme variation: under Midnight, ink is the light colour, so "Section dark" becomes a light band on a dark page. If a section must stay dark in every variation, it should refer to slugs whose meaning does not flip, or the dark variation should override it (next section).

The same style can be refined for one block type from theme.json (or from a theme variation) under styles.blocks.<block>.variations.<slug>; the values are merged over the partial’s. The base theme.json above gives the Columns version more vertical padding. The resolver applies, from highest to lowest priority: styles.blocks.<block>.variations in theme.json, the top-level styles.variations in theme.json, the JSON partials, and the registry’s style_data. The top-level styles.variations form was announced as "not recommended" in the 6.6 dev note and should be avoided in new themes.

A user can then change the root styles of each variation per block in Styles > Blocks > Group (or Columns); those values go to the user layer like any other global style.

Global styles do not contain a rule for .is-style-section-dark. Instead, when a block with a section style renders on the front end, the render_block_data filter wp_render_block_style_variation_support_styles() resolves the variation’s data and generates a stylesheet scoped to a per-instance class, and the render_block filter adds that class to the block’s wrapper. The CSS is added to the inline style handle block-style-variation-styles, so it is printed only on pages that use the style. A newsletter section saved by the editor:

Source: Block Editor Handbook: Styles

The script below renders that markup as the front end does and prints the inline CSS queued for it:

Source: Code Reference: do_blocks()

The wrapper div of the Group comes back with the instance class appended, is-style-section-dark--1 (the inner blocks are unchanged), followed by the CSS (rules split one per line for reading):

Source: WordPress 7.1.3: wp-includes/block-supports/block-style-variations.php

On a real request the same CSS appears in <style id="block-style-variation-styles-inline-css"> in the page head. The same Columns block with the style gets padding-top: 3rem and padding-bottom: 3rem from the theme.json override and keeps the 2rem side padding from the partial, and the PHP-registered section-highlight produces the same shape of output from its style_data:

The inline_style of the pull quote is instead appended to the Quote block’s own wp-block-quote-inline-css style.

Several consequences follow from this design:

A dark section can sit inside a highlighted one and the inner rules win, but a variation cannot contain another variation, a section style cannot restyle the block style variations of its inner blocks, and section partials accept no settings (so a section cannot offer its own palette in the colour picker), as the 6.6 dev note states.