Memahami theme.json WordPress: Settings, Styles, dan Urutan Cascade

theme.json adalah satu file konfigurasi di root sebuah block theme yang mengerjakan dua hal terpisah: settings menentukan apa yang ditawarkan block editor kepada pengguna, dan styles menentukan tampilan situs secara bawaan. WordPress mengurainya, menggabungkannya dengan bawaannya sendiri dan dengan apa pun yang tersimpan di Site Editor, lalu mengeluarkan hasilnya sebagai CSS custom property plus stylesheet inline di setiap halaman.

Mencampuradukkan dua tugas itu adalah alasan kenapa kebanyakan perubahan theme.json terlihat tidak berefek apa-apa. Mendeklarasikan sebuah warna di bawah settings tidak menerapkan warna itu ke mana pun. Itu hanya membuat sebuah variabel dan satu kotak warna di sidebar editor.

Key tingkat atas

File paling minimal terlihat seperti ini:

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

Key	Fungsinya
$schema	Hanya untuk autocomplete dan validasi di editor kode. WordPress mengabaikannya.
version	Memberi tahu WordPress bentuk skema mana yang diurai. Bukan versi tema Anda.
settings	Menghasilkan variabel CSS dan menentukan apa yang ditampilkan editor.
styles	Menerapkan gaya bawaan yang sesungguhnya.
templateParts	Mendeklarasikan part di parts/ dan area mana yang menjadi tempatnya.
customTemplates	Mendaftarkan template halaman di templates/ untuk editor pos.

version sering menjebak karena terlihat seperti nomor versi tema. Bukan. Ia memilih mode penguraian, dan rilis WordPress lama diam-diam mengabaikan key dari bentuk skema yang tidak dikenalnya. Kalau Anda mendukung instalasi lama, incar versi yang dimengerti instalasi tersebut ketimbang berasumsi key baru akan turun kelas dengan mulus. Versi 3 adalah yang terkini saat tulisan ini dibuat; versi 2 masih banyak dipakai dan masih diurai.

$schema menunjuk ke URL skema yang dihosting WordPress. Mengarahkannya ke trunk memberi Anda petunjuk terbaru di editor kode; URL khusus versi lebih aman kalau Anda memang sengaja bertahan di skema lama.

settings: apa yang ditawarkan editor

Semua yang ada di bawah settings menghasilkan sebuah CSS custom property dan, pada sebagian besar kasus, sebuah kontrol di editor. Tidak ada satu pun di bawah settings yang memberi gaya pada apa pun.

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

Itu menghasilkan variabel yang dinamai dari jalur preset dan slug-nya:

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

Ia juga menghasilkan kelas utilitas seperti .has-brand-color dan .has-brand-background-color, yang menjadi cara editor menerapkan kotak warna pilihan ke sebuah blok.

Baris "custom": false adalah separuh lain dari settings: mematikan opsi. Pasang baris itu, maka pemilih warna bebas menghilang, dan pengguna hanya kebagian palet Anda, tidak lebih. Pola yang sama berlaku di mana-mana — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border, dan seterusnya. Tidak ada yang bersifat dekoratif di bawah settings; setiap key entah menambah variabel, menambah kontrol, atau menghapus kontrol.

settings.custom adalah wadah bebas untuk variabel Anda sendiri:

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

Itu menjadi --wp--custom--line-height--body dan --wp--custom--shadow--card. Perhatikan perubahannya: key camelCase dipecah menjadi kebab-case, dan susunan bersarang disambung dengan dua tanda hubung. Salah menulis nama variabel adalah penyebab umum sebuah nilai diam-diam jatuh ke nilai cadangan.

Anda bisa membatasi settings per blok, dan begitulah caranya mengizinkan pemilih warna pada tombol tetapi tidak pada paragraf:

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

styles: apa yang benar-benar tampil

styles adalah tempat nilai diterapkan. Strukturnya mengikuti struktur editor: level root, lalu elements, lalu 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)" } }
      }
    }
  }
}

styles di level root mendarat di body. elements mencakup primitif HTML yang bukan blok — tautan, tombol, heading, keterangan gambar. blocks menyasar satu jenis blok tertentu berdasarkan namanya.

Batasan jujurnya: styles tidak bisa mengungkapkan semua hal yang bisa diungkapkan CSS. Tidak ada cara menulis media query sendiri, tidak ada selector rumit, tidak ada animasi, dan hanya ada sedikit state pseudo-class yang didukung. Tipografi fluid dan penentuan ukuran berbasis layout menutup banyak kebutuhan yang dulu dipecahkan orang dengan breakpoint, tapi tidak semuanya. Sebagian besar block theme yang beredar membawa theme.json plus satu stylesheet kecil, dan itu hasil yang wajar, bukan kegagalan.

Jebakan settings versus styles

Pertanyaan dukungan yang paling sering muncul adalah versi dari kalimat “saya sudah menambahkan warna merek saya dan tidak ada yang berubah.”

Betul. Menambahkannya ke settings.color.palette membuat --wp--preset--color--brand dan satu kotak warna. Itu tidak menerapkan apa pun. Untuk menjadikannya warna tautan bawaan, Anda harus menuliskannya juga di bawah styles:

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

Bacalah begini: settings adalah kotak cat yang Anda serahkan ke pengguna, styles adalah lapisan cat yang Anda sapukan sebelum mereka datang.

Cascade, dari terendah ke tertinggi

Bagian inilah yang menjelaskan kenapa sebuah situs terlihat “mengabaikan” file temanya. WordPress menggabungkan beberapa lapisan sebelum mengeluarkan CSS:

1. Bawaan core WordPress — core membawa theme.json miliknya sendiri berisi palet dasar, ukuran font, dan skala spasi.
2. theme.json tema induk
3. theme.json tema anak — digabungkan di atas induknya per key, bukan mengganti seluruh file.
4. Global Styles yang tersimpan di database — apa yang ditulis panel Styles di Site Editor.
5. Gaya per blok pada blok individual — atribut yang tersimpan di konten pos, ditampilkan sebagai gaya inline atau kelas.

Lapisan 4 adalah yang merusak situs. Begitu ada orang membuka panel Styles lalu menyimpan, WordPress menyimpan sebuah catatan Global Styles dan catatan itu menang atas file Anda untuk setiap properti yang dimuatnya. Mengubah theme.json setelah itu tidak mengubah apa pun secara kasatmata untuk properti tersebut — situs terlihat persis sama setelah deploy padahal file di disk jelas-jelas berbeda.

Solusinya adalah menghapus catatan tersimpan itu, bukan menaikkan tensi dengan !important. Buka Site Editor, masuk ke Styles, buka panel revisi, lalu kembalikan ke bawaan tema. Konfirmasikan dulu ke klien atau pemilik situs — mengembalikan ke bawaan akan membuang kustomisasi mereka, dan itu ongkos nyata, bukan tindakan gratis.

Tersangka kedua adalah caching. WordPress menyimpan data theme.json yang sudah diurai ke cache alih-alih membaca ulang file di setiap permintaan, dan itu persis yang Anda mau di produksi sekaligus persis yang tidak Anda mau saat pengembangan. Mengaktifkan WP_DEBUG, atau pengaturan mode pengembangan tema di rilis yang lebih baru, membuat WordPress membaca ulang file setiap kali. Kalau perubahan Anda baru muncul setelah deploy atau setelah cache dibersihkan, itulah yang sedang terjadi.

templateParts dan customTemplates

Keduanya adalah larik yang menjelaskan file yang sudah ada di dalam tema Anda.

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

name harus sama dengan nama file tanpa ekstensinya — parts/header.html, templates/page-wide.html. Nilai area itu penting: ia menentukan apakah part dibungkus elemen landmark header atau footer dan bagaimana editor mengategorikannya. Kalau dikosongkan, part itu dianggap tanpa kategori.

customTemplates adalah yang membuat sebuah template muncul di dropdown template pada editor pos. Tanpa entri itu, filenya ada tetapi tidak ada yang bisa memilihnya.

Urutan diagnosis cepat

Ketika sebuah block theme tidak tampil sesuai isi filenya, telusuri ini dulu sebelum mengutak-atik apa pun:

1. Lihat kode sumber halaman dan cari blok global styles yang dihasilkan. Kalau variabel Anda tidak ada di sana, masalahnya di settings atau salah ketik pada slug.
2. Kalau variabelnya ada tetapi tidak dipakai, masalahnya adalah entri styles yang hilang.
3. Kalau keduanya ada tetapi ada yang menimpanya, periksa apakah ada catatan Global Styles yang tersimpan.
4. Baru setelah itu lihat stylesheet Anda sendiri, plugin, atau page builder yang menyuntikkan CSS lebih belakangan di cascade.