theme.json давно перестал быть просто удобным JSON-файлом для настройки редактора WordPress. В 2026 году это один из ключевых инструментов современной блочной темы: через него можно централизованно управлять цветами, типографикой, отступами, размерами, пресетами и поведением редактора Gutenberg.
Если раньше разработчики часто решали такие задачи через functions.php, CSS и многочисленные хуки, то сегодня значительную часть настроек лучше описывать декларативно в theme.json.
В этой статье разберём, как использовать theme.json правильно, какие возможности стоит применять в современных темах и каких ошибок лучше избегать.
Что такое theme.json
theme.json — конфигурационный файл блочной темы WordPress. Он позволяет определить дизайн-систему темы и настройки редактора в одном месте.
Например, вместо того чтобы вручную создавать CSS-классы для каждого цвета, можно определить палитру:
{
"settings": {
"color": {
"palette": [
{
"slug": "primary",
"color": "#1a73e8",
"name": "Primary"
},
{
"slug": "text",
"color": "#222222",
"name": "Text"
}
]
}
}
}
После этого эти цвета становятся частью системы WordPress и могут использоваться в редакторе, блоках и стилях темы.
Главная идея theme.json — описать правила дизайна один раз и позволить WordPress применять их последовательно.
Версия theme.json в 2026 году
Одна из первых вещей, которую стоит проверить, — версия схемы:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3
}
Для современных тем WordPress следует ориентироваться на актуальную версию theme.json, а не копировать старые примеры с version: 1 или version: 2.
При этом важно различать версию схемы theme.json и версию WordPress. Возможности файла развиваются вместе с WordPress, поэтому перед использованием новых свойств стоит проверить, какая версия WordPress является минимально поддерживаемой вашей темой.
Поле $schema также полезно оставить в файле. Оно помогает IDE подсказывать доступные свойства и обнаруживать ошибки в JSON.
Не превращайте theme.json в огромный набор настроек
Одна из распространённых ошибок — пытаться поместить в theme.json абсолютно всё.
Хорошая конфигурация должна описывать дизайн-систему, а не заменять весь CSS сайта.
Например, здесь уместны:
- основные цвета;
- шрифты;
- размеры текста;
- размеры контентной области;
- spacing;
- border radius;
- presets;
- стили блоков;
- настройки доступных пользователю опций.
А вот сложные компоненты, анимации, нестандартные layout-механики и специфические responsive-правила зачастую проще и понятнее реализовать обычным CSS.
Условно:
theme.jsonотвечает за системные дизайн-токены и интеграцию с WordPress, CSS — за сложное визуальное поведение.
Используйте settings для создания дизайн-системы
Одна из самых сильных сторон theme.json — возможность создать единый набор токенов.
Например:
{
"settings": {
"color": {
"palette": [
{
"slug": "primary",
"color": "#2563eb",
"name": "Primary"
},
{
"slug": "secondary",
"color": "#7c3aed",
"name": "Secondary"
},
{
"slug": "surface",
"color": "#f8fafc",
"name": "Surface"
},
{
"slug": "contrast",
"color": "#0f172a",
"name": "Contrast"
}
]
}
}
}
Теперь вместо десятков произвольных значений тема использует ограниченную палитру.
Это особенно важно для крупных проектов. Если дизайнер решил изменить основной цвет с #2563eb на другой, изменение можно сделать централизованно.
Ограничивайте произвольные значения там, где это имеет смысл
WordPress позволяет определить, какие возможности доступны пользователю в редакторе.
Например:
{
"settings": {
"color": {
"custom": false
}
}
}
Это означает, что пользователь не сможет создавать произвольные цвета и будет работать с палитрой темы.
Такой подход полезен для корпоративных сайтов, где важно соблюдать брендбук.
Но полностью запрещать пользовательские настройки стоит не всегда. Для контентных проектов редактору часто полезнее оставить больше свободы.
Хорошее правило:
ограничивайте редактор там, где ограничения защищают дизайн-систему, а не просто потому, что это возможно.
Используйте presets вместо множества ручных значений
Современный theme.json позволяет создавать системные presets для размеров, spacing, typography и других параметров.
Например, можно определить набор размеров шрифта:
{
"settings": {
"typography": {
"fontSizes": [
{
"slug": "small",
"name": "Small",
"size": "0.875rem"
},
{
"slug": "medium",
"name": "Medium",
"size": "1rem"
},
{
"slug": "large",
"name": "Large",
"size": "1.5rem"
},
{
"slug": "x-large",
"name": "Extra Large",
"size": "2.25rem"
}
]
}
}
}
Вместо того чтобы каждый раз выбирать произвольный размер, редактор получает понятную шкалу.
Ещё лучше, если эта шкала соответствует реальной типографической системе проекта.
Не забывайте про fluid typography
Для адаптивной типографики в современных темах особенно полезен fluid sizing.
Например, настройки можно организовать так, чтобы размер текста плавно менялся между небольшими и большими экранами, вместо жёсткого переключения между несколькими breakpoint’ами.
Идея примерно такая:
{
"settings": {
"typography": {
"fluid": true
}
}
}
При этом не стоит включать fluid-поведение механически для каждого элемента.
Заголовок может хорошо масштабироваться от мобильного к desktop, а некоторые интерфейсные элементы должны иметь фиксированный размер.
Контролируйте spacing через систему
Отступы — ещё одна область, где theme.json помогает избежать хаоса.
Вместо:
margin: 13px;
margin: 27px;
margin: 41px;
margin: 63px;
лучше создать осмысленную шкалу spacing.
Например:
{
"settings": {
"spacing": {
"spacingSizes": [
{
"slug": "20",
"size": "0.5rem",
"name": "XS"
},
{
"slug": "40",
"size": "1rem",
"name": "S"
},
{
"slug": "60",
"size": "1.5rem",
"name": "M"
},
{
"slug": "80",
"size": "2rem",
"name": "L"
}
]
}
}
}
Названия и значения здесь должны соответствовать конкретной дизайн-системе проекта.
Главное — не создавать 30 почти одинаковых значений. Если разница между 1.5rem и 1.6rem не имеет системного смысла, такой токен, скорее всего, не нужен.
Разделяйте глобальные настройки и настройки конкретных блоков
theme.json позволяет определять стили не только глобально, но и для отдельных блоков.
Например:
{
"styles": {
"blocks": {
"core/button": {
"border": {
"radius": "999px"
}
}
}
}
}
Теперь кнопки WordPress будут использовать заданное скругление.
Это значительно лучше, чем вручную добавлять класс к каждой кнопке:
<a class="button rounded">...</a>
Особенно если сайт полностью построен на блоках.
Используйте styles, чтобы описывать визуальные правила
Глобальные стили можно определить непосредственно в theme.json.
Например:
{
"styles": {
"color": {
"text": "var:preset|color|contrast",
"background": "var:preset|color|surface"
},
"typography": {
"fontSize": "1rem",
"lineHeight": "1.6"
}
}
}
Обратите внимание на использование preset вместо жёстко прописанного цвета.
Это важный принцип:
если значение является частью дизайн-системы, лучше ссылаться на preset, а не дублировать его значение.
Не дублируйте CSS-значения без необходимости
Плохой вариант:
{
"styles": {
"color": {
"text": "#0f172a"
}
}
}
и одновременно:
body {
color: #0f172a;
}
и ещё один вариант цвета в настройках блока.
В итоге возникает несколько источников правды.
Лучше выбрать одну систему:
design token
↓
theme.json
↓
WordPress / block editor
↓
generated styles
А обычный CSS использовать там, где декларативных возможностей theme.json недостаточно.
Особое внимание — CSS-переменным
WordPress генерирует CSS custom properties для многих значений, определённых через presets.
Например, цвет из палитры может использоваться через переменную, созданную WordPress.
Это удобно для собственной CSS-части темы:
.card {
color: var(--wp--preset--color--contrast);
}
Такой подход позволяет связать обычный CSS с дизайн-системой WordPress.
Но не стоит вручную воспроизводить все переменные, которые WordPress уже умеет генерировать.
Используйте theme.json как единый источник дизайн-токенов
Для современного проекта полезно мыслить не страницами, а токенами.
Например:
Colors
├── primary
├── secondary
├── surface
└── contrast
Typography
├── small
├── body
├── large
└── display
Spacing
├── xs
├── sm
├── md
├── lg
└── xl
Затем эти токены используются:
- глобальными стилями;
- блоками;
- шаблонами;
- редактором;
- собственным CSS;
- компонентами темы.
В результате theme.json становится не просто конфигурационным файлом, а центральным слоем дизайн-системы.
Что делать с functions.php
В старых темах многие настройки редактора делались через PHP:
add_theme_support(...);
add_editor_style(...);
В block themes часть подобных задач постепенно переносится в theme.json.
Это не означает, что functions.php больше не нужен.
PHP по-прежнему нужен для:
- серверной логики;
- хуков;
- фильтров;
- регистрации функциональности;
- интеграций;
- динамических блоков;
- специфического поведения WordPress.
Но если задача заключается именно в декларативной настройке редактора и дизайна, сначала стоит проверить, можно ли решить её через theme.json.
Проверяйте итоговый CSS, а не только JSON
Ещё одна важная практика 2026 года — не считать theme.json самоцелью.
После изменения конфигурации нужно смотреть, что реально попадает на страницу.
Проверяйте:
- размер генерируемого CSS;
- дублирование правил;
- специфичность;
- наследование;
- мобильную версию;
- работу редактора;
- frontend;
- пользовательские настройки блоков.
Большой theme.json не обязательно означает плохую тему. Но если изменение одной настройки приводит к огромному количеству сгенерированных правил, стоит разобраться почему.
Типичные ошибки
1. Копирование старого theme.json
Примеры из статей 2021–2023 годов часто используют устаревшие возможности.
В 2026 году документацию и schema лучше сверять с актуальной версией WordPress.
2. Слишком много presets
Preset должен решать реальную задачу дизайн-системы.
Если у вас 47 размеров шрифта и 35 вариантов spacing, система перестаёт быть системой.
3. Дублирование theme.json и CSS
Если одно и то же правило задано в трёх местах, через несколько месяцев никто не будет уверен, какое из них является главным.
4. Слишком жёсткие ограничения
Запретить пользователю всё — не значит сделать тему качественнее.
Ограничения должны защищать дизайн-систему.
5. Жёсткие значения вместо токенов
Если цвет, spacing или размер шрифта используется много раз, его стоит вынести в preset.
6. Игнорирование доступности
Цветовая палитра должна обеспечивать достаточный контраст.
Также не стоит строить типографику исключительно вокруг визуального вида — важны читаемость, масштабирование и доступность.
Рекомендуемая структура
Для современной block theme можно начать примерно с такой архитектуры:
my-theme/
├── style.css
├── theme.json
├── functions.php
├── templates/
│ ├── index.html
│ ├── single.html
│ └── page.html
├── parts/
│ ├── header.html
│ └── footer.html
└── patterns/
├── hero.php
└── card.php
А сам theme.json логически разделить на:
theme.json
│
├── schema / version
├── settings
│ ├── color
│ ├── typography
│ ├── spacing
│ ├── layout
│ └── appearance
│
└── styles
├── global
└── blocks
Конкретная структура будет зависеть от возможностей актуальной версии WordPress и требований проекта.
Практический подход
Если вы создаёте новую тему в 2026 году, удобно двигаться в таком порядке:
1. Сначала определите дизайн-систему.
Опишите цвета, типографику, spacing, размеры контента и основные визуальные характеристики.
2. Затем перенесите системные значения в theme.json.
Создайте presets и глобальные настройки.
3. После этого настройте блоки.
Например, отдельно определите внешний вид кнопок, заголовков, цитат и других часто используемых блоков.
4. Затем добавляйте CSS.
Только для тех вещей, которые действительно неудобно или невозможно выразить через систему WordPress.
5. Проверьте редактор и frontend.
Они должны вести себя одинаково предсказуемо.
Итог
В 2026 году правильное использование theme.json — это не попытка заменить им весь CSS.
Гораздо полезнее рассматривать его как центральный слой конфигурации и дизайн-системы WordPress.
Хороший theme.json:
- содержит ограниченный и осмысленный набор design tokens;
- использует presets;
- связывает редактор и frontend;
- минимизирует дублирование CSS;
- позволяет контролировать возможности Gutenberg;
- учитывает адаптивность и доступность;
- не пытается заменить PHP и обычный CSS там, где они подходят лучше.
Самый практичный принцип можно сформулировать так:
Сначала создайте дизайн-систему, затем выразите её через
theme.json, а CSS и PHP используйте для задач, которые не относятся к декларативной конфигурации темы.
Именно такой подход делает block theme предсказуемой, поддерживаемой и гораздо более удобной для дальнейшего развития.
