البطاقات والمواد السطحية
قواعد استخدام بطاقات المحتوى، وأصداف مساحة العمل، والطبقات العائمة، والظلال، والتعتيم الخلفي.
تبقى بطاقات المحتوى مسطحة؛ أما الغلاف الخارجي فينقل تجميع المساحة في العمل.
بطاقة محتوى قياسية لا تستخدم ظلًا خارجيًا.
يتم نقل اختيار الحالة من خلال اللون وهياكل المعلومات.
معايير مواد البطاقات والطبقات
توضح هذه الوثيقة علنًا متى تستخدم واجهة Qokit الظلال والشفافية والتدرجات والتعتيم الخلفي. ينطبق ذلك على توسيعات المنصة وBuilder وCMS وDashboard وStudio وAdmin. يمكن أن تكون صفحات التسويق والمواقع المُنشأة أكثر تعبيرًا، لكن يجب أن تنتمي التأثيرات إلى السمة الحالية مع ضمان قابلية قراءة المحتوى.
المبادئ الأساسية
تُستخدم التأثيرات البصرية للتعبير عن الهيكل، وليس لتزيين كل كتلة:
- يتم تمييز المحتوى من خلال اختلاف لون الخلفية.
- تعبّر الحاويات عن الانتماء من خلال الشفافية أو التدرجات المتحفظة.
- تعبّر الطبقات العائمة عن التسلسل الهرمي من خلال الظلال.
- تعبّر التفاعلات عن الحالة من خلال اللون وحلقات التركيز.
تستخدم البطاقات المستقلة ذات الألوان الصلبة ومربعات الإدخال ظلًا خفيفًا مشتركًا من المستوى الأول؛ تظل القوائم والأسطح المتداخلة والمجموعات الشفافة مسطحة؛ فقط الطبقات العائمة الحقيقية تستخدم ظلالًا واضحة.
ترتيب التحديد
قبل إضافة تأثيرات المواد، حدد دور السطح:
- هل هو بطاقة مستقلة بلون صلب أو مربع إدخال؟ استخدم ظل السطح المشترك من المستوى الأول أو ظل الحقل.
- هل هو صف قائمة أو بطاقة متداخلة أو خيار مكرر أو مجموعة شفافة؟ حافظ على السطح مسطحًا.
- هل تنظم عدة بطاقات محتوى داخلية في مساحة عمل واحدة؟ استخدم Shell.
- هل يغطي محتوى الصفحة أو يظهر فوق المستوى الحالي؟ استخدم ظل الطبقة العائمة.
- هل هو في حالة سحب أو تكبير أو تعليق مؤقت؟ استخدم ظلًا مؤقتًا.
- هل الهدف فقط التعبير عن التمرير أو التحديد أو التركيز؟ استخدم دور التمرير المشترك ولون خلفية التفاعل وحلقة التركيز.
لا تجمع بين الظلال والشفافية والتدرجات والتعتيم الخلفي إلا إذا كان دور السطح يتطلب ذلك حقًا.
مصفوفة السيناريوهات
| دور السطح | الظل | الشفافية أو التدرج | التعتيم الخلفي |
|---|---|---|---|
| بطاقات محتوى مستقلة بلون صلب، بطاقات مؤشرات | ظل خفيف مشترك من المستوى الأول | يُسمح باختلاف طفيف في لون الخلفية | لا |
| صفوف القوائم، البطاقات المتداخلة، المجموعات الشفافة، الخيارات المكررة | لا | يُسمح باختلاف طفيف في لون الخلفية | لا |
| Shell تجميع داخل الصفحة | لا | مُوصى به | عادةً غير مطلوب |
| الشريط الجانبي أو Shell مساحة العمل الدائمة | خفيف | مُوصى به | يُسمح به عند وجود محتوى مرئي خلفه |
| Dialog وPopover وDropdown وقوائم السياق | ظل طبقة عائمة واضح | يجب أن تكون الخلفية صلبة بما يكفي لضمان القراءة | يُسمح به |
| معاينة السحب، حالة التكبير، معاينة التعليق | مؤقت أقوى | اختياري | عادةً غير مطلوب |
| التمرير (Hover) | الحفاظ على ظل المستوى الأول أو تعزيزه طفيفًا | يمكن تغيير الخلفية | لا تغيير |
| حالة التحديد أو التفعيل | لا | خلفية بلون مميز أو تدرج متحفظ | لا تغيير |
| مربعات الإدخال، مربعات البحث | ظل حقل خفيف جدًا | استخدام لون سطح عنصر التحكم | عادةً غير مطلوب |
| إجراء أساسي مستقل، كبسولة مستقلة، غلاف عناصر التحكم المقسمة | ظل عنصر تحكم خفيف جدًا | استخدام لون سطح عنصر التحكم | عادةً غير مطلوب |
| شريط الأدوات وعناصر التحكم الداخلية الشفافة | لا | استخدام لون سطح عنصر التحكم أو الشفافية | عادةً غير مطلوب |
| بطاقات بصرية لصفحات التسويق أو المواقع المُنشأة | تحددها السمة | يُسمح به | استخدام متحفظ |
تعيين المكونات
<Card>يستخدم افتراضيًاlayer="content": ظل خفيف مشترك من المستوى الأول، بلا حدود، زوايا مستديرة افتراضية20px؛ تظل المتغيرات الصامتة والمتداخلة والقوائم والشفافة مسطحة.<Card layer="shell">: مسؤول فقط عن التجميع داخل الصفحة، يستخدم سطحًا شفافًا أو بتدرج خفيف ويبقى مسطحًا؛ يوفر Shell مساحة العمل الدائمة التسلسل الهرمي الخاص به حسب النمط.<Card shape="pill">: للبطاقات المدمجة في صف واحد، بزوايا مستديرة بشكل كبسولة بيضاوية.SidebarNavigation: Shell مساحة عمل مستقل، يحتفظ بتدرج واضح وشفافية وتعتيم خفيف وظل خفيف.PromptPanelفي Studio عند استخدامه كحاوية مساحة عمل: استخدم--workspace-shell-shadow.DialogPanelوقوائم Dropdown وPopover وقوائم السياق ومتصفح المفاهيم: استخدم ظل الطبقة العائمة.- لوحة Builder، ومعاينة الأجهزة، ومعاينة المواقع المُنشأة، ومعاينة السحب، وحالة التكبير: نظرًا لأنها تمثل مستويات معاينة مستقلة أو طبقات تفاعل مؤقتة، يمكنها الاحتفاظ بظلال مخصصة.
لا تنشئ بطاقات محتوى عائمة بشكل متتالي. إذا كنت بحاجة حقًا إلى تجميع خارجي، فيجب أن يكون Shell مسطحًا. باستثناء الطبقات العائمة الحقيقية، لا يظهر أكثر من ظل واحد عادي للمحتوى أو عنصر التحكم في نفس سلسلة أسلاف DOM.
استخدام متغيرات التصميم (Token)
استخدم Token المشترك أولًا، ولا ترمز التأثيرات بشكل ثابت:
- ظل بطاقة المحتوى:
--card-shadow: var(--qk-shadow-surface) - ظل التمرير لبطاقة المحتوى:
--card-shadow-hover: var(--qk-shadow-surface-hover) - ظل الحقل:
--input-shadow: var(--qk-shadow-field) - ظل الحقل عند التفعيل:
--input-state-shadow: var(--qk-shadow-field-active) - ظل عنصر التحكم:
--qk-shadow-control/--qk-shadow-control-hover - ظل عنصر التحكم للإجراء الأساسي:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - تعتيم بطاقة المحتوى:
--card-backdrop-filter: none - سطح Shell:
--card-shell-surface - تعتيم Shell:
--card-shell-backdrop-filter - ظل Shell مساحة العمل:
--workspace-shell-shadow - سطح Dialog:
--dialog-surface، يوفر تدرج سمة متحفظًا - تعتيم Dialog:
--dialog-backdrop-filter - ظل الطبقة العائمة لـ Dialog:
--dialog-shadow - زوايا Dialog المستديرة: إعادة استخدام
--card-radius - تركيز لوحة المفاتيح:
--focus-ring - ظل الطبقة العائمة: استخدم Token الطبقة العائمة الحالي لـ Dialog أو Dropdown أو Menu أو مستوى الصفحة
لا يجوز لبطاقات المحتوى العادية ولوحات مساحة العمل استخدام Token --shadow العام الأقوى.
تتبع الظلال العامة مقياسًا هادئًا بـ "إزاحة قصيرة، شفافية منخفضة، تزايد حسب مستوى الطبقة". لا يجوز لبطاقات Card العادية والحقول وعناصر التحكم تعميق أو تكبير الظل المشترك في المسار؛ يعبر Popover وDialog عن الانفصال عن الصفحة من خلال إزاحة أكبر ونطاق ضبابية أكبر، وليس عن طريق تكديس ضباب رمادي داكن.
قواعد التفاعل
التمرير (Hover)
- لا يجوز لبطاقات المحتوى الارتفاع إلى مستوى أعلى من
--qk-shadow-surface-hover. - لا ترفع بطاقات المحتوى من خلال
translateY. - استخدم تغييرًا طفيفًا في الخلفية أو ردود فعل واضحة لعنصر التحكم.
- لا تغير الشكل، لتجنب عدم تناسق الزوايا المستديرة أو قص الظل.
التحديد والتفعيل
- استخدم سطحًا بلون مميز أو حالة أيقونة أو حالة دلالية أو تدرجًا متحفظًا.
- لا تعبّر عن الحالة من خلال الظل فقط.
تركيز لوحة المفاتيح
- استخدم قاعدة focus-visible المشتركة أو
--focus-ring. - لا يمكن لظل البطاقة العام أن يحل محل تلميح التركيز.
- يجب أن يكون مرئيًا بوضوح في السمات الفاتحة والداكنة.
السحب والتكبير
- يُسمح باستخدام ظل أقوى فقط عندما تتحرك الطبقة أو يتم تغيير حجمها.
- يجب إزالة الظل المؤقت بعد انتهاء التفاعل.
- لا يجوز للحاويات التي بها تجاوز قص تأثيرات ردود فعل الطبقات المتحركة.
الشفافية والتعتيم الخلفي
تُستخدم الشفافية للتعبير عن انتماء السطح الخارجي إلى مساحة العمل. لا يكون للتعتيم الخلفي معنى إلا عندما يكون هناك محتوى أو لون أو صورة مرئية فعليًا خلف السطح.
- لا تستخدم التعتيم الخلفي على خلفيات ذات لون صلب، فهو يزيد تكلفة العرض فقط ولا يعبر عن التسلسل الهرمي.
- يجب أن تكون النصوص والأيقونات وعناصر التحكم قابلة للقراءة بوضوح بغض النظر عن الخلفية التي تمر من خلفها.
- عندما لا يدعم المتصفح التعتيم الخلفي، يجب أن تكون هناك خلفية بديلة غير شفافة أو قابلة للقراءة.
- يجب أن يكون شدة الضباب متحفظة في واجهات العمل الكثيفة.
- يجب التحقق من السمات الفاتحة والداكنة معًا.
الاستثناءات المسموح بها للاحتفاظ بالظلال
- Shell الشريط الجانبي لمساحة العمل
- Dialog وPopover وDropdown والقوائم واللوحات النمطية
- متصفح المفاهيم في Studio وطبقات التأكيد العائمة
- لوحة Builder وإطارات الأجهزة ومستويات معاينة المواقع المُنشأة
- معاينة السحب وردود فعل التكبير وأدوات التعليق المؤقتة
- أزرار الإجراءات الأساسية التي حدد Token الزر المشترك ظلًا لها
- عناصر بصرية لصفحات التسويق والمواقع المُنشأة التي تتحكم بها السمة الحالية
لا يمكن لهذه الاستثناءات أن تؤثر على بطاقات المحتوى العادية من خلال محددات واسعة أو Token مشترك.
قائمة المراجعة
- تستخدم بطاقات المحتوى المستقلة ذات الألوان الصلبة ومربعات الإدخال فقط دور الظل الخفيف المشترك من المستوى الأول.
- تستخدم الإجراءات الأساسية المستقلة والكبسولات المستقلة وأغلفة عناصر التحكم المقسمة فقط ظل عنصر التحكم الخفيف جدًا المشترك.
- تظل تجميعات الصفحة وصفوف القوائم والبطاقات المتداخلة والمجموعات الشفافة وعلامات Tab/Pill المكررة وأشرطة الأدوات والعناصر الداخلية لعناصر التحكم المركبة مسطحة.
- تظل عمليات البحث والتصفية والفرز والعرض والإجراءات الأساسية المضمنة في شريط الأدوات مسطحة؛ لا يجوز لظل مربعات الإدخال العادية التسرب إلى شريط الأدوات، باستثناء حلقة تركيز لوحة المفاتيح.
- عندما يكون Segmented داخل بطاقة أو مربع حوار أو شريط أدوات به ظل بالفعل، يظل الغلاف والعنصر المحدد مسطحين؛ لا تظهر حلقة تركيز لوحة المفاتيح عند النقر بالماوس.
- باستثناء الطبقات العائمة الحقيقية، لا يتم تكديس ظلال عادية متعددة في نفس سلسلة الأسلاف.
- لا يتسبب التمرير في تحرك بطاقات المحتوى عموديًا.
- تمت إزالة بطاقات المحتوى المتداخلة، أو تم تعريف الغلاف الخارجي بوضوح كـ Shell.
- فقط Shell الحقيقي يستخدم
--workspace-shell-shadow. - فقط الطبقات العائمة الحقيقية وطبقات التفاعل المؤقتة تستخدم ظلالًا أقوى.
- يوجد محتوى مرئي خلف التعتيم الخلفي، وهناك خلفية بديلة قابلة للقراءة.
- يستخدم focus-visible حلقة تركيز.
- تحافظ السمات الفاتحة والداكنة على تباين كافٍ.
- لا تقص الأسطح ذات الزوايا المستديرة ردود فعل التمرير أو التركيز أو السحب أو الطبقات العائمة.
- لا تظهر تجاوزات أفقية جديدة في عرضي سطح المكتب والجوال.
- اجتاز فحص
npm run ui:check-card-surfaces --workspace @qokit-ai/web.