theme.json w WordPressie: settings, styles i kaskada

theme.json to pojedynczy plik konfiguracyjny w katalogu głównym motywu blokowego, który wykonuje dwa osobne zadania: settings decyduje o tym, co edytor bloków oferuje użytkownikowi, a styles decyduje o tym, jak witryna domyślnie wygląda. WordPress przetwarza ten plik, scala go z własnymi ustawieniami domyślnymi oraz ze wszystkim, co zapisano w edytorze witryny, i publikuje wynik jako zmienne CSS wraz z arkuszem stylów osadzonym na każdej podstronie.

Mylenie tych dwóch zadań to powód, dla którego większość zmian w theme.json sprawia wrażenie, jakby nic nie robiła. Zadeklarowanie koloru w settings nie stosuje tego koloru nigdzie. Tworzy jedynie zmienną i próbkę w bocznym panelu edytora.

Klucze najwyższego poziomu

Minimalny plik wygląda tak:

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

Klucz	Do czego służy
$schema	Wyłącznie podpowiedzi i walidacja w edytorze kodu. WordPress go ignoruje.
version	Mówi WordPressowi, według jakiego schematu przetwarzać plik. To nie jest wersja motywu.
settings	Generuje zmienne CSS i decyduje, co udostępnia edytor.
styles	Nakłada rzeczywiste style domyślne.
templateParts	Deklaruje części z katalogu parts/ i obszar, do którego należą.
customTemplates	Rejestruje szablony stron z katalogu templates/ w edytorze wpisów.

version bywa mylące, bo wygląda jak numer wersji motywu. Nim nie jest. Wybiera tryb przetwarzania, a starsze wydania WordPressa po cichu pomijają klucze ze schematu, którego nie znają. Jeśli wspierasz starsze instalacje, celuj w wersję, którą one rozumieją, zamiast zakładać, że nowsze klucze zadziałają choć częściowo. W chwili pisania aktualna jest wersja 3; wersja 2 wciąż jest szeroko używana i nadal przetwarzana.

$schema wskazuje na adres schematu hostowanego przez WordPressa. Wskazanie na trunk daje najnowsze podpowiedzi w edytorze kodu; adres przypisany do konkretnej wersji jest bezpieczniejszy, jeśli świadomie zostajesz przy starszym schemacie.

settings: co oferuje edytor

Wszystko, co znajdzie się w settings, generuje zmienną CSS, a w większości przypadków także kontrolkę w edytorze. Nic z settings niczego nie stylizuje.

{
  "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"
    }
  }
}

Powstają z tego zmienne nazwane według ścieżki presetu i sluga:

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

Powstają też klasy pomocnicze, takie jak .has-brand-color czy .has-brand-background-color — to właśnie przez nie edytor nakłada wybraną próbkę na blok.

Linia "custom": false to druga połowa roli settings: wyłączanie opcji. Ustaw ją, a dowolny wybór koloru zniknie, zostawiając użytkownikom wyłącznie Twoją paletę. Ten sam wzorzec działa wszędzie — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border i tak dalej. Nic w settings nie jest ozdobnikiem: każdy klucz albo dodaje zmienną, albo dodaje kontrolkę, albo kontrolkę odbiera.

settings.custom to dowolny worek na Twoje własne zmienne:

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

Powstaną z tego --wp--custom--line-height--body oraz --wp--custom--shadow--card. Zwróć uwagę na przekształcenie: klucze pisane camelCase są rozbijane na kebab-case, a zagnieżdżenie łączone jest podwójnym myślnikiem. Pomyłka w nazwie zmiennej to częsty powód, dla którego wartość po cichu wraca do ustawienia domyślnego.

Ustawienia można zawęzić do konkretnego bloku — tak właśnie włączysz wybór koloru dla przycisków, ale nie dla akapitów:

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

styles: to, co faktycznie się renderuje

styles to miejsce, w którym wartości zostają zastosowane. Odwzorowuje strukturę edytora: poziom główny, potem elements, potem 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)" } }
      }
    }
  }
}

Style z poziomu głównego lądują na elemencie body. elements obejmuje prymitywy HTML, które nie są blokami — odnośnik, przycisk, nagłówki, podpis. blocks celuje w konkretny typ bloku po nazwie.

Uczciwe ograniczenie: styles nie wyrazi wszystkiego, co potrafi CSS. Nie napiszesz tu własnych zapytań medialnych, nie ma złożonych selektorów ani animacji, a obsługiwany jest tylko wąski zestaw stanów pseudoklas. Płynna typografia i rozmiary oparte na układzie zastępują sporą część tego, do czego kiedyś używano punktów granicznych, ale nie wszystko. Większość wydawanych motywów blokowych ma theme.json plus skromny arkusz stylów — i to normalny rezultat, a nie porażka.

Pułapka settings kontra styles

Najczęstsze pytanie do wsparcia brzmi w takiej czy innej formie: „dodałem kolor mojej marki i nic się nie zmieniło”.

I słusznie. Dodanie go do settings.color.palette utworzyło --wp--preset--color--brand oraz próbkę. Nie zastosowało niczego. Żeby stał się domyślnym kolorem odnośników, musisz zapisać go również w styles:

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

Czytaj to tak: settings to zestaw farb, który wręczasz użytkownikowi, a styles to warstwa, którą nakładasz, zanim ten użytkownik się pojawi.

Kaskada, od najniższej warstwy do najwyższej

To ta część, która tłumaczy witrynę „ignorującą” plik motywu. Zanim WordPress wygeneruje CSS, scala kilka warstw:

1. Ustawienia domyślne rdzenia WordPressa — rdzeń ma własny theme.json z bazową paletą, rozmiarami czcionek i skalą odstępów.
2. theme.json motywu nadrzędnego
3. theme.json motywu potomnego — scalany z nadrzędnym klucz po kluczu, a nie zastępujący cały plik.
4. Style globalne zapisane w bazie danych — to, co zapisuje panel Style w edytorze witryny.
5. Style poszczególnych bloków — atrybuty przechowywane w treści wpisu, renderowane jako style inline lub klasy.

To warstwa 4 psuje witryny. W chwili, w której ktokolwiek otworzy panel Style i zapisze zmiany, WordPress tworzy rekord stylów globalnych, a ten rekord wygrywa z Twoim plikiem dla każdej właściwości, którą zawiera. Późniejsza edycja theme.json nie zmienia w tych właściwościach nic widocznego — witryna po wdrożeniu wygląda identycznie, choć plik na dysku ewidentnie jest inny.

Rozwiązaniem jest usunięcie zapisanego rekordu, a nie eskalacja przy pomocy !important. Otwórz edytor witryny, przejdź do Style, otwórz panel wersji i przywróć ustawienia domyślne motywu. Najpierw potwierdź to z klientem albo właścicielem witryny — reset kasuje jego personalizacje, a to realny koszt, nie darmowa operacja.

Drugim podejrzanym jest buforowanie. WordPress buforuje przetworzone dane z theme.json, zamiast odczytywać plik przy każdym żądaniu — czyli dokładnie to, czego chcesz na produkcji, i dokładnie to, czego nie chcesz podczas pracy nad motywem. Włączenie WP_DEBUG albo ustawienia trybu deweloperskiego motywu w nowszych wydaniach sprawia, że WordPress odczytuje plik za każdym razem. Jeśli Twoje zmiany pojawiają się dopiero po wdrożeniu albo po wyczyszczeniu bufora, to właśnie z tym masz do czynienia.

templateParts i customTemplates

Oba to tablice opisujące pliki, które już leżą w Twoim motywie.

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

name odpowiada nazwie pliku bez rozszerzenia — parts/header.html, templates/page-wide.html. Wartość area ma znaczenie: decyduje o tym, czy część zostanie opakowana w element nagłówka lub stopki, oraz jak edytor ją skategoryzuje. Pomiń ją, a część zostanie potraktowana jako nieprzypisana.

customTemplates sprawia, że szablon pojawia się na liście szablonów w edytorze wpisów. Bez tego wpisu plik istnieje, ale nikt nie może go wybrać.

Szybka kolejność diagnostyczna

Kiedy motyw blokowy nie stylizuje tak, jak wynikałoby to z pliku, przejdź przez to, zanim czegokolwiek dotkniesz:

1. Zobacz źródło strony i poszukaj wygenerowanego bloku stylów globalnych. Jeśli nie ma tam Twojej zmiennej, problem jest w settings albo w literówce w slugu.
2. Jeśli zmienna istnieje, ale nie jest nigdzie użyta, brakuje wpisu w styles.
3. Jeśli istnieją oba, a mimo to coś je nadpisuje, sprawdź zapisany rekord stylów globalnych.
4. Dopiero potem zajrzyj do własnego arkusza stylów, wtyczek albo kreatora stron wstrzykującego CSS później w kaskadzie.