WordPress theme.json समझिए: settings, styles और cascade

theme.json एक block theme की जड़ में रखी एक ही configuration फ़ाइल है जो दो अलग-अलग काम करती है: settings तय करता है कि block editor उपयोगकर्ता को क्या देगा, और styles तय करता है कि साइट default रूप में दिखेगी कैसी। WordPress इसे parse करता है, अपनी खुद की defaults और Site Editor में सहेजी गई हर चीज़ के साथ merge करता है, और नतीजे को हर पेज पर CSS custom properties तथा एक inline stylesheet के रूप में निकालता है।

इन दोनों कामों को आपस में गड्डमड्ड कर देना ही वह वजह है जिससे ज़्यादातर theme.json edits कुछ करती हुई नहीं लगतीं। settings के नीचे कोई रंग घोषित करने से वह रंग कहीं भी लागू नहीं होता। उससे सिर्फ़ एक variable बनता है और editor sidebar में एक swatch आ जाता है।

शीर्ष-स्तर की keys

एक न्यूनतम फ़ाइल कुछ ऐसी दिखती है:

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

Key	यह क्या करती है
$schema	सिर्फ़ editor का autocomplete और validation। WordPress इसे अनदेखा करता है।
version	WordPress को बताती है कि किस schema आकार के हिसाब से parse करना है। यह आपके theme का version नहीं है।
settings	CSS variables बनाती है और तय करती है कि editor क्या दिखाएगा।
styles	असली default styling लागू करती है।
templateParts	parts/ में मौजूद parts और वे किस area के हैं, यह घोषित करती है।
customTemplates	templates/ की page templates को post editor के लिए register करती है।

version लोगों को इसलिए उलझाता है क्योंकि यह theme के version number जैसा दिखता है। है नहीं। यह parsing का तरीक़ा चुनता है, और पुरानी WordPress रिलीज़ें उस schema आकार की keys चुपचाप छोड़ देती हैं जिसे वे नहीं जानतीं। अगर आप पुराने installs को सपोर्ट करते हैं, तो यह मान लेने के बजाय कि नई keys अपने आप ठीक से degrade हो जाएँगी, उसी version को target कीजिए जिसे वे installs समझते हैं। लिखे जाने के समय version 3 चालू है; version 2 अब भी व्यापक रूप से तैनात है और अब भी parse होता है।

$schema WordPress द्वारा होस्ट किए गए एक schema URL की ओर इशारा करता है। उसे trunk पर रखने से आपके code editor में सबसे नए hints मिलते हैं; अगर आप जानबूझकर पुराने schema पर टिके हैं तो version-विशिष्ट URL ज़्यादा सुरक्षित है।

settings: editor क्या देगा

settings के नीचे की हर चीज़ एक CSS custom property बनाती है और ज़्यादातर मामलों में editor में एक control भी। settings के नीचे कुछ भी किसी चीज़ को style नहीं करता।

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

इससे preset के रास्ते और slug से बने नामों वाले variables निकलते हैं:

--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 जैसी utility classes भी बनती हैं — editor चुने हुए swatch को block पर इन्हीं के ज़रिए लगाता है।

"custom": false वाली line settings का दूसरा पहलू है: विकल्प बंद करना। इसे लगा दीजिए और मनमाना रंग चुनने वाला picker ग़ायब हो जाता है, उपयोगकर्ता के पास सिर्फ़ आपका palette बचता है। यही तरीक़ा हर जगह चलता है — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border, वग़ैरह। settings के नीचे कुछ भी सजावटी नहीं है; हर key या तो एक variable जोड़ती है, या एक control जोड़ती है, या एक control हटाती है।

settings.custom आपके अपने variables के लिए एक खुला डिब्बा है:

{
  "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 keys टूटकर kebab-case हो जाती हैं, और nesting दो dashes से जुड़ती है। variable का नाम ग़लत लिख देना वह आम वजह है जिससे कोई value चुपचाप fallback पर चली जाती है।

आप settings को हर block के हिसाब से सीमित कर सकते हैं — buttons पर रंग picker देना और paragraphs पर न देना इसी तरह होता है:

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

styles: असल में render क्या होता है

styles वह जगह है जहाँ values लागू होती हैं। इसकी बनावट editor जैसी ही है: पहले एक root स्तर, फिर 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)" } }
      }
    }
  }
}

Root स्तर की styles body पर जाकर बैठती हैं। elements उन HTML primitives को संभालता है जो block नहीं हैं — link, button, headings, caption। blocks किसी ख़ास block type को नाम से निशाना बनाता है।

एक ईमानदार सीमा: styles वह सब कुछ व्यक्त नहीं कर सकता जो CSS कर सकती है। इसमें अपनी media queries लिखने का कोई रास्ता नहीं, जटिल selectors नहीं, animations नहीं, और pseudo-class states का बस एक छोटा सा समर्थित सेट। Fluid typography और layout-आधारित sizing उस बहुत कुछ को ढँक लेती हैं जिसके लिए लोग breakpoints इस्तेमाल करते थे, पर सब कुछ नहीं। ज़्यादातर चालू block themes theme.json के साथ एक छोटी stylesheet भी रखती हैं, और यह सामान्य नतीजा है, नाकामी नहीं।

settings बनाम styles वाला जाल

सबसे आम सवाल किसी न किसी रूप में यही होता है: “मैंने अपना brand रंग जोड़ा और कुछ नहीं बदला।”

सही है। उसे settings.color.palette में जोड़ने से --wp--preset--color--brand और एक swatch बना। लागू कुछ नहीं हुआ। उसे default link रंग बनाने के लिए आपको उसे styles के नीचे भी लिखना होगा:

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

इसे यूँ पढ़िए: settings रंगों का वह डिब्बा है जो आप उपयोगकर्ता को थमाते हैं, और styles वह पुताई है जो आप उनके आने से पहले ख़ुद कर देते हैं।

Cascade, सबसे नीचे से सबसे ऊपर तक

यही वह हिस्सा है जो उस साइट की व्याख्या करता है जो theme फ़ाइल को “अनदेखा” करती लगती है। CSS निकालने से पहले WordPress कई परतें merge करता है:

1. WordPress core की defaults — core अपनी ख़ुद की theme.json भेजता है जिसमें एक बुनियादी palette, font sizes और spacing scale होता है।
2. Parent theme की theme.json
3. Child theme की theme.json — parent के ऊपर key-दर-key merge होती है, पूरी फ़ाइल की जगह नहीं लेती।
4. Database में सहेजी गई Global Styles — Site Editor का Styles panel यही लिखता है।
5. अलग-अलग blocks पर लगी per-block styles — post content में सहेजे गए attributes, जो inline styles या classes के रूप में render होते हैं।

परत 4 ही साइटें तोड़ती है। जिस पल कोई Styles panel खोलकर Save दबाता है, WordPress एक Global Styles record सहेज लेता है, और उसमें मौजूद हर property के लिए वह record आपकी फ़ाइल से जीत जाता है। उसके बाद theme.json में बदलाव करने से उन properties के लिए कुछ भी दिखाई देने वाला नहीं बदलता — deploy के बाद साइट बिल्कुल वैसी ही दिखती है जबकि डिस्क पर फ़ाइल साफ़ तौर पर अलग है।

फिक्स है उस सहेजे गए record को हटाना, न कि !important लगाकर लड़ाई बढ़ाना। Site Editor खोलिए, Styles में जाइए, revisions panel खोलिए, और theme की defaults पर reset कर दीजिए। पहले क्लाइंट या साइट मालिक से पुष्टि कर लीजिए — reset करने से उनके customizations चले जाते हैं, और यह असली नुक़सान है, मुफ़्त कार्रवाई नहीं।

दूसरा संदिग्ध है caching। WordPress हर request पर फ़ाइल दोबारा पढ़ने के बजाय parse किए गए theme.json डेटा को cache कर लेता है — production में आपको यही चाहिए और development में यही नहीं चाहिए। WP_DEBUG चालू करने पर, या नई रिलीज़ों में theme development mode की setting चालू करने पर, WordPress हर बार फ़ाइल दोबारा पढ़ता है। अगर आपके बदलाव सिर्फ़ deploy या cache flush के बाद दिखते हैं, तो आप यही देख रहे हैं।

templateParts और customTemplates

दोनों ऐसी arrays हैं जो आपके theme में पहले से पड़ी फ़ाइलों का ब्यौरा देती हैं।

{
  "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 की value मायने रखती है: यही तय करती है कि part header या footer landmark element में लिपटेगा या नहीं, और editor उसे किस श्रेणी में रखेगा। इसे छोड़ दीजिए तो part बिना श्रेणी का मान लिया जाता है।

customTemplates ही वह चीज़ है जिससे कोई template post editor के template dropdown में दिखती है। यह entry न हो तो फ़ाइल मौजूद तो रहती है पर कोई उसे चुन नहीं सकता।

जाँच का त्वरित क्रम

जब कोई block theme उस तरह style नहीं कर रही जैसा फ़ाइल कहती है, तो कुछ भी छूने से पहले यह क्रम पूरा कीजिए:

1. Page का source देखिए और generated global styles वाला हिस्सा खोजिए। अगर आपका variable वहाँ नहीं है, तो गड़बड़ settings में है या slug में टाइपो है।
2. अगर variable मौजूद है पर कहीं इस्तेमाल नहीं हो रहा, तो गड़बड़ यह है कि styles वाली entry नहीं है।
3. अगर दोनों मौजूद हैं पर कोई चीज़ उन्हें override कर रही है, तो सहेजा गया Global Styles record जाँचिए।
4. उसके बाद ही अपनी stylesheet, plugins, या cascade में बाद में CSS डालने वाले किसी page builder की तरफ़ देखिए।