Theme.json v3 di WP 6.7 Bikin Tema Lamamu Error? Ini yang Harus Kamu Audit Sebelum Update

Jawaban Singkat: WordPress 6.7 memperkenalkan theme.json versi 3 dengan spacing presets berbasis array, fluid typography yang lebih granular, dan penghapusan backward compatibility untuk format lama. Theme author wajib audit theme.json sebelum update, atau blok layout bisa rusak secara silent.

Apa yang Sebenarnya Berubah di Theme.json v3?

Kamu mungkin baru saja push update tema dan tiba-tiba spacing section jadi aneh. Tombol nggak ada jarak, heading ketabrak paragraf. Itu bukan bug sembarangan, itu theme.json v3 yang mulai berlaku penuh di WordPress 6.7.

Sejak WordPress 5.8, theme.json jadi jantung kontrol block theme. Tiap versi mayor WP menaikkan versi schema-nya. Nah, versi 3 ini membawa perubahan paling signifikan sejak konsep settings.spacing.spacingSizes diperkenalkan. Kalau tema kamu masih pakai format v2 tanpa update, hasil rendering di frontend bisa ngaco.

Tiga area utama yang berubah: spacing presets, fluid typography, dan default values removal. Masing-masing punya potensi breaking change tersendiri.

Spacing Presets: Dari Object ke Array

Ini breaking change paling besar. Di theme.json v2, settings.spacing.spacingSizes pakai format object dengan key-value. Di v3, format itu diganti jadi array of objects. Lihat perbandingannya:

// ❌ Format v2 (akan diabaikan di WP 6.7)
"spacingSizes": {
    "small": "1.5rem",
    "medium": "3rem",
    "large": "6rem"
}

// ✅ Format v3 (wajib mulai WP 6.7)
"spacingSizes": [
    { "name": "Small", "slug": "small", "size": "1.5rem" },
    { "name": "Medium", "slug": "medium", "size": "3rem" },
    { "name": "Large", "slug": "large", "size": "6rem" }
]

Kalau kamu biarin format v2, WordPress 6.7 nggak bakal kasih warning. Spacing presets-mu akan hilang begitu saja dari Editor. Block yang ngandelin preset itu bakal fallback ke default spacing WP, dan layout-mu jadi berantakan. Ini bukan deprecation gradual, ini hard switch.

Rekomendasi: jalankan audit script yang ngecek semua kemunculan "spacingSizes" di repo tema. Kalau ketemu format object, migrasi ke array. Jangan lupa cek "custom" spacing preset juga, biasanya terselip di bawah "settings.custom".

Fluid Typography: Sekarang Bisa Per-Preset

Sebelum 6.7, fluid typography cuma punya satu saklar global: settings.typography.fluid. Nilainya true atau false. Kalau kamu aktifkan, semua font size presets ikut fluid. Kalau matiin, semuanya statis.

Itu masalah besar. Kamu mungkin pengen heading fluid, tapi body text tetap statis di mobile. Atau sebaliknya. Di theme.json v3, kontrol fluid sekarang per-preset:

"fontSizes": [
    {
        "name": "Body",
        "slug": "body",
        "size": "1rem",
        "fluid": false
    },
    {
        "name": "Heading 1",
        "slug": "h1",
        "size": "3.5rem",
        "fluid": {
            "min": "2rem",
            "max": "5rem"
        }
    }
]

Kamu juga bisa set min dan max spesifik untuk tiap preset, bukan cuma ngandelin kalkulasi otomatis WordPress. Ini game-changer buat theme author yang mau kontrol presisi typography di semua breakpoint tanpa nulis CSS tambahan.

Tapi ada gotcha-nya: preset yang nggak punya properti fluid akan inherit dari pengaturan global. Jadi kalau global fluid kamu true, semua preset otomatis ikut fluid kecuali kamu explicitly set false. Perilaku ini beda dari v2, jadi hati-hati.

Default Values yang Dihapus: Jangan Percaya WP Akan Isiin Gaps

Di theme.json v2, WordPress otomatis mengisi beberapa nilai default yang nggak kamu deklarasikan. Contohnya useRootPaddingAwareAlignments dan beberapa setting appearanceTools. Di v3, pendekatan ini berubah total: WP cuma pakai apa yang kamu tulis.

Ini sebenarnya kabar baik. Tema jadi lebih eksplisit dan nggak ada magic values yang susah didebug. Tapi efek sampingnya: tema yang tadinya “kebetulan berfungsi” karena ngandelin default WP, sekarang bakal kehilangan fitur secara diam-diam.

Contoh nyata: kalau dulu kamu nggak deklarasi settings.layout.contentSize, WP otomatis kasih nilai default. Sekarang, nggak ada deklarasi berarti nggak ada constraint. Block yang pakai align wide/full bisa overflow tanpa batas.

Cara Aman Migrasi dari Theme.json v2 ke v3

Setelah ngelihat semua breaking changes di atas, ini checklist migrasi yang bisa kamu ikuti. Simpan sebagai referensi tiap kali update tema.

• Step 1: Naikkan versi schema. Di paling atas theme.json, ganti "version": 2 jadi "version": 3. Tanpa ini, WP tetap parse pakai aturan v2 meskipun di WP 6.7. Tapi jangan lakukan ini sebelum step selanjutnya selesai.
• Step 2: Konversi spacingSizes. Cari semua object-style spacingSizes, ubah ke array format. Pastiin slug unik dan konsisten dengan CSS variable yang dihasilkan.
• Step 3: Audit fluid typography. Cek tiap fontSize preset. Tambahkan properti fluid eksplisit (true, false, atau object dengan min/max). Jangan biarkan inherit tanpa sengaja.
• Step 4: Deklarasikan semua layout settings. Tulis eksplisit contentSize dan wideSize di settings.layout. Jangan ngandelin default.
• Step 5: Uji di WordPress 6.7 staging. Jangan pernah update langsung di production. Spin up WP 6.7 instance, install tema kamu, dan cek semua template. Perhatikan spacing antar block, font scaling di mobile, dan alignment wide/full.
• Step 6: Update child theme. Kalau kamu maintain parent dan child theme, pastikan keduanya pakai versi schema yang sama. Mismatch versi antara parent dan child bisa bikin perilaku nggak terduga.

Backward Compatibility yang Masih Ada

Nggak semua dirombak total. Beberapa bagian theme.json tetap backward compatible. Kamu masih bisa pakai settings.color.palette dalam format array seperti v2. Custom properties di settings.custom juga nggak berubah. Dan yang paling penting: tema tanpa theme.json tetap berfungsi normal.

Yang berubah spesifik di: spacingSizes, typography.fluid, dan beberapa default value behavior. Sisanya masih sama. Jadi jangan panik, audit tiga area itu aja dulu.

Oh ya, kalau tema kamu masih banyak pakai CSS custom yang override theme.json, mungkin ini saatnya kamu baca artikel soal mengurangi CSS berlebih di block theme. Banyak yang bisa dipindah ke theme.json sekarang.

Fitur Baru Theme.json v3 yang Jarang Dibahas

Di balik breaking changes, ada beberapa fitur keren yang bikin theme author punya kontrol lebih presisi tanpa nulis CSS. Ini yang sering kelewat:

• Shadow presets granular. Kamu sekarang bisa definisikan inset shadow per preset, bukan cuma box-shadow biasa. Berguna buat efek depth yang lebih realistis di card component.
• Border width per-side. Di v2, border cuma satu nilai. Di v3, kamu bisa set border.top.width, border.bottom.width terpisah. Bikin aksen garis yang lebih kreatif.
• Appearance Tools split. appearanceTools sekarang bisa di-override per-block di styles.blocks. Jadi kamu bisa enable shadow di Button block tanpa enable di semua block.

Fitur ini belum banyak dibahas di dokumentasi resmi. Bahkan WordPress Developer Blog cuma menyinggung spacing dan fluid typography secara garis besar. Detail granular ini baru ketahuan kalau kamu baca commit history Gutenberg di GitHub repo Gutenberg.

Kapan Kamu Harus Peduli?

Kalau kamu cuma pengguna tema dari directory, kamu nggak perlu ngapa-ngapain. Theme author yang bertanggung jawab update. Tapi kalau kamu:

• Punya tema custom buat klien
• Jual tema di marketplace (ThemeForest, Creative Market)
• Maintain child theme yang override parent theme.json
• Pakai block theme open source yang udah lama nggak di-update

Maka kamu wajib audit sekarang juga. Jangan nunggu klien komplain layout-nya rusak. Baca juga hasil A/B test WP 6.7 biar kamu tahu dampak performa update ini secara keseluruhan.

FAQ: Theme.json v3 WordPress 6.7

Apakah tema tanpa theme.json tetap aman di WP 6.7?

Ya, aman sepenuhnya. Classic theme dan hybrid theme yang nggak pakai theme.json tidak terpengaruh sama sekali oleh perubahan ini. Perubahan hanya berlaku untuk block theme yang mendeklarasikan theme.json dengan "version": 3.

Bagaimana cara cek versi theme.json yang sedang dipakai?

Buka file theme.json di root tema kamu. Cari properti "version" di level paling atas. Kalau angkanya 2 atau nggak ada sama sekali, tema kamu masih pakai format lama. Kalau 3, sudah format baru.

Apa yang terjadi kalau spacingSizes masih pakai format object di v3?

WordPress 6.7 akan mengabaikan seluruh deklarasi spacingSizes tersebut. Tidak ada fallback, tidak ada warning. Preset spacing kamu hilang dari Editor dan CSS variables yang dihasilkan dari preset itu tidak akan muncul di frontend. Block yang mengandalkan preset tersebut akan menggunakan spacing default WordPress.

Apakah bisa downgrade theme.json dari v3 ke v2?

Secara teknis bisa, tapi sangat tidak disarankan. Kalau tema kamu sudah pakai fitur spesifik v3 (seperti spacing array format atau fluid per-preset), downgrade ke v2 akan menyebabkan data loss di pengaturan tersebut. Sebaiknya tetap di v3 dan pastikan semua deklarasi sudah sesuai.

Apakah child theme harus pakai versi theme.json yang sama dengan parent?

Idealnya ya. Kalau parent theme pakai v3 dan child theme override-nya masih pakai format v2, hasil merge-nya bisa tidak konsisten. WordPress akan merge kedua file lalu parse dengan aturan versi tertinggi yang ditemukan. Override dengan format lama bisa diabaikan sebagian atau seluruhnya.

Kesimpulan

Theme.json v3 adalah langkah WordPress menuju sistem yang lebih eksplisit dan presisi. Breaking changes di spacing, fluid typography, dan default values emang bikin pusing di awal. Tapi begitu tema kamu fully migrated, kontrol yang kamu dapat jauh lebih granular.

Anggap ini spring cleaning buat theme.json kamu. Buang format lama, deklarasikan semuanya secara eksplisit, dan uji di staging sebelum push ke production. Tema yang bersih secara struktur akan lebih mudah di-maintain dan lebih cepat rendering-nya, karena WP nggak perlu nebak-nebak intent kamu.

Kalau kamu nemu edge case atau perubahan lain di theme.json v3 yang belum dibahas di sini, drop di kolom komentar ya. Sharing pengalaman migrasi selalu berguna buat theme author lain.