انتقل إلى المحتوى

التثبيت

احصل على Ritla UI

هيّئ مشروعك بأداة ريتلا، وأضف المكوّنات كمصدر تملكه، واستخدم مفتاح ترخيصك. وأداة shadcn تعمل أيضًا.

يُثبَّت Ritla UI كمصدر. تنسخ أداة سطر الأوامر كل مكوّن إلى مشروعك، وتثبّت ما يعتمد عليه، وتهيّئ رموز التصميم للثيم مرة واحدة، فيكون الكود ملكك تقرؤه وتعدّله.

المتطلبات#

تطبيق React على Next.js أو Vite، وTailwind CSS الإصدار 4، وNode الإصدار 20 أو أحدث، واسم مستعار للاستيراد مثل @/* في tsconfig.json.

يعمل في التطبيقات الجديدة والقائمة#

يعمل Ritla UI في التطبيقات الجديدة والقائمة. التثبيت الافتراضي يضيف الثيم بجانب قيم Tailwind الافتراضية، ولا يغيّر أي صنف من أصنافك: تبقى p-4 وgap-6 وbg-red-500 وtext-sm وrounded-lg وshadow-md وdark: وrtl: كما كانت تمامًا قبل التثبيت.

تحمل أصناف Ritla UI أسماءً لا يستخدمها Tailwind، فلا تتعارض المجموعتان أبدًا:

أصنافك، كما هيأصناف Ritla UI، بجانبها
p-4، gap-6p-space-16، gap-space-24
bg-red-500bg-surface-default، bg-red-normal
text-smtext-body-14
shadow-mdshadow-elevation-md
dark:theme-dark:
rtl:، ltr:dir-rtl:، dir-ltr:

ولا يضيف الثيم أي نمط عام كذلك: لا قاعدة على html أو body أو :root تغيّر خطك أو تباعد حروفك أو حلقة التركيز لديك. تبقى صفحاتك كما كانت، وتظهر المكوّنات كما تظهر في هذا التوثيق. وإن أردت مقياس Ritla UI وحده ففعّل الوضع الصارم.

واستثناء واحد عليك أن تتحقق منه: إن كانت كتلة @theme الخاصة بك تعرّف من قبل متغيرًا باسم يطابق تمامًا أحد أسماء Ritla UI، مثل لون خلفية باسم surface-default أو --radius-8، فإن الاسم يصير مشتركًا بينهما ويغلب أحدهما الآخر. فغيّر اسم متغيرك إلى اسم خارج تلك الأسماء. وتذكرها صفحة رموز التصميم.

جهّز المشروع#

npx ritla init

يتعرّف init على إطار العمل وإصدار Tailwind والاسم المستعار للاستيراد، ويكتب ritla.json، ويثبّت @ritla/core (مجاني) ويستورد أنماطه في ملف الأنماط العام. وإذا كان مفتاح الترخيص مضبوطًا يثبّت أيضًا رموز التصميم للثيم الافتراضي.

ويسألك سؤالًا واحدًا:

text
How does your app turn dark mode on?  1. class  a "dark" class on <html> (shadcn; next-themes with attribute="class")  2. data-theme  a data-theme="dark" attribute (next-themes by default)  3. system  the operating system setting (prefers-color-scheme)Choose 1-3 [1, the default]:

الضغط على Enter يختار الخيار الافتراضي، class. وإن كان ملف أنماطك يعرّف @custom-variant dark من قبل، فالخيار الافتراضي يتبعه. وللإجابة دون السؤال مرّر --dark class أو --dark data-theme أو --dark system. وخارج الطرفية، في CI مثلًا، يأخذ init الخيار الافتراضي دون أن يسأل. وتُحفظ الإجابة في ritla.json، فتبقى عليها أوامر add وupdate اللاحقة، ويغيّرها npx ritla init --dark <answer>.

ثم سؤال ثانٍ:

text
Use Ritla's fonts or your app's font?  1. ritla  Ritla UI's fonts: Geist and IBM Plex Sans Arabic, per language  2. app  your app's font: the components inherit it from the pageChoose 1-2 [1, the default]:

الإجابة ritla لا تكتب شيئًا: تحمل المكوّنات خطوط Ritla UI بنفسها، وفي Next.js يجهّزها npx ritla add fonts. أما الإجابة app فتضيف كتلة @theme inline قصيرة بعد أسطر الاستيراد، فترث font-family-body وfont-family-display خط صفحتك، ويبقى font-family-numeric على خط الأرقام في Ritla UI لتبقى الأرقام متحاذية. ومع app تأكّد أن في سلسلة خطوط تطبيقك خطًا عربيًا، وإلا ظهرت العربية بخط النظام. وللإجابة دون السؤال مرّر --font ritla أو --font app، وخارج الطرفية يأخذ init الخيار الافتراضي، وتُحفظ الإجابة في ritla.json باسم font. ولتسمية خط واحد لكل المكوّنات بدلًا من ذلك، راجع الخطوط.

لكل طريقة ملف يحمل ألوان الثيم الداكنة ويعرّف البادئة الشرطية theme-dark:: ritla-dark-class.css وritla-dark-attr.css وritla-dark-system.css. وإجابتك تحدد أيّها يستورده init، فتتحول المكوّنات إلى الداكن بالطريقة نفسها التي تتحول بها بقية تطبيقك. والخيار الافتراضي هو الصنف .dark. راجع الوضع الداكن.

ثم يستورد ملف أنماطك العام الثيم بهذا الترتيب:

css
@import "tailwindcss";@import "../lib/ritla/ritla-strict.css";   /* strict only */@import "@ritla/core/styles.css";@import "../lib/ritla/ritla.css";@import "../lib/ritla/theme.css";@import "../lib/ritla/ritla-dark-class.css"; /* or -attr / -system */

كل مكوّن يقرأ الثيم، فثبّته قبل أول مكوّن: npx ritla init ومفتاح الترخيص مضبوط، أو npx ritla add style. وإن تخطّيته وصلت المكوّنات عناصر بلا تنسيق، دون أي رسالة خطأ.

الوضع الصارم#

الوضع الصارم اختياري، ولا يُفعَّل إلا إن طلبته. وهو لتطبيق جديد، أو تخطيط مخصّص، لا يستخدم إلا مقياس Ritla UI:

npx ritla init --strict

وفي مشروع مهيّأ من قبل، يفعل npx ritla add style-strict الشيء نفسه. يضيف الملف ritla-strict.css. ومكانه الموصى به بعد Tailwind مباشرة وقبل ملفات الثيم، ويعمل أيضًا إن جاء أخيرًا، لأنه يعرّف قيم الثيم من جديد بعد إلغاء قيم Tailwind. وفيه أمران لا يفعلهما التثبيت الافتراضي أبدًا:

  • يلغي قيم Tailwind الافتراضية. تُحذف ألوان Tailwind ومسافاته وأنصاف أقطاره وظلاله وتمويهاته وخطوطه وأوزانها وأحجام النص وارتفاعات الأسطر وتباعد الحروف والحاويات ومقاسات العرض ومنحنيات الحركة، فلا تولّد bg-red-500 أو p-4 أو text-sm أي CSS، ولا يعمل إلا ما في الثيم من أسماء.
  • يضيف الأنماط الأساسية. تأخذ الصفحة عائلة خط الثيم بالإنجليزية والعربية، ويُلغى تباعد الحروف في النص العربي، ويأخذ كل عنصر يتلقى التركيز حلقة التركيز من الثيم، وكل transition مجرّد مدة الحركة ومنحناها من الثيم.

اقصره على التطبيقات الجديدة والتخطيطات المخصّصة: في تطبيق قائم، الأصناف التي يحذفها هي الأصناف التي يستخدمها ذلك التطبيق.

أضف مفتاح الترخيص#

مكوّنات Ritla UI مدفوعة. انسخ مفتاحك من لوحة التحكم (التراخيص) إلى .env.local، ويجب أن يكون هذا الملف مستثنى من git:

RITLA_LICENSE_KEY=your-key

تقرأ أداة سطر الأوامر المفتاح من متغيرات البيئة، ثم من .env.local، ثم من .env، ولا ترسله إلا إلى ritla.app عبر HTTPS: إن ذكر ritla.json سجلًا آخر فلا يصله المفتاح، ما لم تعلن ثقتك بذلك السجل بالمتغير RITLA_REGISTRY_TRUST في بيئة الطرفية لديك، لا في ملف من ملفات المشروع. ولا تكتب الأداة المفتاح في أي ملف. في بيئة CI اضبط RITLA_LICENSE_KEY سرًّا من أسرار خط التشغيل. والأمر npx ritla login يتحقق من الإعداد.

أضف المكوّنات#

npx ritla add phone-input card-details

يجلب add كل مكوّن وكل ما يعتمد عليه، ويكتب الكود المصدري في مشروعك (وهو ملكك)، ويثبّت حزم npm التي يحتاجها، ويدمج أنماطه. الملفات التي عدّلتها تبقى كما هي ما لم تمرّر --overwrite. وفي صفحة كل مكوّن تجد أمره بالضبط تحت «التثبيت».

ابقَ على آخر إصدار#

يعرض npx ritla diff ما تغيّر في السجل منذ التثبيت، ويطبّق npx ritla update التغييرات على الملفات التي لم تعدّلها. وفي مرجع سطر الأوامر كل الأوامر وخياراتها.

رسائل قد تظهر لك#

  • «... جزء من Ritla UI» (401): لم يُرسل مفتاح. اضبط RITLA_LICENSE_KEY.
  • «مفتاح الترخيص غير صالح» أو «انتهت صلاحيته» أو «لا يشمل ...» (403): راجع المفتاح في لوحة التحكم.
  • «طلبات كثيرة» (429): انتظر عدد الثواني الظاهر.

الجزء المجاني: @ritla/core#

الحزمة @ritla/core مجانية بترخيص MIT، ويثبّتها init نيابةً عنك. ولتثبيتها وحدها: npm install @ritla/core (تحتاج React 18 أو أحدث). فيها ما يقوم عليه كل مكوّن: <Ltr> و<Isolate> لجزر الاتجاه، وformatNumber وtoNumerals وparseNumber لمجموعات أرقام صريحة، و<Mirror> وisDirectionalIcon للأيقونات التي تراعي الاتجاه، و@import "@ritla/core/styles.css" لإعدادات الخط العربي الافتراضية.

إن كنت تستخدم shadcn#

يعتمد السجل صيغة shadcn، فتستطيع المشاريع التي تعمل بأداة shadcn تثبيت Ritla UI بها. ومع الإصدار 4 من shadcn أو أحدث، يثبّت npx shadcn add @ritla/style الثيم بطريقة الصنف .dark. راجع استخدام shadcn بدلًا من ذلك.

أسماء تغيّرت قبل الإصدار#

تغيّرت أسماء متغيرات Ritla UI ومزوّده وبعض أصنافه قبل إصداره العام الأول في 28 أكتوبر 2026، ليتمكن من العمل بجانب Tailwind. التثبيت الجديد لا يتطلب منك شيئًا، أما التثبيت السابق لهذا التاريخ فيتبع صفحة الترحيل، وفيها كل اسم تغيّر.