WordPress theme.json کی وضاحت: settings، styles اور cascade

theme.json ایک block theme کی جڑ میں پڑی واحد کنفیگریشن فائل ہے جو دو الگ کام کرتی ہے: settings طے کرتا ہے کہ block editor صارف کو کیا پیش کرے، اور styles طے کرتا ہے کہ سائٹ ڈیفالٹ حالت میں کیسی دکھے۔ WordPress اسے پارس کرتا ہے، اپنے ڈیفالٹس اور Site Editor میں محفوظ کردہ ہر چیز کے ساتھ ملاتا ہے، اور نتیجہ ہر صفحے پر CSS custom properties اور ایک اِن لائن اسٹائل شیٹ کی شکل میں نکالتا ہے۔

انہی دو کاموں کو آپس میں گڈمڈ کر دینا وہ وجہ ہے جس کی بنا پر زیادہ تر theme.json تبدیلیاں بےاثر لگتی ہیں۔ settings کے نیچے رنگ لکھ دینے سے وہ رنگ کہیں لاگو نہیں ہوتا۔ اس سے صرف ایک variable بنتا ہے اور ایڈیٹر کے سائیڈبار میں ایک swatch آ جاتا ہے۔

اوپر کی سطح کی کلیدیں

کم سے کم فائل کچھ یوں دکھتی ہے:

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

کلید	یہ کیا کرتی ہے
$schema	صرف ایڈیٹر کی آٹو کمپلیٹ اور تصدیق کے لیے۔ WordPress اسے نظرانداز کرتا ہے۔
version	WordPress کو بتاتی ہے کہ کس اسکیما شکل کو پارس کرنا ہے۔ یہ آپ کے تھیم کا ورژن نہیں۔
settings	CSS variables بناتی ہے اور طے کرتی ہے کہ ایڈیٹر کیا دکھائے۔
styles	اصل ڈیفالٹ اسٹائلنگ لاگو کرتی ہے۔
templateParts	parts/ میں موجود حصے اور ان کا علاقہ بیان کرتی ہے۔
customTemplates	templates/ کے صفحہ ٹیمپلیٹس کو پوسٹ ایڈیٹر کے لیے رجسٹر کرتی ہے۔

version لوگوں کو اس لیے الجھاتا ہے کہ یہ تھیم کے ورژن نمبر جیسا لگتا ہے۔ ایسا نہیں ہے۔ یہ پارسنگ کا انداز چنتا ہے، اور پرانی WordPress ریلیزیں اُس اسکیما شکل کی کلیدیں خاموشی سے چھوڑ دیتی ہیں جسے وہ نہیں جانتیں۔ اگر آپ پرانی انسٹالیشنز کو سپورٹ کرتے ہیں تو وہی ورژن ہدف بنائیں جو وہ سمجھتی ہیں، بجائے اس کے کہ نئی کلیدوں کے شائستگی سے کم ہو جانے کی امید رکھیں۔ لکھنے کے وقت ورژن 3 موجودہ ہے؛ ورژن 2 اب بھی وسیع پیمانے پر چل رہا ہے اور اب بھی پارس ہوتا ہے۔

$schema WordPress کے میزبان کردہ ایک اسکیما URL کی طرف اشارہ کرتا ہے۔ اسے trunk پر رکھنے سے آپ کے کوڈ ایڈیٹر میں تازہ ترین اشارے ملتے ہیں؛ اگر آپ جان بوجھ کر پرانے اسکیما پر رہ رہے ہیں تو ورژن مخصوص URL زیادہ محفوظ ہے۔

settings: ایڈیٹر کیا پیش کرتا ہے

settings کے نیچے ہر چیز ایک CSS custom property بناتی ہے اور زیادہ تر صورتوں میں ایڈیٹر میں ایک کنٹرول بھی۔ 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"
    }
  }
}

اس سے 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 جیسی یوٹیلیٹی کلاسیں بھی بنتی ہیں، اور ایڈیٹر انہی کے ذریعے چنا ہوا swatch کسی block پر لگاتا ہے۔

"custom": false والی سطر settings کا دوسرا رخ ہے: آپشن بند کرنا۔ اسے لگا دیں تو من مانا رنگ چننے والا پکر غائب ہو جاتا ہے اور صارف کے پاس صرف آپ کا palette رہ جاتا ہے۔ یہی طریقہ ہر جگہ کام کرتا ہے — settings.typography.customFontSize، settings.spacing.customSpacingSize، settings.border، وغیرہ۔ settings کے نیچے کوئی چیز محض سجاوٹ نہیں؛ ہر کلید یا تو variable بڑھاتی ہے، یا کنٹرول بڑھاتی ہے، یا کنٹرول ہٹاتی ہے۔

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 کلیدیں kebab-case میں توڑ دی جاتی ہیں، اور نیسٹنگ کو ڈبل ڈیش سے جوڑا جاتا ہے۔ variable کا نام غلط لکھ دینا وہ عام وجہ ہے جس سے کوئی قدر خاموشی سے واپس اپنی ڈیفالٹ پر چلی جاتی ہے۔

آپ settings کو ہر block کے لیے الگ محدود کر سکتے ہیں، اور اسی طرح آپ بٹنوں پر رنگ کا پکر رکھ کر پیراگراف پر ہٹا سکتے ہیں:

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

جڑ کی سطح کے styles باڈی پر لگتے ہیں۔ elements ان HTML بنیادی عناصر کو سنبھالتا ہے جو block نہیں ہیں — link، button، سرخیاں، caption۔ blocks کسی مخصوص block کی قسم کو نام سے نشانہ بناتا ہے۔

کھری بات یہ ہے کہ styles وہ سب کچھ بیان نہیں کر سکتا جو CSS کر سکتی ہے۔ اپنے media queries لکھنے کا کوئی راستہ نہیں، پیچیدہ selectors نہیں، اینیمیشنز نہیں، اور صرف چند pseudo-class حالتیں سپورٹ ہیں۔ سیال ٹائپوگرافی اور لے آؤٹ پر مبنی سائزنگ اس کا بڑا حصہ ڈھانپ لیتی ہے جس کے لیے لوگ breakpoints استعمال کرتے تھے، مگر سارا نہیں۔ زیادہ تر شپ ہونے والی block themes theme.json کے ساتھ ایک مختصر اسٹائل شیٹ رکھتی ہیں، اور یہ ایک معمول کا نتیجہ ہے، ناکامی نہیں۔

settings بمقابلہ styles کا پھندا

سب سے زیادہ پوچھا جانے والا سوال کچھ اس طرح ہوتا ہے: “میں نے اپنا برانڈ رنگ شامل کیا اور کچھ نہیں بدلا۔”

بالکل درست۔ اسے settings.color.palette میں ڈالنے سے --wp--preset--color--brand اور ایک swatch بنا۔ لاگو کچھ نہیں ہوا۔ اسے لنک کا ڈیفالٹ رنگ بنانے کے لیے آپ کو اسے styles کے نیچے بھی لکھنا ہو گا:

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

اسے یوں سمجھیں: settings رنگوں کا وہ ڈبہ ہے جو آپ صارف کے ہاتھ میں دیتے ہیں، اور styles وہ پہلا کوٹ ہے جو آپ اس کے آنے سے پہلے خود چڑھا دیتے ہیں۔

cascade، سب سے نیچے سے سب سے اوپر تک

یہی حصہ اُس سائٹ کی وضاحت کرتا ہے جو تھیم فائل کو “نظرانداز” کرتی لگتی ہے۔ WordPress CSS نکالنے سے پہلے کئی تہیں ملاتا ہے:

1. WordPress core کے ڈیفالٹس — core اپنی theme.json کے ساتھ آتا ہے جس میں بنیادی palette، فونٹ سائز اور اسپیسنگ اسکیل موجود ہے۔
2. پیرنٹ تھیم کی theme.json
3. چائلڈ تھیم کی theme.json — یہ پیرنٹ کے اوپر کلید در کلید ملتی ہے، پوری فائل کی جگہ نہیں لیتی۔
4. ڈیٹابیس میں محفوظ Global Styles — جو Site Editor کا Styles پینل لکھتا ہے۔
5. انفرادی blocks پر لگے styles — پوسٹ کے مواد میں محفوظ خصوصیات، جو اِن لائن styles یا کلاسوں کی صورت رینڈر ہوتی ہیں۔

چوتھی تہہ ہی سائٹوں کو توڑتی ہے۔ جس لمحے کوئی Styles پینل کھول کر محفوظ کرتا ہے، WordPress ایک Global Styles ریکارڈ رکھ لیتا ہے اور اس ریکارڈ میں شامل ہر پراپرٹی کے لیے وہ آپ کی فائل پر بھاری پڑتا ہے۔ اس کے بعد theme.json میں ترمیم ان پراپرٹیز کے لیے کوئی نظر آنے والی تبدیلی نہیں لاتی، اور ڈیپلائے کے بعد سائٹ بالکل ویسی ہی دکھتی ہے جبکہ ڈسک پر پڑی فائل واضح طور پر مختلف ہے۔

اس کا حل محفوظ ریکارڈ مٹانا ہے، !important سے لڑائی بڑھانا نہیں۔ Site Editor کھولیں، Styles میں جائیں، revisions پینل کھولیں، اور تھیم کے ڈیفالٹس پر واپس جائیں۔ پہلے کلائنٹ یا سائٹ مالک سے تصدیق کر لیں — ریسیٹ کرنے سے ان کی تخصیصات ضائع ہو جاتی ہیں، جو ایک حقیقی قیمت ہے، مفت کام نہیں۔

دوسرا مشتبہ کردار کیشنگ ہے۔ 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 کی قدر اہم ہے: یہ طے کرتی ہے کہ حصہ ہیڈر یا فوٹر کے لینڈ مارک عنصر میں لپیٹا جائے یا نہیں، اور ایڈیٹر اسے کس زمرے میں رکھے۔ اسے چھوڑ دیں تو حصہ بغیر زمرے کے شمار ہوتا ہے۔

customTemplates ہی وہ چیز ہے جس سے کوئی ٹیمپلیٹ پوسٹ ایڈیٹر کی ٹیمپلیٹ فہرست میں دکھائی دیتا ہے۔ اس اندراج کے بغیر فائل موجود تو ہوتی ہے مگر کوئی اسے چن نہیں سکتا۔

تشخیص کی مختصر ترتیب

جب کوئی block theme اُس طرح اسٹائل نہ کرے جیسا فائل کہہ رہی ہے، تو کچھ بھی چھونے سے پہلے یہ ترتیب دیکھیں:

1. صفحے کا سورس دیکھیں اور جنریٹ شدہ گلوبل اسٹائلز کا حصہ تلاش کریں۔ اگر آپ کا variable وہاں نہیں ہے تو مسئلہ settings میں ہے یا slug کی املا میں۔
2. اگر variable موجود ہے مگر استعمال نہیں ہو رہا تو مسئلہ styles کے غائب اندراج کا ہے۔
3. اگر دونوں موجود ہیں مگر کوئی چیز ان پر حاوی ہو رہی ہے تو محفوظ Global Styles ریکارڈ دیکھیں۔
4. اس کے بعد ہی اپنی اسٹائل شیٹ، پلگ اِنز، یا کسی page builder کو دیکھیں جو cascade میں بعد میں CSS ڈال رہا ہو۔