زر الإجراء الرئيسي بخمسة أنماط وأربعة أحجام، مع نسخة للإجراءات الخطرة وحالة تحميل. أيقوناته الاتجاهية تنعكس في العربية وحدها.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add buttonويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/buttonالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { ArrowRightIcon } from "@phosphor-icons/react/ssr";import { Button } from "@/components/ui/button";<Button variant="outline">Cancel</Button><Button iconTrailing={ArrowRightIcon}>Continue</Button><Button danger>Delete project</Button>أمثلة
الأنماط
filled للإجراء الرئيسي، زر واحد لكل شاشة. tonal لإجراء ثانوي قوي، outline للبدائل مثل «إلغاء»، ghost للإجراءات الخفيفة، وinverted-ghost على الأسطح الملونة. danger يحوّل أي نمط إلى الأحمر.
الأحجام
lg 56 بكسل (الافتراضي)، md 48 للنماذج، sm 40 للجداول والمرشحات، xs 32 للواجهات الكثيفة. مساحة النقر تبقى 48 بكسل على الأقل في كل الأحجام.
الحالات
التمرير والضغط والتركيز تأتي من الفأرة ولوحة المفاتيح. loading يضع المؤشر مكان الأيقونة الأولى ويُبقي التركيز على الزر، وdisabled يوقفه. وعند الضغط ينخفض الزر بكسلًا واحدًا حين تسمح إعدادات الحركة. اضغط «حفظ».
الأيقونات
iconLeading وiconTrailing اختياريان. «التالي» يستخدم ArrowRightIcon في اللغتين ويُقلب في العربية ليشير إلى الأمام؛ أيقونة التنزيل لا تنعكس.
التخطيط الممتد
layout="spread" يضع النص في البداية والأيقونة اللاحقة عند حافة النهاية، بعرض لا يقل عن 216 بكسل في lg وmd. للأزرار التي تنقل إلى صفحة أو خطوة أخرى. السهم يشير إلى الوجهة (إلى اليسار في العربية) ويتقدّم نحوها عند تمرير المؤشر أو التركيز عليه؛ الأيقونات غير الاتجاهية تبقى ثابتة.
ترتيب الإجراءات
الإجراء الرئيسي عند نهاية السطر والبديل قبله. في العربية ينعكس الصف كله، فيبقى الرئيسي عند النهاية (اليسار). للإجراءات الخطرة نص محدد، لا «موافق».
رابط بشكل زر
التنقل يبقى رابطًا حتى لو بدا زرًا: مرّر render={<a href=… />} أو <Link> من Next. يأخذ شكل الزر ويبقى رابطًا لقارئات الشاشة.
مرجع الخصائص
Button
أي خاصية أخرى من Base UI Button تمر كما هي (onClick، type…).
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
variant | "filled" | "tonal" | "outline" | "ghost" | "inverted-ghost" | "filled" | خاصية Style في Figma (الاسم style محجوز في React). |
size | "lg" | "md" | "sm" | "xs" | "lg" | خاصية Size: 56 و48 و40 و32 بكسل. |
danger | boolean | false | خاصية Danger في Figma: الأحمر للإجراءات الخطرة، مع حلقة تركيز حمراء. |
children | ReactNode | لا يوجد | خاصية Label: نص الزر. |
iconLeading | IconComponent | لا يوجد | Icon leading: أيقونة Phosphor أو من Ritla UI في بداية السطر. |
iconTrailing | IconComponent | لا يوجد | Icon trailing: أيقونة في نهاية السطر. |
layout | "default" | "spread" | "default" | spread يضع النص في البداية والأيقونة اللاحقة عند حافة النهاية، ويحرّك السهم نحو الوجهة عند التمرير أو التركيز. |
loading | boolean | false | State = Loading: مؤشر مكان الأيقونة الأولى، aria-busy، الزر يبقى قابلًا للتركيز ويتجاهل الضغط. |
disabled | boolean | false | State = Disabled. |
render | ReactElement | لا يوجد | عنصر آخر بشكل الزر، عادةً رابط (<a> أو <Link>). يحتفظ بدلالته، فلا يُعلن زرًا. |
className | string | لا يوجد | أصناف إضافية تُدمج عبر cn()، مثل w-full. |
البنية
إطار محتوى داخل مساحة لمس بارتفاع 48 بكسل: أيقونة اختيارية في البداية، ثم العنوان، ثم أيقونة اختيارية في النهاية.
1. مساحة اللمس
size/touch-targetالإطار الخارجي: ارتفاعه 48 بكسل على الأقل في كل الأحجام. يضيفه
smوxsدون أن يأخذ مساحة في التخطيط.2. المحتوى
variant, dangerالتعبئة والحد يتبعان النمط؛
radius/10فيlg، وradius/8فيmd، وradius/6فيsm، وradius/4فيxs.3. الأيقونة الأولى
iconLeading24 في
lg، و20 فيmdوsmوxs. تقع في بداية السطر.4. العنوان
childrenخاصية نص العنوان:
body-16/Semibold، وbody-14/Semiboldفيxs.5. الأيقونة الأخيرة
iconTrailingبأحجام الأيقونة الأولى نفسها. تقع في نهاية السطر وتنعكس في الاتجاه من اليمين إلى اليسار.
6. مؤشر التحميل
loadingيحلّ محل الأيقونة الأولى أثناء الانتظار؛ ويبقى العنوان كي لا يتغير العرض.
7. حلقة التركيز
حلقة بعرض 2 بكسل عند
focus-visibleفقط، بعيدة عن إطار المحتوى.
إرشادات الاستخدام
الزر يبدأ إجراءً: حفظ، إرسال، إنشاء، حذف. هنا: أي نمط تختار، وكيف تكتب التسمية، وما تتحقق منه قبل التسليم.
1. اختر النمط حسب الأهمية
النمط يبيّن أهمية الإجراء لا طبيعته. تحتاج معظم الشاشات إلى زر filled واحد وبضعة أزرار أهدأ منه. وإذا علا صوت كل شيء، لم يعد شيء لافتًا.
| النمط | العدد | الاستخدام |
|---|---|---|
filled | واحد في كل شاشة | الإجراء الرئيسي في الشاشة: حفظ، إرسال، دفع، إنشاء. |
tonal | واحد أو اثنان | إجراء ثانوي مهم يبقى ظاهرًا بجوار الرئيسي. |
outline | حسب الحاجة | بدائل الإجراء الرئيسي: إلغاء، رجوع، تخطٍّ. |
ghost | حسب الحاجة | إجراءات قليلة الأهمية داخل المحتوى والبطاقات وأشرطة الأدوات. |
inverted-ghost | حسب الحاجة | إجراءات فوق أسطح العلامة أو الأسطح الداكنة: اللافتات، وأقسام الواجهة الرئيسية، والإشعار المعكوس. |
danger | واحد في نهاية المسار | الإجراءات الخطرة التي تُفقد بيانات. يعمل مع كل الأنماط، ولا يكون filled إلا في خطوة التأكيد. |
الأزرار فوق سطح العلامة
لافتة ترويجية بإجراء واحد.
inverted-ghostالنص الأبيض على تعبئة شفافة يحافظ على التباين فوق أزرق العلامة.ghost فوق العلامةالنص الرمادي على أزرق العلامة يفشل في التباين ويبدو معطّلًا.افعل
- اجعل في كل شاشة زر
filledواحدًا لإجرائها الرئيسي. - استخدم
inverted-ghostفوق أسطح العلامة والأسطح الداكنة. - حافظ على النمط نفسه للإجراء نفسه في كل المنتج.
تجنّب
- وضع زرّي
filledمتجاورين. - استخدام
ghostأوoutlineفوق سطح العلامة، فنصّهما الرمادي يختفي. - اختيار نمط للونه، فالأحمر يعني إجراءً خطرًا لا إجراءً مهمًا.
2. اكتب التسمية
التسمية تقول بالضبط ما يحدث عند الضغط على الزر. ابدأ باسم الإجراء ثم سمِّ ما يقع عليه. واكتب التسمية العربية بلغتها لا بالترجمة: المصدر القصير مثل «حفظ» أو «إرسال» يُقرأ أمرًا في الواجهات ويبقى متسقًا في كل المنتج.
سمِّ الإجراء
الإجراء الرئيسي في صفحة الفواتير.
افعل
- ابدأ باسم الإجراء ثم بما يقع عليه: «إنشاء فاتورة».
- اجعل التسمية من كلمة إلى ثلاث كلمات.
- في الإنجليزية تُكتب الحروف الكبيرة في أول الجملة فقط. والعربية بلا حروف كبيرة، فلا تعوّض ذلك بتكبير الخط.
- استخدم الفعل نفسه للإجراء نفسه في كل مكان: «حذف» لا يصبح «إزالة» في موضع آخر.
تجنّب
- كتابة «اضغط هنا» أو «موافق» أو «نعم» حين يمكن تسمية الإجراء.
- إنهاء التسمية بعلامة ترقيم أو بنقاط حذف.
- اقتطاع التسمية؛ اختصر صياغتها بدلًا من ذلك.
- الترجمة كلمة بكلمة: «Submit» تصبح «إرسال» لا «قدّم».
3. الأيقونات
الأيقونة تساعد على إيجاد الزر أسرع، لكن التسمية هي التي تحمل المعنى. استخدم أيقونة البداية لتأكيد الإجراء (علامة الجمع للإنشاء، والتنزيل للتصدير)، وسهم النهاية للتقدّم فقط. والأيقونات الاتجاهية في الأزرار العربية تأخذ نسختها المعكوسة.
الأسهم تتبع اتجاه القراءة
زر «التالي» في صفحة دفع عربية.
افعل
- أيقونة واحدة على الأكثر، في البداية أو في النهاية.
- ضع سهمًا في نهاية «التالي» و«متابعة»، وفي العربية يشير إلى اليسار.
- اختر نسخة
RTL = Yesمن الأسهم وعلامات الاتجاه في الأزرار العربية.
تجنّب
- الجمع بين أيقونة في البداية وأخرى في النهاية.
- إبقاء السهم متجهًا إلى اليمين في زر عربي.
- زر بأيقونة وحدها؛ استخدم زر الأيقونة مع تسمية بدلًا منه.
4. المقاس
المقاس lg (56) هو الافتراضي، كما في الكود، وهو مقاس الإجراء الرئيسي على الجوال وفي أقسام الواجهة الرئيسية. يناسب md (48) أزرار النماذج، وsm (40) الجداول وعوامل التصفية، وxs (32) أشرطة الأدوات المزدحمة. ويضيف sm وxs في الكود مساحة لمس غير مرئية بارتفاع 48 بكسل، فاترك لهما متّسعًا.
مقاس واحد في المجموعة
أزرار نموذج.
افعل
- مقاس واحد لكل أزرار المجموعة.
- اترك
space-8على الأقل بين أزرارsmوxsحتى لا تتداخل مساحات اللمس. - اجعل الإجراء الرئيسي بعرض الشاشة في أسفل شاشات الجوال.
تجنّب
- خلط المقاسات في مجموعة واحدة.
- جعل
xsالإجراء الوحيد على شاشة لمس. - تثبيت ارتفاع الزر، فالتسميات العربية تحتاج أسطرًا أعلى.
5. الترتيب والموضع
في المجموعة يقع الإجراء الرئيسي في نهاية السطر: على اليمين في الإنجليزية وعلى اليسار في العربية، ويسبقه البديل. الترتيب ينعكس مع التخطيط، فالشاشات العربية تحتاج أزرارًا عربية في صف من اليمين إلى اليسار، لا الصف الإنجليزي بتسميات عربية.
الإجراء الرئيسي في نهاية السطر
تذييل نافذة حوار بالعربية.
افعل
- ضع الإجراء الرئيسي في نهاية السطر في النوافذ والنماذج والتذييلات.
- حاذِ المجموعة إلى نهاية حاويتها.
- على الشاشات الضيقة رتّب الأزرار بعضها فوق بعض بعرض كامل، والرئيسي في الأعلى.
تجنّب
- إبقاء الترتيب الإنجليزي في الشاشات العربية.
- وضع الإجراء الرئيسي بين إجراءين ثانويين.
- تفريق أزرار تنتمي إلى مجموعة واحدة.
6. التحميل والتعطيل
التحميل والتعطيل هما الحالتان اللتان تضبطهما بنفسك، أما التمرير والضغط والتركيز فتأتي من التفاعل. أثناء التحميل حوّل التسمية إلى صيغة «جارٍ …» («حفظ» إلى «جارٍ الحفظ»)، ويأخذ مؤشر التحميل مكان أيقونة البداية.
أظهر التقدّم في التسمية
حفظ نموذج.
افعل
- انتقل إلى حالة التحميل فور بدء الإجراء، وعُد منها عند انتهائه.
- حوّل التسمية إلى صيغة «جارٍ …» أثناء التحميل: «حفظ» إلى «جارٍ الحفظ».
- اشرح بجوار الزر المعطّل سبب تعطيله، أو اتركه مفعّلًا وأظهر الخطأ عند الضغط.
تجنّب
- استبدال التسمية بعبارة عامة مثل «جارٍ التحميل…».
- تعطيل زر دون قول ما الذي ينقص.
- التعطيل لإجراء لا يستطيعه المستخدم أبدًا؛ أخفِه بدلًا من ذلك.
7. الإجراءات الخطرة
تفعيل danger يحوّل أي نمط إلى الألوان الحمراء. استخدمه فقط حين يحذف الإجراء شيئًا أو يُفقده، وأكّد كل ما لا يمكن التراجع عنه في نافذة حوار يكرّر زرها filled مع danger الإجراءَ نفسه بالضبط.
outline أو ghost مع danger في الصفحة، وfilled مع danger في التأكيد فقط.افعل
- سمِّ ما سيُفقد: «حذف المشروع».
- استخدم
outlineأوghostمعdangerفي الصفحة، وfilledمعdangerفي التأكيد فقط. - إن أمكن التراجع عن الإجراء، فاعرض «تراجع» بدل طلب التأكيد.
تجنّب
- الأحمر لإجراءات غير خطرة مثل تسجيل الخروج أو الإلغاء.
- تسمية إجراء خطِر «موافق» أو «نعم».
- جعل الإجراء الخطِر الزرَّ الذي يأخذ التركيز تلقائيًا.
8. الأزرار والروابط
الزر ينفّذ شيئًا، والرابط ينقلك إلى مكان. وحين يحتاج رابط إلى شكل الزر (مثل «ابدأ الآن» في صفحة تعريفية)، أبقِه رابطًا في الكود عبر render={<a href>}، كي تعلنه قارئات الشاشة رابطًا ويمكن فتحه في علامة تبويب جديدة.
افعل
- استخدم
Buttonللإجراءات في الصفحة الحالية. - استخدم رابطًا بشكل الزر للانتقال إلى صفحة أخرى.
- استخدم مكوّن الرابط داخل النص.
تجنّب
- التنقل بين الصفحات بزر
Buttonدون دلالة الرابط. - إعطاء رابط داخل فقرة شكل زر
filled.
قبل التسليم
- زر
filledواحد في كل شاشة، في نهاية مجموعته. - كل تسمية تبدأ باسم الإجراء وتسمّي ما يقع عليه.
- الشاشات العربية تستخدم النسخ العربية بأسهمها المعكوسة.
- الإجراءات الخطرة تستخدم
dangerوتسمية محددة. - حالات التحميل والتعطيل والخطأ مصمّمة، لا الحالة الافتراضية وحدها.
- الروابط التي تشبه الأزرار معلَّمة روابطَ لفريق التطوير.
رموز التصميم والمواصفات
كل قيمة في الزر متغيّر أو نمط نص. هذه هي القيم المربوطة بالمكوّن، حسب المقاس وحسب النمط.
المقاسات
الارتفاع الظاهر، والحشوة على امتداد السطر، والمسافة بين العناصر، ونصف قطر الزوايا لإطار المحتوى. وكل مقاس داخل مساحة لمس size/touch-target (48).
| المقاس | الارتفاع والحشوة والمسافة ونصف القطر | التسمية والأيقونات |
|---|---|---|
lg | 56 · space-24 · space-8 · radius/10 | body-16/Semibold · 24 |
md | 48 · space-24 · space-8 · radius/8 | body-16/Semibold · 20 |
sm | 40 · space-16 · space-8 · radius/6 | body-16/Semibold · 20 |
xs | 32 · space-12 · space-8 · radius/4 | body-14/Semibold · 20 |
الألوان
لون التعبئة والحدّ والتسمية لكل نمط في الحالة الافتراضية. ويأتي الوضعان الفاتح والداكن من وضع 1. Colors، لا من نسخ منفصلة.
| النمط | التعبئة والحدّ | التسمية |
|---|---|---|
filled | background/brand/solid | text/brand/on-brand |
filled · danger | background/danger/solid | text/static/white |
tonal | background/brand/faint | text/brand/subtle |
tonal · danger | background/danger/faint | text/danger/subtle |
outline | background/surface/lowest · border/gray/soft | text/gray/subtle |
outline · danger | background/surface/lowest · border/danger/soft | text/danger/subtle |
ghost | alpha/tint-12 | text/gray/subtle |
ghost · danger | alpha/tint-12 | text/danger/subtle |
inverted-ghost | alpha/tint-12 | text/static/white |
التركيز
في حالة التركيز يُرسم نمط التأثير Focus/focus-ring (effects/focus/main) بسماكة border-width/thicker، وتصبح الحلقة حمراء مع danger. وفي الكود يحدث ذلك تلقائيًا مع :focus-visible.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | ينقل التركيز إلى الزر، وتظهر حلقة التركيز (حمراء مع danger). |
| EnterSpace | ينفّذ الإجراء. أثناء التحميل يبقى التركيز ولا يتكرر الإجراء. |
ARIA
- عنصر
<button>أصلي (أو<a>معrender)، فلا حاجة لـrole. - التحميل يضبط
aria-busy="true"وaria-disabled="true"بدلdisabled، فلا يضيع التركيز ويعلن قارئ الشاشة الحالة. غيّر النص أيضًا («جارٍ الحفظ»). - الأيقونات زخرفية؛ النص هو الاسم. الأزرار التي لا تحوي إلا أيقونة تأتي في زر الأيقونة.
- مساحة النقر 48 بكسل على الأقل حتى في
smوxs(WCAG 2.5.8).
افعل
- ينقل
Tabالتركيز، ويضغطEnterوSpaceالزر. وتظهر عند التركيز حلقة ريتلا بلون العلامة، أو بالأحمر معdanger. - حافظ على مساحة لمس بارتفاع 48 بكسل، ويحصل عليها
smوxsمن مساحة غير مرئية. - أعطِ الإجراءات ذات الأيقونة وحدها تسمية عبر زر الأيقونة.
- علّم الأزرار أثناء التحميل بأنها مشغولة (
aria-busy)، والكود يفعل ذلك عنك.
تجنّب
- إزالة حلقة التركيز أو تغيير شكلها.
- الاعتماد على اللون وحده لتمييز الإجراء الرئيسي، فالنمط والموضع يحملانه أيضًا.
- وضع زرين أقرب من
space-8على شاشات اللمس.
ملاحظات العربية والاتجاه
ينعكس
- الأيقونة الأولى في بداية السطر (اليمين في العربية) والأخيرة في نهايته، دون أي خاصية RTL.
- الأسهم والأسهم المثلثة تنعكس عبر
<Icon>: «التالي» يشير إلى اليسار في العربية. - ترتيب الإجراءات ينعكس: الرئيسي عند نهاية السطر في الاتجاهين.
لا ينعكس
- مؤشر التحميل يدور في اتجاه عقارب الساعة في اللغتين.
- علامات الصح والتنزيل والشعارات داخل الأزرار لا تنعكس.
- الأرقام
- الأرقام داخل النص («حذف 3 ملفات») تتبع إعداد الأرقام عبر
formatNumber، لا الزر. - الخط العربي
- النص بنمط
body-16(وbody-14فيxs) بوزن Semibold؛ ارتفاع الزر ثابت، ونص العربية يتسع فيه دون قص. - النص ثنائي الاتجاه
- اسم لاتيني داخل نص عربي («تسجيل الدخول باستخدام Google») يوضع في
<bdi>كي لا تنتقل علامات الترقيم.
افعل
- استخدم النسخة العربية لكل زر عربي، حتى دون أيقونات.
- بدّل الأيقونات الاتجاهية إلى نسختها
RTL = Yes. - اترك متّسعًا للتسميات العربية، فهي غالبًا أطول من الإنجليزية.
- اكتب الأرقام في التسميات حسب إعداد الأرقام: «٣ عناصر» أو «3 عناصر».
تجنّب
- كتابة العربية في النسخة الإنجليزية، فهي تُبقي خط Geist وارتفاعات الأسطر الإنجليزية.
- عكس مؤشر التحميل أو علامات الصح أو الشعارات.
- اختصار التسمية العربية لتناسب عرضًا ثابتًا.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.