تخطَّ إلى المحتوى

دليل المطوّر

ما تحتويه حزمة الثيم، وما يرفضه المُتحقِّق، وكيف يصل الإصدار إلى متجر.

ابدأ من هنا

أقصر طريق من لا شيء إلى قالب يقبله المراجع. كل خطوة أدناه يفحصها المدقّق نفسه، فالقالب الذي ينجح على جهازك ينجح عند التقديم.

  1. أنشئ الحزمة: «قالب جديد» في هذا الاستوديو، أو restro-theme init في سطر الأوامر. كلاهما يكتب الحزمة الأولى نفسها بكل ملفّاتها المطلوبة.
  2. اضبط الألوان في light.json وdark.json معاً. يُظهر الاستوديو أخطاء التباين أثناء الكتابة، قبل أن تقدّم شيئاً.
  3. عدّل المكوّنات أو أضفها: component.json يصف خصائصه، وtemplate.hbs بالمساعدات المسموحة، وstyles.css بالخصائص المنطقية.
  4. افحص، ثم عاين بالعربية والإنجليزية، فاتحاً وداكناً، بعرض الهاتف وسطح المكتب.
  5. أضف ثلاث لقطات على الأقل وقدّم. يعمل الفحص الآلي أولاً، ثم يراجع إنسانٌ ما يجتازه.
npx restro-theme init my-theme
cd my-theme
npx restro-theme validate      # the same checks as the studio
npx restro-theme dev           # a live preview on your machine
npx restro-theme login
npx restro-theme publish       # submits for review

الحزمة

الثيم هو بيان ولوحتا ألوان ومكوّن واحد أو أكثر وتخطيط لكل نوع صفحة. كل مسار أدناه ثابت: المثبِّت والمُتحقِّق وهذا الاستوديو يقرأون الأسماء نفسها.

my-theme/
├── theme.manifest.json
├── tokens/
│   ├── light.json
│   └── dark.json          mandatory
├── components/
│   └── <key>/
│       ├── component.json props schema + slots + regions
│       ├── template.hbs   allowed helpers only
│       └── styles.css     sanitized and scoped on upload
├── layouts/
│   ├── <page-type>.json
│   └── home.site-first.json  optional: "homeMode": "site_first" — a second home page
├── assets/
├── preview/               at least three screenshots
├── LICENSE
└── CHANGELOG.md

البيان حقلاً حقلاً

يصف theme.manifest.json القالب للسوق وللمثبّت. كل حقل إلزامي والحقول المجهولة مرفوضة، فالخطأ الإملائي يصير خطأً لا إعداداً لا يفعل شيئاً بصمت.

schemaVersion
صيغة البيان. استعمل ما تكتبه الحزمة الأولى.
key
معرّف القالب الدائم: أحرف إنجليزية صغيرة وأرقام وشرطات. لا يتغيّر بعد الإصدار الأوّل.
name
اسم القالب في السوق، بالعربية والإنجليزية.
description
جملة أو جملتان لبطاقة السوق، باللغتين.
version
Semver، يُرفع مع كل إصدار.
author
من صنعه، وكيف يصل إليك صاحب المطعم.
license
الترخيص الذي يُقدَّم به القالب، باسمه في SPDX أو ترخيصك الخاص.
platformCompat
إصدارات المنصّة التي يعمل معها القالب، كنطاق semver.
businessTypes
أنواع الأماكن التي صُمّم لها — مطعم، مقهى، مخبز وغيرها. يرى التاجر القوالب المطابقة لنوع مكانه.
supportedLocales
اللغات التي يوجد بها نصّ القالب نفسه. العربية والإنجليزية إلزاميتان.
colorModes
يجب أن يذكر الفاتح والداكن معاً.
defaultColorMode
الوضع الذي يراه الزائر قبل أن يختار: فاتح أو داكن أو حسب النظام.
pricing
مجاني، أو بسعر لمرّة واحدة أو متكرّر.
capabilities
ما يطلبه القالب فوق القوالب وCSS — جافاسكربت مخصّص، موارد خارجية. وكلٌّ منها يضيف مراجعة.
entry
أين يجد المثبّت الرموز والمكوّنات والتخطيطات داخل الحزمة.
presentation
Presentation
motion
Motion
content
Content

رموز التصميم

يعرّف كل ملف ألوان كل المفاتيح أدناه، في الوضعين. يقرؤها المتجر متغيّراتِ CSS، فالمكوّن الذي يستعمل var(--color-primary) يتبع التاجر حين يعيد تلوين القالب.

الألوان

  • primary
  • secondary
  • accent
  • background
  • surface
  • surfaceRaised
  • foreground
  • foregroundMuted
  • border
  • success
  • warning
  • danger
  • info

الخطوط

  • headingFont
  • bodyFont
  • baseSize
  • scale
  • headingWeight
  • bodyWeight

المسافات والأشكال

  • radius
  • containerWidth
  • sectionPadding
  • gap

أنماط المكوّنات

  • buttonStyle
  • cardStyle
  • navbarStyle
  • menuItemStyle

خيارات التخطيط

  • headerType
  • footerType
  • menuLayout
  • checkoutLayout

الوضعان إلزاميان

يوفّر الثيم ملفّي light.json و dark.json بالمفاتيح نفسها تمامًا. يرفض المُتحقِّق ثيمًا بوضع واحد، ويرفض ثيمًا يختلف وضعاه في مجموعة التوكنات. لا تستطيع المنصّة توليد الوضع الناقص بأمان، والزائر في الوضع الداكن على ثيم فاتح فقط يحصل على صفحة غير مقروءة.

التباين بوّابة لا نصيحة

يجب أن يبلغ نصّ المتن على كل سطح نسبة 4.5:1، والتعبئات ذات الدلالة 3:1، في الوضعين. الإخفاق خطأ يمنع التقديم. يُفحص تباين الحدود أيضًا لكنه ينبّه فقط، لأنّ دور الحدّ الواحد يغطّي إطارات الحقول والخطوط الزخرفية معًا.

أزواج الألوان التي يقيسها المدقّق في الوضعين
المقدّمة / الخلفيةالحدّ الأدنىالسبب
foreground / background4.5:1يجب أن يكون النص الأساسي مقروءًا على كل سطح يرسمه الثيم (المعيار 1.4.3).
foreground / surface4.5:1يجب أن يكون النص الأساسي مقروءًا على كل سطح يرسمه الثيم (المعيار 1.4.3).
foreground / surfaceRaised4.5:1يجب أن يكون النص الأساسي مقروءًا على كل سطح يرسمه الثيم (المعيار 1.4.3).
foregroundMuted / background4.5:1التسميات والأسعار والنصوص المساعدة تظل نصوصًا، والمعيار 1.4.3 لا يستثنيها.
foregroundMuted / surface4.5:1التسميات والأسعار والنصوص المساعدة تظل نصوصًا، والمعيار 1.4.3 لا يستثنيها.
foregroundMuted / surfaceRaised4.5:1التسميات والأسعار والنصوص المساعدة تظل نصوصًا، والمعيار 1.4.3 لا يستثنيها.
primary / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
primary / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
secondary / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
secondary / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
accent / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
accent / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
success / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
success / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
warning / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
warning / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
danger / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
danger / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
info / background3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
info / surface3:1يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11).
border / background3:1 · تحذير فقطحين يرسم هذا الدور حدود حقل إدخال أو حلقة تركيز يجب أن يبلغ 3:1 (المعيار 1.4.11)؛ أما كخط فاصل رفيع فيمكن أن يبقى أقل.
border / surface3:1 · تحذير فقطحين يرسم هذا الدور حدود حقل إدخال أو حلقة تركيز يجب أن يبلغ 3:1 (المعيار 1.4.11)؛ أما كخط فاصل رفيع فيمكن أن يبقى أقل.

المكوّنات

المكوّن مجلّد فيه component.json وtemplate.hbs وstyles.css. يعلن الملف JSON الخصائص التي يعدّلها التاجر — وكلٌّ منها يصير أداةً في منشئ الصفحات — والمناطق التي يجوز أن يوضع فيها.

أنواع الخصائص

  • string
  • text
  • richtext
  • number
  • boolean
  • color
  • image
  • url
  • select
  • object
  • array

المناطق

  • header
  • hero
  • main
  • sidebar
  • footer
  • floating

الفتحات تجعل المكوّن يحتوي مكوّنات أخرى، مع إمكان حصرها بمفاتيح وأعداد. خصائص الألوان تصل إلى القالب متغيّراتِ CSS خاصّة بالنسخة (--cmp-<prop>)، لا أنماطاً مضمّنة يحذفها المنقّي.

{
  "key": "hero-banner",
  "regions": ["hero"],
  "props": {
    "title":   { "type": "string",  "label": { "en": "Title", "ar": "العنوان" }, "required": true },
    "image":   { "type": "image",   "label": { "en": "Image", "ar": "الصورة" } },
    "overlay": { "type": "color",   "label": { "en": "Overlay", "ar": "التظليل" } },
    "align":   { "type": "select",  "label": { "en": "Align", "ar": "المحاذاة" },
                 "options": [ { "value": "start", "label": { "en": "Start", "ar": "البداية" } },
                              { "value": "center", "label": { "en": "Centre", "ar": "الوسط" } } ] }
  },
  "slots": []
}

القوالب

Handlebars بمجموعة مساعدات ثابتة ولا شيء غيرها. تُرفض الأقواس الثلاثية وصيغة العلامة & والكتل الخام لأنها تُخرج HTML بلا تهريب؛ وتُرفض الأجزاء والمزخرفات لأنّ هدفها يُحلّ وقت التصيير ولا يمكن فحصه قبل التنفيذ.

المساعدات المسموحة

  • if
  • unless
  • each
  • t
  • money
  • date
  • img
  • url
  • eq
  • ne
  • gt
  • lt
  • and
  • or
  • not
  • concat

متغيّرات البيانات المسموحة

  • @index
  • @key
  • @first
  • @last

مرفوضة بالاسم

  • with
  • log
  • lookup
  • blockHelperMissing
  • helperMissing

أوراق التنسيق

يُعقَّم CSS الخاص بك ويُحصر في نسخة المكوّن قبل التخزين. تُزال import و expression() و behavior و ‎-moz-binding؛ ولا يشير url() إلا إلى صورة data أو إلى نطاق يعلنه البيان؛ وتتحوّل position: fixed إلى absolute حتى لا يغطّي مكوّن صفحة الدفع.

استخدم الخصائص المنطقية. تعمل padding-inline و margin-inline-start بشكل صحيح في العربية والإنجليزية بقاعدة واحدة؛ أمّا padding-left فتصحّ في واحدة فقط.

جافاسكربت

إعلان capabilities.customJs يرسل الإصدار إلى مراجع بشري دائمًا. يُنفَّذ السكربت داخل إطار على أصل منفصل بلا وصول إلى المتجر: لا كوكيز ولا تخزين ولا مستند أب. ولا يصل إلى الصفحة إلا عبر مجموعة مغلقة من أوامر DOM موجّهة إلى أسماء data-ref يعلنها قالبك.

من المسودّة إلى المتجر

يصبح الإصدار الذي تقدّمه مُقدَّمًا، ثم يُفحص آليًا، ثم ينتقل إلى قيد المراجعة. يقبله مراجع أو يرفضه بأسباب تقرأها في صفحة الثيم. القبول والنشر فعلان منفصلان بصلاحيتين منفصلتين، لذا ينتظر الإصدار المقبول قبل عرضه على التجّار.

لماذا تُرفض الإصدارات

يرفض الفحص الآلي الإصدار برمز يظهر في صفحة قالبك. هذه أكثرها شيوعاً، وما الذي يجب تغييره.

TOKENS_MODE_KEY_MISMATCH
يعرّف light.json وdark.json مفاتيح مختلفة. عرّف كل مفتاح في الملفّين.
TOKENS_CONTRAST_FAIL
زوج ألوان مطلوب دون حدّه الأدنى في أحد الوضعين. الجدول أعلاه يذكر كل زوج؛ عدّل الطرف الأغمق أو الأفتح.
MANIFEST_SCHEMA
حقل في البيان مفقود أو مكتوب خطأً أو من نوع خاطئ. الرسالة تسمّي الحقل.
MANIFEST_PLATFORM_LOCALE_MISSING
العربية أو الإنجليزية غير مذكورة في supportedLocales.
HB_TRIPLE_STACHE
قالب يستعمل {{{ }}}، التي تطبع HTML دون تهريب. استعمل {{ }} والمساعدات المتاحة.
HB_UNKNOWN_HELPER
قالب يستدعي مساعداً خارج القائمة المسموحة. استعمل واحداً من القائمة أعلاه.
CSS_URL_HOST
رابط url() يشير إلى مضيف لا يعلنه البيان. أعلنه تحت capabilities، أو ضمّن الصورة.
CSS_POSITION_FIXED
position: fixed يُعاد كتابته إلى absolute كي لا يغطّي شيءٌ صفحة الدفع. رتّب المكوّن من دونه.
JS_STORAGE
السكربت يلمس localStorage أو sessionStorage. لا تخزين لسكربتات القوالب؛ أبقِ الحالة في الصفحة.
CHECKSUM_UNSAFE_PATH
مسار ملفّ يخرج من الحزمة (../ أو مسار مطلق). أبقِ كل ملفّ داخل مجلّد القالب.

ما يعيده المراجع

  • أقلّ من ثلاث لقطات، أو لقطات لا تُظهر القالب كما قُدِّم.
  • تخطيط عربي مكسور: نصّ يجري في الاتجاه الخاطئ، أيقونات غير معكوسة، أو حشو في الجهة الخاطئة.
  • صفحات تنكسر بلا قائمة أو صور أو مراجعات — والمطعم الجديد بلا الثلاثة.
  • نوع صفحة بلا تخطيط، فيلجأ المثبّت فيه إلى تخطيط المنصّة الافتراضي.
  • خطوط أو صور أو شيفرة مضمّنة بلا ترخيص يسمح بذلك.

الإصدارات

Semver، وملاحظات إصدار ابتداءً من الإصدار الثاني. يصل إصدار التصحيح إلى التجّار الذين فعّلوا التحديث التلقائي؛ وينتظر الإصدار الأصغر أو الأكبر قبول كل تاجر. سحب إصدار يمنع التثبيتات الجديدة دون كسر المتاجر التي تشغّله.

سطر الأوامر

يشغّل هذا الاستوديو و theme-cli المُتحقِّقات نفسها على صيغة الحزمة نفسها، فما يجتاز هنا يجتاز هناك. سطر الأوامر هو ما تريده لمستودع وخطّ أنابيب وأرشيف ‎.rtheme موقّع؛ والاستوديو هو ما تريده للوحة الألوان والمعاينة.

الحدود

البيان
64 KiB
القالب
128 KiB
ورقة التنسيق
256 KiB
السكربت
128 KiB
لقطات الشاشة
من 3 إلى 12