شرح theme.json في ووردبريس: إعدادات التصميم والألوان والتخطيط

أهلاً بك يا بطل في المحطة رقم 95 من سلسلتنا المعمارية الشاملة في ووردبريس! لو كنت مطور ووردبريس مخضرم، أكيد فاكر المعاناة القديمة: كنت عشان تعمل لوحة ألوان للثيم، تروح تعرفها في مصفوفة PHP عبر add_theme_support('editor-color-palette', ...)، وبعدين تروح تكتب نفس الألوان دي يدوي في ملف style.css كفئات مثل .has-primary-color، وبعدين تكرر نفس الكلام للـ font sizes ومقاسات الخطوط! لو غيرت كود لون واحد، كنت بتلف على خمس ملفات تعدل فيها وتدعي ربنا ما تكونش نسيت حاجة!

كل هذه الفوضى العارمة انتهت رسمياً للأبد مع ظهور ملف theme.json. هذا الملف البسيط في شكله، الجبار في بنيته المعمارية، هو العقل المدبر لنظام التصميم العالمي (Global Design System) في ووردبريس الحديث. في هذا المقال الشامل، هنشرح theme.json من الألف إلى الياء، هنفهم الفروق الدقيقة بين قسم settings وقسم styles، إزاي الكور بيولد الـ CSS Custom Properties في أجزاء من الثانية، إزاي تقيد صلاحيات المحررين وتمنعهم من تدمير الهوية البصرية، وهنستعرض كود حقيقي ودراسة حالة عملية من قلب السوق المصري!

المفهوم المعماري: ما هو ملف theme.json ولماذا غير قواعد اللعبة؟

ملف theme.json هو ملف تكوين تصريحي (Declarative Configuration File) يوضع في المجلد الجذري للقالب (سواء كان Block Theme بالكامل أو حتى Classic Theme يتبنى نظام الكتل). بدلاً من كتابة كود إجرائي (Imperative Code) في PHP لإخبار ووردبريس بما تريده، أنت تعلن في هذا الملف عن نظام التصميم الخاص بك كـ Data Structure نقية.

عندما يقلع ووردبريس، يقوم صنف مخصص في النواة اسمه WP_Theme_JSON_Processor و WP_Theme_JSON_Resolver بقراءة ملفات الـ JSON المختلفة (ملف الكور الافتراضي، ثم ملف القالب الأب، ثم ملف القالب الابن، ثم تخصيصات المستخدم من قاعدة البيانات)، ويدمجها وفق خوارزمية وراثة دقيقة (Inheritance & Merge Hierarchy). الناتج النهائي هو:

• توليد مئات من متغيرات CSS في الـ :root وفي كتل محددة.
• تفعيل أو تعطيل أدوات وميزات محددة في الشريط الجانبي لمحرر جوتنبرج (Inspector Controls).
• تطبيق التنسيقات العامة على عناصر الـ HTML الأساسية (Body, Headings, Links, Buttons).

تطور الإصدارات: من Schema Version 2 إلى Version 3 في WordPress 6.6+

بدأ ملف theme.json بإصدار version: 1 في المراحل التجريبية الأولى، ثم استقر مع ووردبريس 5.8 في version: 2. ومع إطلاق ووردبريس 6.6، تم تقديم version: 3 كمعيار رسمي حديث يقدم تحسينات معمارية فائقة:

• توحيد تباعد الشبكات (Grid Spacing): إمكانية ضبط خصائص الـ Grid Layout والتباعد بين الأعمدة بشكل أكثر دقة داخل قسم layout.
• دعم لوحات الألوان والخطوط الفرعية (Section Styles): القدرة على تطبيق نظام ألوان وتنسيقات كاملة على أقسام معينة داخل الصفحة دون التأثير على الموقع بأكمله.
• إلغاء بعض المسميات القديمة: تحسين أسماء الخصائص البرمجية لتكون أكثر اتساقاً مع معايير CSS الحديثة وأسهل في التحقق عبر الـ JSON Schema.

التشريح الثنائي الأساسي: الفرق الحاسم بين Settings و Styles

لو سألت أي مطور بيغلط في theme.json، هتلاقي السبب الأكبر إنه بيتلخبط بين settings و styles. القاعدة الذهبية هنا سهلة جداً وبسيطة:

• قسم Settings (الإعدادات والأدوات والخيارات): هنا أنت تحدد ما هو المتاح للمحرر وما هي الأدوات المفعلة. أنت بتعرف لوحة الألوان (القيم المتاحة)، مقاسات الخطوط، التباعد، وهل تظهر أداة الـ Border في الشريط الجانبي أم تختفي. هذا القسم لا يطبق لوناً على عنصر محدد، بل يتيح الألوان للاختيار ويولد متغيرات CSS لها!
• قسم Styles (التنسيقات الفعلية المطبقة): هنا أنت تحدد ما هو المطبق بالفعل على الصفحة أو الكتل بشكل افتراضي. هنا تقول: “أنا عايز خلفية الـ body تكون كحلي داكن، ولون الروابط أخضر، وحجم الخط الأساسي 18 بكسل، وكتلة الاقتباس (core/quote) يكون لها إطار رمادي على اليمين”.

جدول المقارنة المعمارية: قسم Settings في مواجهة قسم Styles

محرك توليد متغيرات CSS: كيف يحول ووردبريس الـ JSON إلى أنماط حية؟

هل تساءلت يوماً عن الصيغة الغريبة لمتغيرات ووردبريس مثل --wp--preset--color--emerald-500؟ ووردبريس يتبع خوارزمية صارمة مبنية على مسار المفاتيح (Key Path Resolution):

1. البداية دائماً بالبادئة المزدوجة: --wp--
2. ثم نوع التصنيف الفرعي: preset-- للخيارات المسبقة، أو custom-- للقيم الخاصة القديمة.
3. ثم الخاصية: color-- أو spacing-- أو font-size-- أو font-family--.
4. ثم الـ Slug الذي قمت بتحديده في الـ JSON: مثلاً primary.

النتيجة هي متغير قياسي: --wp--preset--color--primary. وعندما تريد الإشارة إلى هذا المتغير داخل قسم styles في نفس ملف الـ JSON، لا تكتب var(...) مباشرة، بل تستخدم الصيغة المعيارية لووردبريس: "color": "var:preset|color|primary"، وسيقوم الكور بتحويلها تلقائياً إلى صيغة المتصفح الصحيحة var(--wp--preset--color--primary) أثناء تصيير الصفحة!

كود عملي متكامل: ملف theme.json احترافي يدعم الفونت العربي وFluid Typography

إليك ملف theme.json كامل وجاهز للاستخدام في الإنتاج، معد خصيصاً للمواقع العربية المتطورة:

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "settings": {
        "appearanceTools": true,
        "layout": {
            "contentSize": "860px",
            "wideSize": "1280px"
        },
        "color": {
            "custom": false,
            "customDuotone": false,
            "customGradient": false,
            "palette": [
                {
                    "slug": "primary",
                    "color": "#0284c7",
                    "name": "أزرق سماوي قيادي"
                },
                {
                    "slug": "secondary",
                    "color": "#0f766e",
                    "name": "أخضر تركوازي مساند"
                },
                {
                    "slug": "dark-base",
                    "color": "#0f172a",
                    "name": "كحلي داكن للنصوص"
                },
                {
                    "slug": "light-surface",
                    "color": "#f8fafc",
                    "name": "رمادي فاتح للخلفيات"
                },
                {
                    "slug": "pure-white",
                    "color": "#ffffff",
                    "name": "أبيض ناصع"
                }
            ]
        },
        "typography": {
            "fluid": true,
            "fontFamilies": [
                {
                    "fontFamily": "Cairo, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "name": "Cairo Arabic",
                    "slug": "cairo",
                    "fontFace": [
                        {
                            "fontFamily": "Cairo",
                            "fontWeight": "400 700",
                            "fontStyle": "normal",
                            "fontDisplay": "swap",
                            "src": [ "file:./assets/fonts/cairo-variable.woff2" ]
                        }
                    ]
                }
            ],
            "fontSizes": [
                {
                    "name": "صغير",
                    "size": "0.875rem",
                    "slug": "small"
                },
                {
                    "name": "عادي",
                    "size": "1.125rem",
                    "slug": "medium",
                    "fluid": {
                        "min": "1rem",
                        "max": "1.125rem"
                    }
                },
                {
                    "name": "كبير",
                    "size": "1.5rem",
                    "slug": "large",
                    "fluid": {
                        "min": "1.25rem",
                        "max": "1.75rem"
                    }
                },
                {
                    "name": "عملاق للعناوين الرئيسية",
                    "size": "2.5rem",
                    "slug": "x-large",
                    "fluid": {
                        "min": "1.75rem",
                        "max": "3rem"
                    }
                }
            ]
        },
        "spacing": {
            "spacingScale": {
                "operator": "*",
                "increment": 1.5,
                "steps": 7,
                "mediumStep": 1.5,
                "unit": "rem"
            }
        }
    },
    "styles": {
        "color": {
            "background": "var:preset|color|light-surface",
            "text": "var:preset|color|dark-base"
        },
        "typography": {
            "fontFamily": "var:preset|font-family|cairo",
            "fontSize": "var:preset|font-size|medium",
            "lineHeight": "1.8"
        },
        "elements": {
            "link": {
                "color": {
                    "text": "var:preset|color|primary"
                },
                ":hover": {
                    "color": {
                        "text": "var:preset|color|secondary"
                    }
                }
            },
            "heading": {
                "typography": {
                    "fontWeight": "700",
                    "lineHeight": "1.3"
                },
                "color": {
                    "text": "var:preset|color|dark-base"
                }
            },
            "button": {
                "color": {
                    "background": "var:preset|color|primary",
                    "text": "var:preset|color|pure-white"
                },
                "border": {
                    "radius": "0.5rem"
                },
                "spacing": {
                    "padding": {
                        "top": "0.75rem",
                        "bottom": "0.75rem",
                        "left": "1.5rem",
                        "right": "1.5rem"
                    }
                }
            }
        },
        "blocks": {
            "core/quote": {
                "border": {
                    "right": {
                        "color": "var:preset|color|primary",
                        "style": "solid",
                        "width": "4px"
                    }
                },
                "spacing": {
                    "padding": {
                        "right": "1.5rem"
                    }
                }
            }
        }
    }
}

تقييد تجربة المحرر (Editor Curation): قفل الألوان والخطوط لحماية الهوية

أكبر كابوس يواجه وكالات التصميم والبرمجة هو أنك تسلم الموقع للعميل بعد أسابيع من ضبط الهوية البصرية، وتفاجأ بعد أسبوع إن كاتب المحتوى حاطط خلفية صفراء فاقعة وخط أحمر فوسفوري وحجم خط 70px في نص المقال!

عبر ملف theme.json، تقدر تتحكم بدقة مطلقة وتصنع ما يسمى بـ Curated Experience:

• منع اختيار ألوان مخصصة: بضبط "custom": false في قسم color، يختفي منتقي الألوان اللوني (Color Picker) تماماً، ولا يتبقى أمام المحرر إلا الألوان الرسمية المعرفة في اللوحة فقط.
• منع التدرجات والظلال العشوائية: بضبط "customGradient": false و "shadow": { "defaultPresets": false }، تحمي الواجهة من تشوهات الظلال والتدرجات المزعجة.
• تعطيل تغيير أحجام الخطوط العشوائية: بضبط "customFontSize": false، يلتزم المحرر بأحجام الخطوط الأربعة أو الخمسة القياسية المصممة بدقة.
• قفل خواص على مستوى كتل محددة: تقدر مثلاً تسمح بالتباعد المخصص (Padding) في كتلة core/group ولكن تمنعه تماماً في كتل core/paragraph للحفاظ على إيقاع القراءة المنتظم.

دراسة حالة حقيقية: وكالة تسويق في التجمع الخامس وأزمة الألوان العشوائية

الوصايا العشر لمهندسي theme.json المحترفين

1. ابدأ دائماً بربط الـ JSON Schema: ضع السطر "$schema": "https://schemas.wp.org/trunk/theme.json" في أول الملف لتستمتع بالإكمال التلقائي والتحقق الفوري من الأخطاء في VS Code.
2. لا تكتب قيماً لونية صلبة (Hex Codes) في قسم styles: استخدم دائماً مراجع الـ Presets عبر صيغة var:preset|color|slug لضمان ترابط النظام إذا تغير اللون لاحقاً.
3. أغلق منتقي الألوان العشوائي في مشاريع الشركات: اضبط "custom": false لحماية تصميمك من عبث المحررين ومحاولاتهم الفردية.
4. اعتمد على Fluid Typography دائماً: استخدم الإعداد "fluid": true لتجعل الخطوط متجاوبة تلقائياً مع حجم الشاشة دون صداع الميديا كويري.
5. نظم هوامش التباعد بمقياس قياسي (Spacing Scale): لا تترك مسافات البادينج عشوائية؛ حدد درجات تباعد منتظمة لتوحيد الفراغات في كافة الصفحات.
6. استخدم قسم elements لتنسيق الروابط والأزرار: وفر كتابة مئات أسطر الـ CSS بتعريف ألوان وحالات الـ :hover للأزرار والروابط مباشرة في elements.
7. اجعل الخطوط محملة ذاتياً (Self-hosted Fonts): لا تعتمد على روابط Google Fonts الخارجية لتفادي مشاكل الخصوصية وبطء الـ DNS؛ خزن خطوط WOFF2 داخل مجلد الثيم.
8. استفد من Section Styling في WordPress 6.6+: عرف أنماطاً متباينة للأقسام (مثل الأقسام المظلمة والأقسام المضيئة) كـ Style Variations لسهولة تطبيقها.
9. لا تخزن منطقاً برمجياً في ملفات JSON: ملف theme.json للبيانات التكوينية فقط؛ العمليات الشرطية مكانها كود PHP أو فلاتر ووردبريس.
10. افحص الـ Output في المتصفح باستخدام Inspect Elements: تأكد من أن المتغيرات المحدثة تظهر تحت الوسم :root وأن ترتيب الأسبقية يسير كما خططت له.

الغوص المعماري: إدارة Style Variations و Custom Templates في theme.json

يا صديقي المطور، واحدة من أقوى الميزات التي تميز ووردبريس الحديث عن أي نظام إدارة محتوى آخر هي ميزة Style Variations (أو تنويعات الأنماط). زمان، لو العميل طلب منك وضع ليلي (Dark Mode) أو لوحة ألوان مختلفة لموسم الصيف أو رمضان، كنت بتضطر تعمل قالب فرعي جديد أو تكتب آلاف الأسطر من الـ CSS Override المعقد اللي بيبهدل الأداء.

في عالم theme.json، الموضوع أصبح في منتهى النقاء البرمجي: كل اللي عليك تعمله هو إنشاء مجلد باسم styles/ داخل القالب بتاعك، وتحط جواه ملفات JSON منفصلة، مثل styles/dark.json أو styles/cairo-sunset.json. هذه الملفات لا تحتاج لتكرار كل شيء؛ يكفي أن تعيد تعريف قسم styles أو لوحة الـ palette فقط!

// styles/dark.json
{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "title": "النمط الليلي الفاخر (Dark Mode)",
    "styles": {
        "color": {
            "background": "var:preset|color|dark-base",
            "text": "var:preset|color|light-surface"
        },
        "elements": {
            "link": {
                "color": {
                    "text": "var:preset|color|secondary"
                }
            }
        }
    }
}

بمجرد وضع هذا الملف، ووردبريس تلقائياً بيتعرف عليه ويعرضه في محرر الموقع تحت تبويب “Styles”، وبضغطة زر واحدة من العميل أو مدير الموقع، الموقع بالكامل بيتحول للنمط الليلي دون كتابة سطر كود واحد! الكور بيقوم بتبديل قيم متغيرات الـ CSS بسلاسة فائقة، مع الحفاظ على كاش المتصفح والأداء الاستثنائي.