السمات

هذه الصفحة مترجمة من الإنجليزية. اقرأ الصفحة الإنجليزية

الحالة: منفذة في crates/zeyn/assets/zeyn.css.

تقرأ مجموعة واجهة المستخدم الافتراضية كل لون وخط وحجم ونصف قطر زاوية من خصائص CSS المخصصة في :root. تغيّر المؤسسة المظهر بتجاوز عدد قليل منها، ولا تحتاج إلى تعديل zeyn.css ولا إلى كتابة محددات.

1. كيف تُطبَّق السمة

يقدّم الخادم zeyn.css أولاً، ثم ورقة أنماط إضافية فيها تجاوزات الرموز (tokens) إن كان للتطبيق ورقة كهذه. يحتوي ملف التجاوز على كتل :root فقط:

:root {
  --z-brand: #7a2448;
  --z-font: "Source Sans 3", "Segoe UI", system-ui, sans-serif;
  --z-radius: 8px;
  --z-density: 0.75;
}

قواعد ملف التجاوز:

• يجب تقديمه من أصل التطبيق نفسه. سياسة أمان المحتوى (Content Security Policy) هي style-src 'self'، لذلك تُحجب كتل <style> المضمنة وأوراق الأنماط الصادرة عن أطراف خارجية.
• يجب أن تكون الخطوط مثبتة مسبقاً على أجهزة المستخدمين أو أن تُقدَّم من أصل التطبيق. المجموعة نفسها لا تحمّل أي خطوط ويب.
• حمّله بعد zeyn.css، حتى تفوز المحددات المتساوية بحسب الترتيب.
• اضبط الرموز الأساسية في القسم 2. تتبعها الرموز المشتقة في القسم 3 تلقائياً. لا تتجاوز رمزاً مشتقاً إلا إذا كانت القيمة المحسوبة لا تناسب علامتك التجارية.

السمات الفاتحة والداكنة وسمات التطبيق

لكل تطبيق منتقي سمات في القائمة، بجوار منتقي اللغة. يعرض النظام (يتبع prefers-color-scheme) والفاتحة والداكنة وأي سمة يعرّفها التطبيق:

App::new("Billing")
    .theme(Theme::new().brand("#7a2448").radius(6))
    .themes([
        Theme::light(),
        Theme::dark(),
        Theme::named("sand", [("--z-bg", "#f5f1ea"), ("--z-surface", "#fffdf8")]).label(t!("theme.sand")),
    ])
    .default_theme("system")

• App::theme هو مظهر المؤسسة، ويُطبَّق تحت كل سمة.
• App::themes يسرد ما يستطيع المستخدمون اختياره. وبدونه تكون القائمة الفاتحة والداكنة. يُعرض خيار النظام عندما تكون السمتان في القائمة. Theme::named(...) يبني على السمة الفاتحة، و.dark_base() يبنيها على الداكنة.
• App::default_theme هي سمة المستخدمين الذين لم يختاروا. القيمة system ما لم تُضبط.
• App::theme_picker(false) يخفي المنتقي، ويحصل الجميع على السمة الافتراضية.
• سمة واحدة تقفل التطبيق: .themes([Theme::named("acme", tokens)]) أو .theme(Theme::dark()).

تُفحص الرموز عند بدء التطبيق. يبلّغ App::check (وبالتالي router وserve) عن أسماء الرموز غير المعروفة، والقيم التي قد تخرج من تصريحها (; والأقواس المعقوفة و\ و< و> وurl()، وأسماء السمات غير الصالحة، والسمة الافتراضية غير المعروفة، وكل زوج ألوان في القسم 5 تدفعه سمة إلى ما دون WCAG 2.2 AA. لا يمكن فحص التباين إلا لقيم #rgb و#rrggbb؛ أما صيغ الألوان الأخرى فيُوثق بها.

تُقدَّم كل السمات في ورقة أنماط واحدة، /_zeyn/theme.css، تُبنى مرة واحدة عند بدء التشغيل وتُحمَّل بعد أوراق أنماط المجموعة. يُخزَّن الاختيار في ملف تعريف الارتباط zeyn_theme، وللمستخدم المسجل الدخول في تطبيق له مخزن عروض (App::datagrid_views) يُخزَّن في ذلك المخزن أيضاً، فيتبع المستخدم إلى جهاز جديد. يعرض الخادم السمة على <html>، فيكون الرسم الأول صحيحاً من البداية ولا حاجة إلى سكربت مضمن:

تغيير السمة في المنتقي يغيّر هذه الخصائص ووسم color-scheme فقط، ثم يستدعي POST /_zeyn/theme. لا يُعاد تحميل أي شيء.

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

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { --z-bg: #0e1012; }
}
:root[data-theme="dark"] { --z-bg: #0e1012; }

الكثافة

--z-density يضبط مقياس وحدة التباعد. القيمة 1 عادية و0.75 مضغوطة. <html data-density="compact"> يضبط 0.75 دون ورقة أنماط. لا تصغر عناصر التحكم وصفوف الشبكة عن 24 بكسل أبداً، فيظل الوضع المضغوط ملتزماً بحجم الهدف في WCAG 2.2.

ارتفاع صف الشبكة الافتراضية (virtual grid) يحدده الخادم (Paging::virtual_rows(px)، و32 بكسل افتراضياً) لأن بيئة التشغيل تحسب مواضع التمرير منه. الكثافة لا تغيّره.

2. الرموز الأساسية

هذه هي الرموز التي يُتوقع أن تضبطها المؤسسة.

3. الرموز المشتقة

تُحسب من الرموز الأساسية بـ color-mix() وصيغة الألوان النسبية. وتتحدث من تلقاء نفسها عندما يتغير رمز أساسي.

رموز لكل عنصر يضبطها ترميز الخادم: --z-width (عرض النافذة) و--z-flex (حصة العمود) و--z-row-height (ارتفاع صف الشبكة الافتراضية)، ولمكتبة المكونات --z-stack-gap و--z-split و--z-progress و--z-columns و--z-level و--z-pop-x / --z-pop-y (موضع النافذة المنبثقة).

ألوان سلاسل المخططات هي --z-chart-1 إلى --z-chart-6 في components.css، بقيم أفتح في السمة الداكنة. كل منها يبلغ 3:1 مقابل --z-surface. تجاوزها كأي رمز أساسي.

4. اختيار لون العلامة التجارية

• يحمل --z-brand نصاً أبيض في السمة الفاتحة (الأزرار وشريط اسم التطبيق). اختر لوناً يبلغ 4.5:1 على الأقل مقابل --z-on-brand. معظم ألوان العلامات المتوسطة إلى الداكنة تنجح. أما للون علامة فاتح مثل الأصفر، فاضبط --z-on-brand أيضاً على لون داكن.
• في السمة الداكنة تفتّح المجموعة لون العلامة للنصوص والحلقات والأزرار الأساسية، وتبقي لون العلامة الصلب لشريط اسم التطبيق. فتبدو العلامة المختلفة مقصودة في السمتين دون لون ثانٍ.
• أبقِ ألوان الحالة متمايزة عن العلامة. علامة حمراء بجوار صفوف أخطاء حمراء تجعل الأخطاء أصعب في الملاحظة؛ في هذه الحالة أزِح --z-danger نحو درجة حمراء مختلفة أو أبعد العلامة عن الشبكات بتجاوز --z-brand-subtle.
• افحص ألوانك مستعيناً بجدول القسم 5 هدفاً. أي زوج دون العتبة يفشل في WCAG 2.2 AA.

5. التباين المتحقق منه

قيس في Chromium على تطبيق المثال العامل: حُلَّ كل رمز إلى قيمة sRGB المعروضة (بما في ذلك color-mix() والألوان النسبية)، ثم حُسبت نسبة التباين وفق WCAG 2.x. العتبات: 4.5:1 للنص، و3:1 لحدود مكونات الواجهة ومؤشرات التركيز.

--z-border زخرفي (فواصل بين عناصر لها نص أصلاً) ولا يُلزَم بنسبة 3:1.

6. سلوك إتاحة آخر

• كل عنصر تفاعلي يعرض حلقة :focus-visible بسماكة 2 بكسل بلون --z-focus. ترسم صفوف الشبكة الحلقة داخل الصف حتى لا تُقصّ بحاوية التمرير.
• الأزرار وحقول الإدخال ورؤوس الفرز ومربعات المرشحات وأزرار الترقيم وزر إغلاق النافذة لا تقل عن 24 × 24 بكسل عند أي كثافة.
• prefers-reduced-motion: reduce يزيل دخول الإشعارات المتحرك وكل الانتقالات.
• في وضع forced-colors تستخدم الأيقونات CanvasText، ويستخدم الزر الأساسي والصف المركَّز Highlight، وأي حالة تعتمد على تدرجات الخلفية (عنصر القائمة الحالي وحالة الصف) تحصل على إطار أو حد بدلاً منها.