إنتقل إلى المحتوى الرئيسي

إرشادات تصميم واجهة المستخدم — إلزامي

ملزم لـ كل قطعة واجهة مستخدم جديدة أو معدلة في هذا التطبيق (صفحات Blazor والحوارات والمكونات). هذا هو مصدر الحقيقة المرجعي في CLAUDE.md. إذا كانت قاعدة ما تحول دون تقدمك، توقف واسأل — لا تنشر واجهة مستخدم تنتهك القاعدة. المستند مستوحى من plans/ui-overhaul.md.

1. بالأولويات أولاً للجوّال​

  • قم بالتأليف لهاتف ذكي بحجم 360–430px أولاً، ثم عزز نحو الأعلى باستخدام استعلامات وسائط min-width / خصائص نقاط توقف MudBlazor. لا تبدأ من سطح المكتب أولاً مع تجاوزات max-width.
  • لا توجد تمرير أفقي بأي عرض من 320–1920px. إذا كان المحتوى أعرض من المنفذ، فهذا خطأ.
  • أهداف اللمس ≥ 44px (var(--app-touch-target)). مدخلات النصوص ≥ 16px خط (توقف تكبير/تصغير التركيز على iOS).
  • احترم الشقوق: استخدم env(safe-area-inset-*); المنفذ يعين بالفعل viewport-fit=cover.
  • احترم prefers-reduced-motion — لا معلومات أساسية يتم نقلها عن طريق الحركة فقط.

2. رموز التصميم — لا توجد قيم مشفرة بشكل مباشر​

  • جميع الألوان والنصف القطر والمسافات تأتي من رموز التصميم: موضوع MudBlazor (Web/Components/Theme.cs) + خصائص CSS المخصصة الصادرة عن Web/Branding/BrandingCss.cs (var(--app-primary), --app-surface, --app-border, --app-text*, --app-radius, …).
  • لا تشفر بشكل مباشر لون سادس عشري أو نصف قطر أو سلسلة نصية للعلامة التجارية في مكون أو قاعدة CSS. اقرأ رمزاً. تتدفق الرموز من BrandingOptions الخاص بالعلامات البيضاء، لذا يجب أن تصل لوحة بائع إعادة البيع إلى واجهة المستخدم الخاصة بك بحرية.
  • قيمة جديدة تؤثر على العلامة التجارية → إضافة رمز + حقل العلامة التجارية؛ لا تضمنه.

3. التخطيط والبيانات سريعة الاستجابة​

  • الجداول تنهار لتصبح بطاقات على الهواتف. كل MudTable يعين Breakpoint="Breakpoint.Sm" وكل MudTd لها DataLabel. لا جدول عريض خام على الجوّال. (نموذج: Components/Pages/Nodes.razor.)
  • الشبكات: MudItem xs="12" sm="6" md="4" — عرض كامل على الهاتف، متعدد الأعمدة لأعلى.
  • نماذج عمود واحد على الجوّال؛ أهداف لمس كبيرة؛ inputmode/autocomplete على المدخلات؛ رقمي/عشري inputmode للنقود/النسبة المئوية.
  • التحكم الصحيح في الإدخال المنظم — لا تصندوق نص خام للأرقام أو القوائم. جمع الأرقام والنقود والنسب المئوية والتواريخ والتعدادات وأي بيانات متعددة القيم مع التحكم الصحيح (MudNumericField, MudDatePicker, MudSelect, قائمة صف قابلة للتحرير من الحقول المكتوبة، أو جدول)، كل حقل يتم التحقق منه بشكل فردي. صندوق نص MudTextField واحد مجاني يجب على المستخدم كتابة كتلة مفصولة بفاصلة/مسافة/سطر جديد — والذي تحلله بعد ذلك — محظور: إنه عرضة للأخطاء وغير مثقق والمعادي على الهاتف. لا أحد يريد كتابة كتلة. الإدخال متعدد القيم هو قائمة قابلة للتحرير من الصفوف المكتوبة (إضافة/إزالة)، أو يتم تحميله من بيانات المجال الموجودة (على سبيل المثال، قم بتشغيل الفحص مباشرة خارج اختبار خلفي مكتمل بدلاً من إعادة إدخال أرقامه). MudTextField العادي مخصص فقط للنص الحر الحقيقي — الأسماء والملاحظات والبحث والأوصاف.
  • توفير التحميل والفارغ والخطأ على كل قائمة/تفاصيل — حجمها للجوّال.
  • التنقل السفلي للجوّال (Components/Layout/BottomNav.razor) هو تنقل الهاتف الأساسي؛ الدرج المجمع هو القائمة الكاملة. أضف وجهات عالية الحركة هناك؛ احتفظ بها ≤5 عناصر.

4. الحوارات (إنشاء/تحرير)​

  • جميع إجراءات الإضافة/الإنشاء/التحرير/الجديدة تستخدم حوار MudBlazor (IDialogService.ShowAsync<TDialog>)، لا توجد نماذج صفحة مضمنة. الحوارات تعيش في Web/Components/Dialogs/، كشف [Parameter]s، أرجع سجلاً متداخلاً public sealed record …Result(...). إجراءات الصف في القائمة (البدء/الإيقاف/الحذف) تبقى مدمجة كأزرار أيقونة.
  • على الهواتف، يجب أن تكون الحوارات ملء الشاشة/ملء العرض والوعي بلوحة المفاتيح.

5. المساعدة المضمنة — كل تحكم​

  • كل خيار غير واضح أو تحديد أو تبديل أو إجراء يحصل على <HelpTip Text="…" /> (Components/HelpTip.razor) — تحوم على سطح المكتب، اضغط على الجوّال. مصدر النص من docs/ لذا يبقى الإرشاد متزامناً مع السلوك؛ حدّث كلاهما في نفس الالتزام.

6. العلامة البيضاء​

  • اسم المنتج والشعار والوصف والدعم/الشركة والألوان والرمز المفضل جميعها تأتي من BrandingOptions. قم بالإشارة إليها (IBrandingThemeProvider / IOptionsMonitor<AppOptions>)، لا تحرر حرفية "cMind" أو لون العلامة التجارية. تجميع PWA والرموز وموضوع اللون وبطل تسجيل الدخول جميعها موسومة.

7. PWA​

  • التطبيق قابل للتثبيت. احتفظ بنقطة نهاية الخريطة (/manifest.webmanifest) موسومة، والرموز موجودة (192/512/maskable + apple-touch)، عامل الخدمة محدود فقط بقوقعة التطبيق (لا يلمس Blazor circuit/_framework/hubs)، والصفحة غير المتصلة تعمل. مسار ثابت جديد → احتفظ بنطاق scope الخريطة.
  • Blazor Server يحتاج إلى دائرة SignalR مباشرة → قابل للتثبيت + محدود بقوقعة التطبيق، وليس غير متصل بالكامل. لا تعد بالتفاعل دون اتصال.

8. الوصولية​

  • التسميات على المدخلات، aria-* على التحكم المخصص، التركيز المرئي، ترتيب التركيز المنطقي. نظراً لأن الموضوع قابل للعلامات البيضاء، تحقق من التباين مقابل الموضوع النشط، لا من لوحة ثابتة.

9. E2E — لا تطبيق واجهة مستخدم بدون اختبار (حجب)​

كل تغيير واجهة مستخدم يتجه نحو تطبيق Playwright E2E في tests/E2ETests, مدفوعاً كمستخدم حقيقي، على محاكاة أجهزة الجوّال بالإضافة إلى سطح المكتب:

  • مسار جديد → أضفه إلى PageSmokeTests و MobileLayoutTests (يرسم، أسفل تنقل، لا واجهة خطأ).
  • تحويل جدول/صفحة → أضف مساره إلى مجموعة عدم التجاوز للجوّال.
  • تدفق جديد → رحلة جوّال واقعية (إنشاء/تحرير/حفظ جولة ذهاب وإياب) وممر غير سعيد (إدخال غير صالح، قائمة فارغة، رفع الإذن لكل دور).
  • تلميح مساعدة جديد → أكدها تفتح على اللمس (HelpTipTests نمط).
  • استخدم AppFixture.NewAuthedMobilePageAsync / NewAnonymousMobilePageAsync (محاكاة الجهاز).
  • dotnet test أخضر قبل "تم". WebKit المحاكاة ≠ mobile Safari — بوابة الجهاز الفعلي خطوة إصدار منفصلة.

10. تعريف الانتهاء (واجهة المستخدم)​

  • بالأولويات أولاً للجوّال؛ لا تجاوز أفقي 320–1920px؛ أهداف اللمس ≥44px.
  • فقط رموز التصميم — أصفار ألوان/نصف قطر/سلاسل نصية العلامة التجارية مشفرة بشكل مباشر.
  • الجداول → بطاقات على الهاتف (DataLabel + Breakpoint.Sm); تحميل/فارغ/حالات الخطأ موجودة.
  • الإدخال المنظم يستخدم التحكم المثقق بشكل صحيح (رقمي/تاريخ/تحديد/قائمة صفوف قابلة للتحرير) — لا صندوق نص خام يكتبه المستخدم في كتلة رقم/قيمة مفصولة.
  • إنشاء/تحرير عبر حوار؛ ملء الشاشة على الجوّال.
  • كل تحكم لديه HelpTip مصدره من الوثائق.
  • احترم العلامة البيضاء + PWA.
  • تمت إضافة E2E الجوّال + سطح المكتب (دخان، بدون تجاوز، رحلة، مسار غير سعيد)؛ dotnet test أخضر.
  • Rider get_file_problems + dotnet format analyzers نظيفة على الملفات التي تم لمسها.