theme.json у WordPress: settings, styles і порядок каскаду

theme.json — це один файл конфігурації в корені блокової теми, який виконує дві окремі задачі: settings вирішує, що блоковий редактор пропонує користувачам, а styles вирішує, як сайт виглядає за замовчуванням. WordPress розбирає цей файл, зливає його зі своїми базовими значеннями і з усім, що збережено в Site Editor, та віддає результат як CSS-змінні плюс вбудовану таблицю стилів на кожній сторінці.

Плутанина між цими двома задачами — причина, чому більшість правок у theme.json начебто нічого не роблять. Оголошення кольору в settings не застосовує цей колір ніде. Воно лише створює змінну й зразок кольору на бічній панелі редактора.

Ключі верхнього рівня

Мінімальний файл виглядає так:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "templateParts": [],
  "customTemplates": []
}

Ключ	Що робить
$schema	Лише автодоповнення й валідація в редакторі коду. WordPress його ігнорує.
version	Каже WordPress, за якою схемою розбирати файл. Це не версія вашої теми.
settings	Генерує CSS-змінні й визначає, що показує редактор.
styles	Застосовує реальні стилі за замовчуванням.
templateParts	Оголошує частини з parts/ і те, до якої зони вони належать.
customTemplates	Реєструє шаблони сторінок із templates/ для редактора записів.

version збиває з пантелику, бо схожий на номер версії теми. Це не так. Він обирає режим розбору, і старіші випуски WordPress мовчки ігнорують ключі зі схеми, якої не знають. Якщо ви підтримуєте старі інсталяції, орієнтуйтеся на версію, яку вони розуміють, а не на надію, що новіші ключі відпрацюють коректно. На момент написання актуальна версія 3; версія 2 усе ще широко розгорнута й досі розбирається.

$schema вказує на URL схеми, розміщений WordPress. Прив’язка до trunk дає найсвіжіші підказки у вашому редакторі коду; URL із конкретною версією безпечніший, якщо ви свідомо лишаєтеся на старішій схемі.

settings: що пропонує редактор

Усе, що лежить у settings, породжує CSS-змінну і, здебільшого, елемент керування в редакторі. Ніщо в settings нічого не стилізує.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Це створює змінні, назви яких складаються зі шляху пресету й слага:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

А ще з’являються службові класи на кшталт .has-brand-color і .has-brand-background-color — саме так редактор застосовує обраний зразок кольору до блоку.

Рядок "custom": false — це друга половина settings: вимикання опцій. Пропишіть його, і довільний вибір кольору зникне, лишивши користувачам вашу палітру й нічого більше. Той самий підхід працює всюди — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border тощо. У settings немає декоративних ключів: кожен або додає змінну, або додає елемент керування, або прибирає його.

settings.custom — вільна секція для ваших власних змінних:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

З цього виходять --wp--custom--line-height--body і --wp--custom--shadow--card. Зверніть увагу на перетворення: ключі у camelCase розбиваються на kebab-case, а вкладеність з’єднується подвійним дефісом. Помилка в назві змінної — поширена причина того, чому значення тихо відкочується до запасного.

Налаштування можна задавати окремо для кожного блоку — так ви дозволяєте вибір кольору для кнопок, але не для абзаців:

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: що справді відображається

styles — це місце, де значення застосовуються. Структура повторює редактор: кореневий рівень, далі elements, далі blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

Стилі кореневого рівня лягають на body. elements охоплює HTML-примітиви, які не є блоками: посилання, кнопку, заголовки, підпис. blocks націлюється на конкретний тип блоку за назвою.

Чесне обмеження: styles не може виразити все, що вміє CSS. Немає способу написати власні медіазапити, немає складних селекторів, немає анімацій, а з псевдокласів підтримується лише невеликий набір. Плинна типографіка й розміри на основі макета покривають більшу частину того, заради чого раніше писали брейкпоінти, але не все. Більшість готових блокових тем несуть theme.json плюс скромну таблицю стилів — і це нормальний результат, а не поразка.

Пастка «settings проти styles»

Найчастіше питання до підтримки звучить як варіація фрази «я додав свій фірмовий колір, і нічого не змінилося».

Усе правильно. Додавання до settings.color.palette створило --wp--preset--color--brand і зразок кольору. Воно нічого не застосувало. Щоб зробити цей колір типовим для посилань, його треба ще прописати в styles:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Читайте це так: settings — набір фарб, який ви даєте користувачеві, а styles — шар фарби, який ви наносите до його приходу.

Каскад, від нижнього рівня до верхнього

Саме ця частина пояснює, чому сайт «ігнорує» файл теми. Перед виведенням CSS WordPress зливає кілька шарів:

1. Базові значення ядра WordPress — ядро постачає власний theme.json із базовою палітрою, розмірами шрифтів і шкалою відступів.
2. theme.json батьківської теми
3. theme.json дочірньої теми — зливається поверх батьківського ключ за ключем, а не замінює файл цілком.
4. Global Styles, збережені в базі даних — те, що записує панель Styles у Site Editor.
5. Стилі окремих блоків — атрибути, збережені у вмісті запису, які виводяться як inline-стилі або класи.

Ламає сайти саме шар 4. Щойно хтось відкриє панель Styles і збереже зміни, WordPress створює запис Global Styles, і цей запис перемагає ваш файл для кожної властивості, яку містить. Подальше редагування theme.json не змінює для цих властивостей нічого видимого: сайт після деплою виглядає точно так само, хоча файл на диску очевидно інший.

Рішення — прибрати збережений запис, а не підвищувати ставки через !important. Відкрийте Site Editor, перейдіть до Styles, відкрийте панель ревізій і поверніться до стандартних значень теми. Спершу узгодьте це з клієнтом або власником сайту: скидання знищує його налаштування, і це реальна втрата, а не безкоштовна дія.

Другий підозрюваний — кешування. WordPress кешує розібрані дані theme.json, а не перечитує файл на кожен запит: саме те, що потрібно в продакшні, і саме те, що заважає під час розробки. Увімкнений WP_DEBUG або режим розробки теми в новіших випусках змушує WordPress перечитувати файл щоразу. Якщо ваші правки з’являються лише після деплою чи скидання кешу — ви бачите саме це.

templateParts і customTemplates

Обидва ключі — масиви, які описують файли, що вже лежать у вашій темі.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

name збігається з іменем файлу без розширення — parts/header.html, templates/page-wide.html. Значення area має вагу: воно вирішує, чи буде частину загорнуто в елемент-орієнтир header або footer і як редактор її класифікує. Пропустите його — частина вважатиметься некатегоризованою.

customTemplates — це те, завдяки чому шаблон з’являється у випадному списку шаблонів у редакторі записів. Без цього запису файл існує, але обрати його ніхто не може.

Швидкий порядок діагностики

Коли блокова тема стилізується не так, як написано у файлі, пройдіть це до того, як щось чіпати:

1. Подивіться вихідний код сторінки й знайдіть згенерований блок глобальних стилів. Якщо вашої змінної там немає, проблема в settings або в описці в слагу.
2. Якщо змінна є, але не використовується, проблема у відсутньому записі в styles.
3. Якщо є і те, і те, але щось їх перекриває, шукайте збережений запис Global Styles.
4. І лише тоді дивіться на власну таблицю стилів, плагіни чи конструктор сторінок, який підмішує CSS пізніше в каскаді.