رموز التصميم
كيف يصبح متغير Figma متغيرًا في CSS وصنفًا في Tailwind بالاسم نفسه، ولماذا تبدّل الأوضاع المتغيرات لا الأصناف.
كل لون ومقاس وخط وحركة في Ritla UI رمز تصميم. لا يكتب أي مكوّن قيمة ثابتة، وهذا ما يتيح للثيم أن يغيّر الشكل دون أن يتغير سطر في التخطيط، وما يمنع ملف Figma والكود من الابتعاد أحدهما عن الآخر.
ما تحصل عليه#
ثلاثة ملفات CSS وملف JSON، وملف CSS اختياري للوضع الصارم:
| الملف | ما فيه |
|---|---|
ritla.css، ملف المتغيرات | القيم نفسها متغيّراتِ CSS: ألوان الوضع الفاتح، وخطوط الإنجليزية والعربية، والمسافات وأنصاف الأقطار وسماكات الحدود والظلال والحركة والطبقات. |
| الملف الداكن | ألوان الوضع الداكن والبادئة الشرطية theme-dark:، لطريقة واحدة من طرق التبديل إلى الداكن: ritla-dark-class.css أو ritla-dark-attr.css أو ritla-dark-system.css (راجع الوضع الداكن). |
theme.css | ثيم Tailwind v4: يربط أصنافًا مثل bg-surface-default وp-space-16 بتلك المتغيّرات، بجانب ألوان Tailwind ومقاييسه الأصلية، ويضيف البادئتين الشرطيتين dir-rtl: وdir-ltr: (انظر الاتجاه). |
tokens.json | قائمة مسطّحة بكل رموز التصميم: لكل رمز تصميم متغيّر CSS المقابل ونوعه وقيمته في كل وضع وما يشير إليه. للأدوات ووكلاء الذكاء الاصطناعي. |
يضيف npx ritla init ملفات CSS الثلاثة إلى lib/ritla/ في مشروعك ويستوردها بعد Tailwind. أما ritla-strict.css فلا يُضاف إلا إن طلبته: راجع الوضع الصارم.
كيف تُسمّى رموز التصميم#
اسم رمز التصميم هو مسار متغيّره في Figma. ومتغيّر CSS هو ذلك المسار بعد تحويل الشرطات المائلة إلى شرطات، تسبقه البادئة --ritla-، ويذكره tokens.json لكل رمز باسم cssVar. والصنف هو المسار دون مجموعته الأولى، فالاسم الذي يقرؤه المصمم في Figma هو الصنف الذي يكتبه المطوّر. وحيث يستخدم Tailwind الاسم نفسه، يأخذ صنف الثيم مجموعة خاصة به فلا يتعارض الاثنان: المسافات space-، والظلال والتمويه elevation-، وعروض الحاويات container-.
| Figma | Tailwind |
|---|---|
background/surface/default | bg-surface-default |
text/gray/txt-primary | text-gray-txt-primary |
text/brand/txt-subtle | text-brand-txt-subtle |
icons/gray/icon-strong | text-gray-icon-strong |
border/gray/soft | border-gray-soft |
space-16 | p-space-16، gap-space-16، ms-space-16 |
radius/8 | rounded-8 |
shadow/md | shadow-elevation-md |
body-14 (نمط نص: الحجم وارتفاع السطر وتباعد الحروف) | text-body-14 |
duration/moderate، easing/standard | duration-moderate، ease-standard |
z-index/dropdown | z-dropdown |
تُقرأ أسماء الألوان من العام إلى الخاص: ما تلوّنه (background أو text أو icons أو border)، ثم العائلة (gray أو brand أو red أو amber أو green)، ثم القوة. قوى النص بالترتيب: txt-primary وtxt-secondary وtxt-subtle وtxt-muted وtxt-dim وtxt-soft وtxt-faint. استخدم الثلاثة الأولى لكل نص يحتاج الناس إلى قراءته: تحقق معيار WCAG AA بنسبة 4.5:1 على أسطح الصفحة والبطاقات (من surface/lowest إلى surface/high، ومن container/soft إلى container/muted) في الوضعين. على surface/highest وcontainer/strong يقل txt-subtle الأخضر والكهرماني قليلًا عن الحد (4.25 و4.28 في الوضع الفاتح)، فاستخدم txt-secondary منهما هناك. أما surface/inverse وcontainer/fixed فتُستخدم معهما رموز النص invert وstatic. أما txt-muted وtxt-dim فتأكيدهما منخفض، وtxt-soft وtxt-faint للزخرفة والنص المؤقت.
مجموعات رموز التصميم#
- الألوان: الخلفيات والنصوص والأيقونات والحدود والشفافية (طبقات التفتيح والتظليل) والألوان المميزة ودرجات الثيم وألوان حلقة التركيز، ولكل منها قيمة فاتحة وأخرى داكنة.
- الطباعة: عائلة الخط ووزنه وحجمه وارتفاع السطر وتباعد الحروف، بقيمة للإنجليزية وأخرى للعربية.
- المسافات: مقياس واحد للحشو والفواصل والهوامش والمقاسات.
- الحدود: أنصاف الأقطار وسماكات الحدود.
- العروض: الحاويات والمكوّنات ومساحة اللمس ومقاسات العرض (بوحدة rem).
- التأثيرات: الظلال وحلقات التركيز وتمويه الخلفية.
- الحركة: المدد والمنحنيات.
- الطبقات: ترتيب ثابت لقيم z-index من
baseإلىtooltip.
الفاتح والداكن#
يبدّل الوضعُ قيمَ رموز التصميم لا الأصناف، فلا تحتاج معظم أجزاء المكوّن إلى بادئة شرطية للوضع الداكن. وحيث يحتاجها جزء منه يستخدم theme-dark:، ويربطها npx ritla init بطريقة التبديل إلى الداكن في تطبيقك: الصنف .dark افتراضيًا، أو data-theme="dark"، أو إعداد النظام. أما dark: في Tailwind فتبقى لك. والوضع الفاتح هو الافتراضي. الوضع الداكن في الثيم الافتراضي رمادي محايد: كل رمادي فيه متساوي الأحمر والأخضر والأزرق، فلا يبدو شيء مائلًا إلى الأزرق بجوار لون العلامة. المزيد في الوضع الداكن.
الطباعة الإنجليزية والعربية#
يكفي lang="ar" على أي عنصر ليأخذ قيم الطباعة العربية: خط IBM Plex Sans Arabic وأسطر أعلى ودون تباعد بين الحروف. والإنجليزية بخط Geist. كل سلسلة خطوط تحتوي العائلتين، فيظهر النص العربي داخل واجهة إنجليزية بخطه العربي، لا بخط لاتيني بديل.
<section lang="ar" dir="rtl">...</section>الاتجاه#
اكتب التخطيط بأصناف منطقية: ms-space-* وme-space-* وps-space-* وpe-space-* وstart-* وend-* وtext-start وborder-s وrounded-s-*. تتبع dir من تلقاء نفسها. وإن احتجت نمطًا خاصًا باتجاه، فاستخدم dir-rtl: وdir-ltr:. تطابقان أقرب سمة dir لا أي عنصر أب، فتبقى الجزيرة الإنجليزية داخل صفحة عربية (مقطع كود أو حقل رقم هاتف) من اليسار إلى اليمين. أما rtl: وltr: في Tailwind فلا يمسّهما الثيم، وتبقيان على معناهما: أي عنصر أب بذلك الاتجاه. راجع مبادئ العربية والاتجاه.
بجانب قيم Tailwind#
يضيف الثيم قيمه ولا يحذف شيئًا من قيم Tailwind. تبقى bg-red-500 وtext-sm وp-4 وfont-bold تعمل، وأسماء الثيم بجانبها: bg-red-normal وtext-body-14 وp-space-16 وfont-semibold. استخدم أسماء الثيم في كل ما تبنيه بـ Ritla UI، ليصله أي تغيير في الثيم.
خطوات المسافات هي 0 2 4 6 8 10 12 14 16 20 24 32 40 48 64 80 96 128 160 192 224 256 320، وأسماؤها بالبكسل: p-space-12 تعني 12 بكسل. أما p-12 فتبقى صنف Tailwind (بقيمة 3rem)، ولهذا فإن space- في الاسم مهمة. ولجمع أكثر من رمز تصميم استخدم قيمة اعتباطية مبنية من متغيّرات CSS الخاصة بها (cssVar لكل منها في tokens.json)، لا رقمًا خامًا.
ولاستخدام قيم الثيم وحدها، مع حذف قيم Tailwind الافتراضية، فعّل الوضع الصارم.
أسماء قد يشترك فيها ثيمك#
ألوان Ritla UI في مجالات أسماء بحسب دورها، فلا يتعارض متغير من متغيراتك مع واحد منها إلا إن تطابق الاسم كله بعد مجال الاسم. قارن كتلة @theme الخاصة بك بهذه الأسماء:
| صنفك | تبدأ أسماء Ritla UI بـ |
|---|---|
bg- | amber-، brand-، container-، danger-، disabled-، green-، overlay-، red-، skeleton-، static-، success-، surface-، warning- |
text- | amber-، brand-، danger-، disabled-، gray-، green-، icon-، invert-، red-، static-، success-، warning- |
border- | amber-، brand-، danger-، disabled-، gray-، green-، red-، success-، surface-، warning- |
fill-، stroke- | amber-، brand-، disabled-، gray-، green-، icon-، red-، static- |
| أي صنف لون | accent-، alpha-، chart-، theme- |
rounded- | رقم مجرّد: --radius-0، ومن --radius-2 إلى --radius-24 |
وبعد كل بادئة يأتي اسم الدور، مثل surface-default أو gray-txt-primary أو chart-series-1، ويذكر tokens.json كل اسم منها باسم cssVar. ويتعارض الاسمان في حالتين:
- المتغير نفسه في الاثنين. إن عرّفت كتلة
@themeالخاصة بك المتغير نفسه، مثل--radius-8، فالغلبة لكتلة@themeالتي تأتي بعد الأخرى، أيًّا كانت منهما. - الاسم نفسه في مجال أوسع. يقرأ Tailwind الصنف
bg-surface-defaultمن--background-color-surface-defaultقبل--color-surface-default، وكذلكtext-وborder-. فمتغيرك--color-surface-defaultيخسر أمام متغير Ritla UI فيbg-surface-default.
ولا اسم من هذه الأسماء من قيم Tailwind الافتراضية أو من متغيرات shadcn المعتادة، مثل --color-primary و--color-chart-1 و--radius-lg.
من أين تأتي رموز التصميم#
متغيّرات Figma هي المصدر. يأخذ بناء رموز التصميم لقطة من متغيّرات ملف ريتلا لـ Figma وأنماطه، ويحوّلها إلى tokens.json بصيغة DTCG، ثم يشغّل Style Dictionary ليكتب ملف المتغيرات وtheme.css وritla-strict.css وtokens.json المسطّح. البناء أمر واحد وقابل للتكرار: اللقطة نفسها تنتج الملفات نفسها حرفًا بحرف. لا تُحرَّر الملفات المولّدة يدويًا؛ أي تغيير يبدأ في Figma.
لوكلاء الذكاء الاصطناعي#
وجّه وكيلك إلى tokens.json لا إلى ملفات CSS: لكل عنصر name (مسار Figma) وcssVar وtype وvalues لكل وضع (light وdark أو default) وaliases (الرمز الأساسي الذي يشير إليه). الوكيل الذي يكتب text-gray-txt-primary بدل #151515 يُبقي واجهتك صحيحة في الوضعين.