Вариации стилей и theme.json

Вариации стилей (Style Variations) - это альтернативные версии theme.json в папке темы /styles/, которые позволяют пользователю переключать варианты оформления (цвета, типографика и т.п.) без создания отдельной темы.

Также, через файлы /styles/*.json можно регистрировать вариации стилей для отдельных блоков (см. параметр blockTypes).

Оглавление:

Как это работает
Глобальная вариация (нет blockTypes)
Вариация блока (есть blockTypes)
Доп параметры /styles/*.json
title
slug
description
blockTypes
Что не работает в вариациях
Где хранятся данные
Связанные функции
Отличие от дочерней темы

Как это работает

WordPress автоматически сканирует все файлы в папке /styles/ её подпапках.

Далее логика зависит от параметра blockTypes - это два похожих, но разных механизма:

Глобальная вариация (Для всей темы) - Мержится поверх theme.json
Вариация блока (Для блока) - Добавляет блоку класс is-style-{slug} и применяет стили только к нему

Глобальная вариация (нет `blockTypes`)

Если параметра blockTypes нет, то файл работает как глобальная вариация стилей темы.

Пример структуры:

mytheme/
├── theme.json              ← основной файл (по умолчанию)
└── styles/
	├── latte.json          ← глобальная вариация стилей
	└── swashbuckler.json   ← глобальная вариация стилей

Пример файла latte.json:

{
  "version": 3,
  "title": "Latte",
  "slug": "latte",
  "description": "Latte theme style variation",
  "settings": { ... },
  "styles": { ... }
}

Где в settings, styles нужно добавить новые параметры, которые заменят аналогичные параметры из theme.json. Структура такая же как в theme.json.

На странице админки Appearance > Editor > Styles > Browse styles появится возможность выбора настроек оформления:

При выборе вариации её данные сохраняются в БД как кастомные настройки, которые переопределяют настройки theme.json.

Настройки сохраняются в таблице wp_posts, в поле post_content типа поста wp_global_styles.
Основной theme.json продолжает работать как базовая конфигурация темы. Вариации не заменяют его полностью, а мержатся поверх него. Итоговая конфигурация собирается примерно так:
```
WordPress defaults
→ theme.json
→ selected style variation
→ user changes from wp_global_styles
```

ВАЖНО: Если пользователь уже выбрал вариацию, то обновления файла не применяются (данные из БД важнее). Чтобы обновления вступили в силу, нужно выбрать другую вариацию и вернуться назад.

Каждая вариация - это JSON-файл с теми же возможностями, что и основной theme.json.

ВАЖНО: файл theme.json физически не изменяется. WordPress берет основной theme.json, мержит с ним выбранную вариацию стилей и применяет итоговые настройки.

Вариация блока (есть `blockTypes`)

Если параметр blockTypes есть, то файл работает как вариация стиля для указанного блока/блоков.

Пример вариации для блока:

styles/blocks-variations/
	section-dark.json

Возможные поля .json файла:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Alt Fill",
  "slug": "alt-fill",
  "blockTypes": [ "core/button" ],
  "styles": {}
}

Где:

$schema - схема для IDE, подсказок и валидации.
version - версия формата theme.json.
title - название в интерфейсе редактора.
slug - системное имя, из него будет is-style-{slug}.
blockTypes - список блоков, для которых регистрируется вариация.
styles - сами стили вариации.

Внутри styles можно использовать почти все поля style, что и в theme.json:

{
  "color": {},
  "background": {},
  "border": {},
  "dimensions": {},
  "filter": {},
  "outline": {},
  "shadow": {},
  "spacing": {},
  "typography": {},
  "elements": {},
  "blocks": {},
  "css": ""
}

Например:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Alt Fill",
  "slug": "alt-fill",
  "blockTypes": [ "core/button" ],
  "styles": {
	"color": {
	  "background": "var(--wp--preset--color--contrast)",
	  "text": "var(--wp--preset--color--base)"
	},
	"border": {
	  "radius": "999px"
	},
	"spacing": {
	  "padding": {
		"top": "0.75rem",
		"right": "1.5rem",
		"bottom": "0.75rem",
		"left": "1.5rem"
	  }
	},
	"css": " box-shadow: 0 0 0 2px currentColor;"
  }
}

Эта вариация появится только у блока core/button:

При выборе вариации в редкторе, WordPress добавляет блоку CSS класс вида is-style-{slug} и применяет стили только к этому блоку.

Вариация блока должна иметь хотябы одну настройку в параметер "styles", иначе она не будет работать - WP сочтет её пустой и пропустит.

Можно создать несколько файлов для разных блоков:

styles/blocks-variations/
	section-dark.json
	section-light.json
	image-rounded.json
	card-accent.json

Каждый файл регистрирует отдельную вариацию для отдельных блоков.

Доп параметры /styles/*.json

Параметры ниже будут работать только для json файла вариации стилей, который расширяет базовый theme.json файл темы.

title

Название вариации стилей. Если не определено, будет использовано имя файла вариации.

{
	"version": 3,
	"title": "Настройки темы МОЯ_ТЕМА",
	...
}

slug

Идентификатор вариации стилей (в kebab-case). Если не определено, будет сгенерирован автоматически на основе title.

{
	"version": 3,
	"slug": "my-theme-variation",
	...
}

description

Описание вариации стилей. Может отображаться в интерфейсе WordPress. Необязательное поле.

{
	"version": 3,
	"description": "Тёмная тема с акцентом на контрастные цвета.",
	...
}

blockTypes

Список блоков, к которым относится данная вариация.

Если параметр blockTypes не указан, json файл работает как глобальная вариация стилей темы.

Если blockTypes указан, WordPress воспринимает такой файл как вариацию стиля для конкретного блока или списка блоков. Такая вариация появляется не в списке глобальных стилей темы, а в настройках конкретного блока.

{
	"version": 3,
	"title": "Section Dark",
	"slug": "section-dark",
	"blockTypes": [ "core/group", "core/columns" ],
	"styles": {
		"color": {
			"background": "var:preset|color|contrast",
			"text": "var:preset|color|base"
		}
	}
}

В этом примере вариация Section Dark будет доступна только для блоков core/group и core/columns.

После выбора этой вариации у блока появится CSS класс:

<div class="wp-block-group is-style-section-dark">
	...
</div>

А стили из json файла будут применены только к блоку с этим выбранным стилем.

Вариация блока прорастет в редакторе, в том числе с глобальных стилях редактора FSE.

При регистрации через register_block_style(), вариация не появляется в глобальных стилях.

Что не работает в вариациях

Вариации не поддерживают следующие параметры (будут проигнорированы, если указаны):

customTemplates
templateParts
patterns
settings - некоторые настройки игнорируются

Где хранятся данные

В stylebook админки (редакторе стилей), можно изменять стили для отдельных блоков или выбирать другие вариации стилей.

Такие изменения хранятся в таблице wp_posts в post_type = wp_global_styles. Такая запись может быть одна для темы.

Важные поля таблицы:

post_content - хранит JSON измененных стилей. Этот JSON мержится с данными из theme.json.
post_name - хранит ярлык отсылающий к теме к которой относятся стили. Шаблон такой: wp-global-styles-{theme_folder_name}. Нужно это потому что для разных тем могут быть разные стили.

Так, если нужно сохранить (экспортировать) текущие стили, то можно сохранить контент этой записи из wp_posts.

Данные указанные в json файле вариации стилей + кастомные правки стилей от пользователя, сохраняются в таблице wp_posts, в поле post_content типа поста wp_global_styles.

+-----------------------+----------------------------------------------------------------------+
| Field                 | Value                                                                |
+-----------------------+----------------------------------------------------------------------+
| ID                    | 21                                                                   |
| post_author           | 1                                                                    |
| post_date             | 2025-05-29 23:38:02                                                  |
| post_date_gmt         | 2025-05-29 23:38:02                                                  |
| post_content          | {"styles":{"spacing":{"padding":{"top":"0px","right":"var:preset|spa |
|                       | cing|3xs","bottom":"0px","left":"var:preset|spacing|3xs"}},"css":".f |
|                       | oooooooooo {n   color: red;n}"},"settings":[],"isGlobalStylesUserT |
|                       | hemeJSON":true,"version":3}                                          |
| post_title            | Custom Styles                                                        |
| post_excerpt          |                                                                      |
| post_status           | publish                                                              |
| comment_status        | closed                                                               |
| ping_status           | closed                                                               |
| post_password         |                                                                      |
| post_name             | wp-global-styles-agnostic-design                                     |
| to_ping               |                                                                      |
| pinged                |                                                                      |
| post_modified         | 2025-06-19 12:47:51                                                  |
| post_modified_gmt     | 2025-06-19 12:47:51                                                  |
| post_content_filtered |                                                                      |
| post_parent           | 0                                                                    |
| guid                  | http://pbnwp.loc/blog/2025/05/29/wp-global-styles-agnostic-design/   |
| menu_order            | 0                                                                    |
| post_type             | wp_global_styles                                                     |
| post_mime_type        |                                                                      |
| comment_count         | 0                                                                    |
| url                   | http://pbnwp.loc/blog/2025/05/29/wp-global-styles-agnostic-design/   |
+-----------------------+----------------------------------------------------------------------+

ВАЖНО: Сохраняются только те значения параметров, которые отличаются от базовых в theme.json.

Связанные функции

Cписок функций связанных с вариациями стилей (theme.json styles variations):

Получение и обработка стилей:

wp_get_global_styles() — Gets the styles resulting of merging core, theme, and user data.
wp_get_global_stylesheet() — Получает готовый CSS-код из смерженных данных theme.json, вариаций стилей и кастомных настроек пользователя.
wp_clean_theme_json_cache() — Cleans the caches under the theme_json group.
wp_print_font_faces_from_style_variations() — Generates and prints font-face styles defined the the theme style variations.

Работа с WP_Theme_JSON:

WP_Theme_JSON::get_style_nodes() — Builds metadata for the style nodes, which returns in the form of:
WP_Theme_JSON::get_stylesheet() — Returns the stylesheet that results of processing the theme.json structure this object represents.
WP_Theme_JSON::get_settings() — Returns the existing settings for each block.
WP_Theme_JSON::get_raw_data() — Returns the raw data.
WP_Theme_JSON::get_data() — Returns a valid theme.json as provided by a theme.
WP_Theme_JSON::merge() — Merges new incoming data.

Все остальные методы WP_Theme_JSON.

Резолвер данных:

WP_Theme_JSON_Resolver::get_theme_data() — Returns the theme's data.
WP_Theme_JSON_Resolver::get_style_variations() — Returns the style variations defined by the theme.
WP_Font_Face_Resolver::get_fonts_from_style_variations() — Gets fonts defined in style variations.

Все остальные методы WP_Theme_JSON_Resolver, WP_Font_Face_Resolver.

Отличие от дочерней темы

Вариации стилей	Дочерняя тема
Один JSON-файл	Полная структура темы
Переопределяет `theme.json`	Может переопределять всё
Хранится в `/styles/`	Это отдельная тема
Настройки сохраняются в БД	Нет сохранения в БД

Вариации стилей подходят, если нужно предложить визуальные варианты оформления темы без дублирования темы. Для более глубоких изменений (PHP код, шаблоны и т.д.) лучше использовать дочернюю тему.

Читайте также уроки по FSE: https://fullsiteediting.com/lessons/global-style-variations/