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

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

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

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

Читайте также: https://fullsiteediting.com/lessons/global-style-variations/

Оглавление:

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

Использование

Нужно создать в теме папку styles и в ней json файлы. Пример структуры:

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.

Доп параметры .json

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

title

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

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

slug

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

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

description

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

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

blockTypes

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

Позволяет ограничить вариацию только определёнными типами блоков. Применяется редко.

{
	"version": 3,
	"blockTypes": [ "core/paragraph", "core/heading" ],
	...
}

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

WordPress автоматически сканирует все файлы в папке /styles/ и показывает их в редакторе сайта.
При выборе вариации её данные сохраняются в БД как кастомные настройки, которые переопределяют настройки theme.json.
Настроки сохраняются в таблице wp_posts, в поле post_content типа поста wp_global_styles.

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

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

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

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

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

Данные указаныне в 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 код, шаблоны и т.д.) лучше использовать дочернюю тему.