تأتي أيقونات SDAIA UI من مصدر واحد هو مجموعة أيقونات DGA (@platformscode/icons)، وتُعرض بمكوّن واحد هو DgaIcon. استخدام المجموعة نفسها ورموز الأحجام نفسها في كل مكان يحافظ على اتساق الشاشات باللغتين وفي السمتين الفاتحة والداكنة.
مجموعة أيقونات DGA
تضم الحزمة @platformscode/icons نحو 4,400 أيقونة، ولكل أيقونة نمطان: …Stroke (خطّي) و…Solid (مصمت). يثبّت الأمر init الحزمة تلقائيًا.
- استخدم النمط الخطّي (Stroke) افتراضيًا: في التنقّل والإجراءات وحقول النماذج ورسائل الحالة.
- استخدم النمط المصمت (Solid) فقط حين يتطلّب التصميم شكلًا ممتلئًا، مثل زرّي التشغيل والإيقاف المؤقت، أو حالة التحديد، أو المجلد الممتلئ.
- لا تخلط النمطين لأداء الغرض نفسه في شاشة واحدة.
- ابحث في المجموعة قبل طلب أيقونة جديدة. تتبع الأسماء نمطًا مثل
search01StrokeوarrowLeft01Strokeوcalendar03StrokeوplaySolid.
استخدام DgaIcon
أضف المكوّن بأداة سطر الأوامر، ثم استورد بيانات الأيقونات التي تحتاجها. استورد كل أيقونة باسمها حتى لا يدخل في الحزمة النهائية إلا ما تستخدمه.
npx sdaia-ui@latest add dga-icon
import { DgaIcon } from '@/components/ui/DgaIcon'; import { search01Stroke } from '@platformscode/icons'; export function SearchGlyph() { return ( <span className="size-icon-lg text-icon-default"> <DgaIcon data={search01Stroke} /> </span> ); }
يملأ DgaIcon العنصر الذي يحتويه، فيُعرض بعرض العنصر الأب وارتفاعه كاملين. حدّد حجم الأيقونة بوضع صنف size-icon-* على العنصر الأب. تأخذ الأيقونة لونها من لون نص العنصر الأب، فتعمل أصناف text-* والسمة الداكنة دون خصائص إضافية.
أحجام الأيقونات
أحجام الأيقونات رموز تصميم ثابتة، فهي نفسها على الحاسوب والجهاز اللوحي والهاتف. وحدها المسافات وأحجام الخطوط تتغير بين أحجام الشاشات.
| الصنف | الحجم |
|---|---|
| size-icon-xs | 12px |
| size-icon-sm | 16px |
| size-icon-lg | 20px |
| size-icon-xl | 24px |
| size-icon-2xl | 32px |
| size-icon-3xl | 40px |
لا يوجد حجم md للأيقونات. الصنف size-icon-md لا أثر له، فتتمدد الأيقونة لتملأ العنصر الذي يحتويها. استخدم size-icon-sm (16px) أو size-icon-lg (20px). لا يملك DgaIcon خاصية size، ولا تضع عرضًا أو ارتفاعًا على عنصر svg.
- 16px (
sm) بجانب النص الأساسي، وداخل الحقول والشرائح والأزرار الصغيرة. - 20px (
lg) في الأزرار المتوسطة والكبيرة والقوائم والتنبيهات. - 24px (
xl) في التنقّل وأزرار الأيقونات المستقلة. - 32px و40px (
2xlو3xl) في الحالات الفارغة والأيقونات البارزة والرسوم التوضيحية.
الأيقونات في الواجهات من اليمين إلى اليسار
الأيقونات التي تدل على اتجاه يجب أن تنعكس في الواجهة العربية. أضف الخاصية flipOnRtl لتنعكس الأيقونة حين تحمل الصفحة أو أحد العناصر الأب dir="rtl".
import { DgaIcon } from '@/components/ui/DgaIcon'; import { arrowRight01Stroke } from '@platformscode/icons'; // تشير إلى اليمين في الإنجليزية وإلى اليسار في العربية. <span className="size-icon-sm"> <DgaIcon data={arrowRight01Stroke} flipOnRtl /> </span>
| تُعكس في RTL | لا تُعكس |
|---|---|
| أسهم الرجوع والتقدّم، وأسهم الشيفرون والأسهم الصغيرة | التشغيل والإيقاف المؤقت والتقديم السريع وسائر أزرار الوسائط |
| الصفحة السابقة والتالية | البحث والإعدادات والمستخدم والصفحة الرئيسية |
| الأيقونات التي تدل على اتجاه النص (المسافة البادئة، تعداد القوائم) | علامة الصح والزائد والناقص والإغلاق |
| الإرسال والرد، حين يُظهر التصميم اتجاهًا | الشعارات والأعلام وعلامات الهوية |
يعكس DgaIconByName الأسماء الاتجاهية تلقائيًا (أسهم اليمين واليسار بأنواعها، والتقدّم، والرجوع، والتالي، والسابق). لكنه يحمّل مجموعة الأيقونات كاملة، فلا تستخدمه إلا حين يأتي اسم الأيقونة من البيانات أثناء التشغيل.
الأيقونات الخاصة وعلامات الهوية
بعض الرسوم ليست أيقونات عامة: شعارا سدايا وDGA، وعلم المملكة، ومؤشرات التلميحات، ورسوم مقتطفات الشيفرة ورفع الملفات، ووجوه التقييم وأيقونات الإعجاب، وأيقونات التشغيل في بطاقات الوسائط. هذه الرسوم موجودة في sdaia-assets على شكل مكوّنات React، وتنسخها أداة سطر الأوامر إلى components/ui/sdaia-assets/ حين تضيف مكوّنًا يستخدمها.
- لا ترسم علامة هوية بأيقونة عامة، ولا تغيّر لون شعار أو أبعاده.
- لا تلصق شيفرة
<svg>مباشرة داخل مكوّن. استخدمDgaIconمع أيقونة من المجموعة، أو مكوّنًا مسمّى منsdaia-assets. - إن لم تجد الأيقونة التي تحتاجها في مجموعة DGA، فاطلب من فريق التصميم إضافتها أصلًا خاصًا.
أيقونات قابلة للوصول
حين لا تحمل DgaIcon عنوانًا (title) فهي زخرفية: تُعرض مع aria-hidden="true" ويتجاوزها قارئ الشاشة. وهذا هو الصواب حين يشرح نص ظاهر بجانبها معناها.
// زخرفية: بجانب نص ظاهر، ومخفية عن قارئ الشاشة (الوضع الافتراضي). <Button leadingIcon={<DgaIcon data={delete02Stroke} />}>حذف</Button> // لها معنى بمفردها: أعطِ الأيقونة عنوانًا. <span className="size-icon-sm"> <DgaIcon data={alertCircleStroke} title="خطأ" /> </span> // زر بأيقونة فقط: سمِّ الزر، لا الأيقونة. <Button iconOnly aria-label="إغلاق" leadingIcon={<DgaIcon data={cancel01Stroke} />} />
- أعطِ الأيقونة عنوانًا فقط حين تحمل معنى غير مكتوب في مكان آخر، مثل أيقونة حالة في خلية جدول. تحصل الأيقونة عندها على
role="img"ويصبح العنوان اسمها. - الزر الذي يحتوي أيقونة فقط يحتاج إلى
aria-labelعلى الزر نفسه. لا تضع عنوانًا على الأيقونة أيضًا حتى لا يُقرأ الاسم مرتين. - لا تعتمد على اللون وحده لإيصال المعنى. أرفق لون الحالة بأيقونة أو كلمة.
- يجب ألا تقل نسبة التباين بين الأيقونة وخلفيتها عن 3:1 في السمتين الفاتحة والداكنة.
- اجعل مساحة اللمس 24 × 24px على الأقل حتى لو كانت الأيقونة 16px. استخدم أحجام مكوّن الزر بدل أيقونة مجردة.
قائمة التحقق
الأيقونة من @platformscode/icons أو من sdaia-assets، لا شيفرة SVG مضمّنة.
النمط الخطّي افتراضيًا، والمصمت فقط حيث يكون التصميم ممتلئًا.
الحجم بصنف size-icon-* على العنصر الأب (لا يوجد md).
الأيقونات الاتجاهية تستخدم flipOnRtl وتمت مراجعتها في العربية.
الأيقونات الزخرفية مخفية، والأيقونات ذات المعنى وأزرار الأيقونات لها اسم.
تمت المراجعة في السمتين الفاتحة والداكنة.