الرسوم البيانية
كل رسوم Ritla البيانية، من الأعمدة والخطوط إلى الخرائط الحرارية والشموع ورسوم البطاقات، تتجه من اليمين في العربية وتُقرأ بلوحة المفاتيح.
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add chartويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/chartأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { BarChart, ChartCard, ChartLegend } from "@/components/ui/chart";<ChartCard title="Income and spend" subtitle="SAR" legend={<ChartLegend items={series} />}> <BarChart label="Income and spend by month" data={data} series={series} /></ChartCard>أمثلة
خط
خط ناعم بمساحة خفيفة، والعام الماضي خط رمادي متقطع، والمتوسط دليل متقطع.
خط في بطاقة مع نطاق
المحور في جهة النهاية يبدأ من 30K، ونطاق مظلل بتغيّره. مرّر المؤشر أو استخدم الأسهم لرؤية خط التقاطع.
أعمدة البطاقات
إبراز شهر، وتوقّع بأعمدة مظللة، وتدفق داخل وخارج حول الصفر.
رسوم دائرية
عدّاد وأقواس مقسّمة وحلقات وحلقة تقدّم، تمتلئ عكس عقارب الساعة في العربية.
خرائط البطاقات الحرارية
النشاط بالساعة واليوم، والاحتفاظ حسب أسبوع البدء، وشريط يومي.
مرجع الخصائص
ChartCard
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
title / subtitle | ReactNode | لا يوجد | العنوان والوحدة والفترة. |
legend | ReactNode | لا يوجد | ChartLegend تحت الرسم. |
BarChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
data | ChartDatum[] | لا يوجد | صف لكل فئة: label وقيمة لكل سلسلة. |
series | ChartSeries[] | لا يوجد | key وlabel بترتيب ألوان الرسم. |
stacked | boolean | false | أعمدة مكدّسة بدل المتجاورة. |
layout | "vertical" | "horizontal" | "vertical" | الأفقي للترتيب. |
series[].from | string | لا يوجد | مفتاح الطرف الأدنى: أعمدة عائمة. |
histogram | boolean | false | أعمدة تملأ فئاتها بفاصل 2px. |
line | ChartSeries | لا يوجد | مقياس ثانٍ خطًا بنقاط فوق الأعمدة. |
max / valueFormat | number / (n) => string | لا يوجد | أعلى المحور وتنسيق قيمه. |
label | string | لا يوجد | اسم جدول البيانات المخفي. |
LineChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
area | boolean | false | مساحة خفيفة تحت الخط. |
stacked | boolean | false | طبقات مكدّسة ممتلئة. |
curve | "smooth" | "linear" | "step" | "smooth" | منحنٍ أو مستقيم أو درجات. |
average | { value, label } | لا يوجد | خط المتوسط ووسمه. |
range | { from, to, label, tone } | لا يوجد | نطاق مظلل بين فهرسين ووسم بتغيّره. |
axis / min | "start" | "end" / number | "start" / 0 | جهة محور القيم وأدنى قيمة عليه. |
series[].comparison | boolean | لا يوجد | خط رمادي متقطع للفترة السابقة. |
ScatterChart / BubbleChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
series | { label, points: { x, y }[] }[] | لا يوجد | التبعثر: نقاط كل سلسلة. |
xLabel / yLabel | string | لا يوجد | ما يمثّله كل محور. |
data | { label, value, size, series }[] | لا يوجد | الفقاعات: الارتفاع والمساحة والسلسلة. |
BoxPlot / LollipopChart / BulletChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
data / names (BoxPlot) | { label, min, q1, median, q3, max }[] / Record | لا يوجد | الإحصاءات الخمسة لكل فئة، وأسماؤها للتلميح والجدول. |
data (Lollipop) | { label, value }[] | لا يوجد | مرتبة، الأكبر أولًا. |
data (Bullet) | { label, value, target, bands? }[] | لا يوجد | الفعلي والهدف وحدّا النطاقات. |
Heatmap
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
rows / columns / values | string[] / string[] / number[][] | لا يوجد | الصفوف والأعمدة والقيم values[row][column]. |
labelEvery | number | 1 | تسمية كل عمود رقم n. |
less / more | ReactNode | لا يوجد | طرفا المفتاح. |
InsightBarChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
style | "highlight" | "forecast" | "diverging" | "highlight" | خاصية Style. |
highlight | number | لا يوجد | العمود الملوّن: الشهر المقصود أو الحالي. |
average / labelEvery | { value, label } / number | لا يوجد | دليل المتوسط، وتسمية كل عمود رقم n. |
DensityBars / SegmentedBar
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
emphasis / marker | [from, to] / number | لا يوجد | مقطع أغمق، وموضع العلامة الابتدائي. |
type | "segments" | "stacked" | "remainder" | "segments" | خاصية Type للشريط المقسّم. |
value / max / segments / parts | number / number / number / { label, value }[] | لا يوجد | التقدّم، أو الحصص بالنسبة المئوية. |
RadialChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
type | "gauge" | "arc-segments" | "rings" | "progress-ring" | "gauge" | خاصية Type. |
value / max / rings | number / number / { label, value, max? }[] | لا يوجد | القيمة، أو حتى ثلاث حلقات من الخارج. |
children | ReactNode | لا يوجد | الرقم والسطر في الوسط. |
ActivityHeatmap / CohortHeatmap / HeatStrip / CandlestickChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
columns / rows / values | string[] / string[] / number[][] | لا يوجد | النشاط: الأيام والساعات والقيم. |
rows (Cohort) | { label, values: number[] }[] | لا يوجد | النسبة النشطة لكل أسبوع. |
days / labels | ("up" | "down" | "flat")[] / { up, down, flat } | لا يوجد | الشريط اليومي وكلمات مفتاحه. |
data / last / names | { label, open, high, low, close, volume? }[] / number / { open, high, low, close } | لا يوجد | الشموع وآخر سعر وأسماء القيم الأربع. |
ChartValueTooltip / ChartAxisTag / ChartDot
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label / value | ReactNode | لا يوجد | التلميح: التسمية فوق القيمة. |
tone | "inverse" | "brand" | "positive" | "negative" | "neutral" | "neutral" / "brand" | لون الوسم أو النقطة حسب المعنى. |
DonutChart
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
data | { label, value }[] | لا يوجد | الأجزاء. |
total / totalLabel | ReactNode | لا يوجد | الرقم في الوسط وتحته. |
ChartMeter
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
type | "single" | "proportional" | "single" | خاصية Type. |
value / max | number | لا يوجد | للمقياس المفرد. |
parts | { label, value }[] | لا يوجد | للمقياس النسبي. |
start / end | ReactNode | لا يوجد | تحت الشريط في البداية والنهاية. |
البنية
كل رسم بياني هو البطاقة نفسها: رأس، ومساحة الرسم بمحاورها، ومفتاح. والأجزاء مكوّنات داخلية مشتركة، فيصل أي تغيير إلى كل رسم.
- 1. الرأس
title / subtitleالعنوان يقول ما يُقاس؛ والعنوان الفرعي يعطي الوحدة والفترة. - 2. محور القيم وخطوط الشبكةخمسة خطوط شبكة من الصفر، والتسميات في جهة البداية، بأرقام غربية.
- 3. البيانات
seriesالألوان تتبع ترتيب السلاسل؛ والأعمدة تبدأ من الصفر. - 4. محور الفئات
data[].labelأشهر أو أيام أو نطاقات أو مدن، في وسط كل خانة. - 5. المفتاح
ChartLegendمدخل لكل سلسلة، بترتيب البيانات نفسه. - 6. التلميحالفئة، ثم صف لكل سلسلة بقيمتها؛ عند التمرير والتركيز.
- 7. المؤشرخط عمودي يتبع المؤشر ويثبّت التلميح.
إرشادات الاستخدام
الرسم البياني يُري شكل الأرقام عبر الفئات أو الزمن. هنا: متى تصبح الأعمدة أوضح من القطاعات، وكيف تفصل السلاسل، وكيف تقول الوحدة والفترة، وكيف ينعكس الرسم كله في العربية.
1. رتّب الأجزاء الكثيرة في أعمدة
خمسة أجزاء أو أكثر تُقرأ أعمدةً مرتّبة أفضل منها قطاعات.
رتّب الأجزاء الكثيرة في أعمدة
2. افصل السلاسل المتجاورة
استخدم ألوان السلاسل بترتيبها؛ فهي تتغير في درجة اللون والإضاءة من واحدة إلى التالية. ست سلاسل على الأكثر، بترتيب المتغيرات: أزرق، كحلي، رمادي، ثم أزرق مخضر وأصفر وبرتقالي. وبعد ست، أبقِ الخمس الأولى واجمع البقية في «أخرى» بالرمادي.
افصل السلاسل المتجاورة
3. قل الوحدة والفترة
يحمل العنوان الفرعي الوحدة والفترة، فيصبح لأرقام المحور معنى. والأعمدة والمساحات تبدأ من الصفر؛ والخط يمكن أن يبدأ من غيره حين يكون التغير هو المقصود، وقل ذلك في العنوان الفرعي.
قل الوحدة والفترة
4. اعكس الرسم كله في العربية
في العربية ينعكس الرسم كله: ينتقل محور القيم إلى اليمين ويسير الزمن من اليمين إلى اليسار. والأرقام لا تنعكس. استخدم النسخة العربية؛ فترجمة النص وحده تترك الزمن يسير في الاتجاه الخطأ.
| الجزء | في العربية | السبب |
|---|---|---|
| محور القيم | على اليمين؛ والصفر يبقى في الأسفل | المحور حيث تبدأ القراءة؛ والأعلى ما زال أكثر |
| الفئات والزمن | من اليمين إلى اليسار، الشهر الأول على اليمين | يطابق ترتيب قراءة التسميات |
| الأعمدة الأفقية | التسميات على اليمين، والأعمدة تمتد إلى اليسار | تُقرأ التسمية قبل عمودها |
| الحلقي والدائري | تسير الأجزاء عكس عقارب الساعة من الأعلى | يبدأ الجزء الأول حيث تبدأ القراءة |
| المفتاح | السلسلة الأولى على اليمين | بترتيب البيانات نفسه |
| الأرقام | أرقام غربية 0123456789، كما في Ritla كلها | الأرقام تحتفظ بترتيبها داخل النص العربي |
| النسب المئوية والقيم بإشارة | داخل عزل من اليسار إلى اليمين (U+2066 إلى U+2069) | كي لا تظهر 80% أبدًا بصورة %80 وتبقى إشارة السالب في المقدمة |
اعكس الرسم كله في العربية
رموز التصميم والمواصفات
كل لون وقياس في الرسم البياني متغيّر. ألوان السلاسل الست بترتيبها، ثم متغيرات أجزاء البطاقة.
ألوان السلاسل
السلاسل من 1 إلى 6، بهذا الترتيب. التباين مقيس مقابل background/surface/lowest في كل ثيم، والمعيار WCAG يطلب 3:1 لعلامات الرسوم. الثلاثة الأولى هادئة وتغطي معظم الرسوم؛ ولا تدخل الثلاثة الأخرى إلا بعد ثلاث سلاسل.
| المتغيّر | التباين، فاتح / داكن | الاستخدام |
|---|---|---|
chart/series-1 | 3.35:1 / 6.27:1 | أزرق. السلسلة 1، وكل رسم بسلسلة واحدة |
chart/series-2 | 11.31:1 / 16.01:1 | كحلي (أزرق فاتح في الوضع الداكن). السلسلة 2 |
chart/series-3 | 5.25:1 / 5.85:1 | رمادي. السلسلة 3، وكذلك «أخرى» والفترة السابقة |
chart/series-4 | 3.13:1 / 12.36:1 | أزرق مخضر. السلسلة 4، بعد ثلاث سلاسل فقط |
chart/series-5 | 3.08:1 / 12.49:1 | أصفر. السلسلة 5 |
chart/series-6 | 3.05:1 / 8.50:1 | برتقالي. السلسلة 6 |
theme/brand/50 to theme/brand/800 | ست درجات: 50 و100 و200 و400 و600 و800 | سلّم الخريطة الحرارية من الفاتح إلى الداكن؛ وينقلب في الوضع الداكن |
الأجزاء
متغيرات البطاقة والشبكة والنصوص والتلميح. البطاقة بعرض 560، والرسوم في صف واحد من لوحة المعلومات بالارتفاع نفسه لتصطف مساحات الرسم.
| المتغيّر | الموضع | الاستخدام |
|---|---|---|
background/surface/lowest | البطاقة | تعبئة البطاقة؛ والحلقة بعرض 2 بكسل حول النقاط |
border/gray/soft | البطاقة وخطوط الشبكة | حدّ البطاقة وخطوط الشبكة |
border/gray/dim | خط الأساس | خط الصفر |
text/gray/intense | العنوان | body-16/Semibold |
text/gray/dim | العنوان الفرعي وتسميات المحور | body-12/Regular |
text/gray/muted | المفتاح وتسميات الفئات | body-12/Regular |
background/surface/inverse | التلميح | مع text/invert/white وlabel-12/Medium وbody-12/Regular |
radius/12 | البطاقة | زوايا البطاقة |
radius/4 | الأعمدة | الزوايا الخارجية فقط، فيبقى التكديس مستقيمًا عند الوصلات |
space-24, space-16 | البطاقة | الحشوة، والمسافة بين الرأس ومساحة الرسم والمفتاح |
اللون وحده لا يكفي
لا يحمل اللون وحده المعنى أبدًا: أبقِ المفتاح، وسمِّ القيم حيث تتسع، واستخدم الموضع أو فجوة 2 بكسل بين الأجزاء (WCAG 1.4.1).
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | ينقل التركيز إلى منطقة الرسم. |
| ArrowRightArrowLeft | الفئة التالية أو السابقة وتلميحها. في العربية التالية ArrowLeft. |
| HomeEnd | الفئة الأولى أو الأخيرة. |
| Escape | يخفي التلميح. |
ARIA
- كل رسم يُعرض أيضًا جدولًا مخفيًا بصريًا، فالأرقام في متناول قارئ الشاشة ولوحة المفاتيح دون الصورة.
- البطاقة
figureوعنوانهاfigcaption. - المقياس المفرد
role="meter"بقيمه. - منطقة الرسم
role="group"باسم الرسم، وتُقرأ الفئة التي يصلها المؤشر في منطقة حيّة. - الشريط المقسّم والعدّاد وحلقة التقدّم
meter، والحلقات قائمة مسمّاة. - لا تعتمد على اللون وحده: سمِّ السلاسل في المفتاح وفي التلميح.
افعل
- أظهر التلميح عند التمرير وعند التركيز بلوحة المفاتيح.
- قدّم الأرقام جدولًا لقارئات الشاشة.
- ألوان السلاسل الست تبلغ تباين 3:1 على السطحين، الفاتح والداكن.
- أبقِ المفتاح وفجوة 2 بكسل بين الأجزاء، كي لا يحمل اللون المعنى وحده.
ملاحظات العربية والاتجاه
ينعكس
- الفئات والزمن تجري من اليمين إلى اليسار، ومحور القيم على اليمين.
- الأعمدة الأفقية والمقاييس تبدأ من اليمين، والحلقة تدور عكس عقارب الساعة.
- العدّادات والحلقات تمتلئ عكس عقارب الساعة، والشموع وأعمدة الكثافة تجري من اليمين.
لا ينعكس
- المحور الرقمي يبقى من الأسفل إلى الأعلى، وترتيب التكديس من الأسفل.
- الأرقام غربية في العربية، كما في Figma.
- النسب والقيم بإشارة داخل عزل من اليسار إلى اليمين، فلا تظهر 80% كـ %80 وتبقى الإشارة أمام الرقم.
- الأرقام
- قيم الرسوم بأرقام غربية دائمًا؛ مرّر
valueFormatلتنسيق آخر. - الخط العربي
- العنوان
body-16Semibold، والعلاماتbody-12وnumeric-12.
افعل
- النسخة العربية: ينعكس الرسم كله، فمحور القيم على اليمين، والزمن من اليمين إلى اليسار، والمفتاح على اليمين.
- أبقِ الأرقام غربية، والنسب المئوية والقيم بإشارة داخل عزل من اليسار إلى اليمين.
تجنّب
- ترجمة النص وحده على رسم من اليسار إلى اليمين.
- عكس الأرقام، أو نقل الصفر إلى الأعلى.