فارسی‌محور بودن

اصل اول پرتو — طراحی از ابتدا برای زبان فارسی، نه ترجمه از انگلیسی

چرا فارسی اول؟

اکثر کتابخانه‌های UI برای LTR (انگلیسی) ساخته شده‌اند و RTL به عنوان «حالت جایگزین» اضافه می‌شود. این رویکرد مشکلات زیادی ایجاد می‌کند: فاصله‌گذاری معکوس، آیکون‌های برعکس، انیمیشن‌های ناهماهنگ.

پرتو از صفر برای فارسی طراحی شده است. RTL تنها حالت اصلی است، نه یک افزونه.

یکی از اصول بنیادین پرتو این است: فارسی اول، RTL بومی. این صفحه آنچه را که این اصل در عمل معنا می‌دهد توضیح می‌دهد.

پیکربندی پایه

تگ HTML

<html lang="fa" dir="rtl">

این دو attribute باید همیشه روی تگ <html> باشند:

lang="fa" — برای screen readerها و موتورهای جستجو
dir="rtl" — برای کارکرد صحیح CSS Logical Properties

CSS Logical Properties

پرتو از CSS Logical Properties به جای مقادیر فیزیکی استفاده می‌کند. این یعنی چیدمان‌ها به صورت خودکار با جهت متن تطبیق می‌یابند.

جدول معادل‌ها

فیزیکی — استفاده نکنید	Logical — استفاده کنید	معنا
`ml-*`	`ms-*`	margin-inline-start
`mr-*`	`me-*`	margin-inline-end
`pl-*`	`ps-*`	padding-inline-start
`pr-*`	`pe-*`	padding-inline-end
`left-*`	`start-*`	موقعیت از ابتدای خط
`right-*`	`end-*`	موقعیت از انتهای خط
`border-l-*`	`border-s-*`	حاشیه ابتدای خط
`border-r-*`	`border-e-*`	حاشیه انتهای خط
`rounded-l-*`	`rounded-s-*`	گوشه ابتدای خط
`rounded-r-*`	`rounded-e-*`	گوشه انتهای خط
`text-left`	`text-start`	تراز متن
`text-right`	`text-end`	تراز متن

مثال

// درست — با dir="rtl" به سمت راست قرار می‌گیرد
<div className="ms-4 ps-6 border-s-2 text-start">
  محتوا
</div>

// غلط — در RTL و LTR یکسان عمل می‌کند، تغییر جهت نمی‌دهد
<div className="ml-4 pl-6 border-l-2 text-left">
  محتوا
</div>

استثنا: مرکزگرایی مطلق

left-1/2 -translate-x-1/2 برای مرکز قرار دادن المان‌های absolute جهت‌دار نیستند و این یک استثنا مجاز است:

// این استفاده صحیح است
<div className="absolute left-1/2 -translate-x-1/2">
  محتوای مرکزی
</div>

اعداد فارسی

برای نمایش اعداد فارسی، از OpenType استفاده کنید، نه JavaScript.

روش درست — OpenType

/* در globals.css یا root element */
body {
  font-feature-settings: "ss01" 1;
}

این ویژگی در دیزاین سیستم پرتو به صورت پیش‌فرض تنظیم شده است. با فعال بودن ss01، فونت یکان بخ اعداد لاتین را به صورت فارسی نمایش می‌دهد.

روش غلط — تبدیل دستی با JavaScript

// این کار را نکنید
const persianNumber = num.toString().replace(/\d/g, (d) => '۰۱۲۳۴۵۶۷۸۹'[d])

مشکلات این رویکرد:

خواندن توسط screen readerها آسیب می‌بیند
Copy/Paste اعداد دچار مشکل می‌شود
سرعت رندر کاهش می‌یابد
سازگاری با ابزارهای جستجو کم می‌شود

formatNumber و convertToLocalNumbers

اگر نیاز به فرمت‌دهی اعداد داشتید (مثلاً جداکننده هزارها)، از utility های موجود استفاده کنید:

import { formatNumber, convertToLocalNumbers } from '@parto-system-design/ui'

// formatNumber: اضافه کردن جداکننده هزارها با locale
formatNumber(1234567) // → "۱٬۲۳۴٬۵۶۷"

// convertToLocalNumbers: تبدیل صریح برای موارد خاص
convertToLocalNumbers('2024') // → "۲۰۲۴"

آیکون‌های جهت‌دار

برخی آیکون‌ها مانند فلش‌ها در RTL باید چرخانده شوند:

import { Icons } from '@parto-system-design/ui'

// آیکون فلش که در RTL چرخش می‌خورد
<Icons.arrowRight className="rtl:rotate-180" />
<Icons.chevronRight className="rtl:rotate-180" />

کلاس‌های Tailwind برای RTL

// فقط در RTL نمایش داده می‌شود
<div className="hidden rtl:block">محتوای RTL</div>

// فقط در LTR نمایش داده می‌شود
<div className="hidden ltr:block">LTR Content</div>

استثنا: Instagram Post

کامپوننت InstagramPost همیشه LTR رندر می‌شود، حتی در صفحات RTL — چون این استاندارد برند اینستاگرام است:

// این کامپوننت داخلاً dir="ltr" دارد — نیازی به تنظیم دستی نیست
<InstagramPost data={postData} />

چک‌لیست RTL

قبل از commit کردن هر کامپوننت جدید:

هیچ property فیزیکی (ml, mr, pl, pr, left, right, border-l, border-r) در کد وجود ندارد
متن‌ها text-start دارند (نه text-right)
آیکون‌های جهت‌دار کلاس rtl:rotate-180 دارند
dropdown‌ها و popoverها از طرف درست باز می‌شوند
انیمیشن‌های کشویی جهت RTL را رعایت می‌کنند

تایپوگرافی فارسی

فضاگذاری (letter-spacing)

در متن فارسی، letter-spacing مثبت اغلب خوانایی را کاهش می‌دهد:

// مناسب برای فارسی
<h1 className="tracking-normal">عنوان</h1>

// نامناسب — فاصله بیش از حد بین حروف فارسی
<h1 className="tracking-widest">عنوان</h1>

شکستن خط

برای متن‌های طولانی فارسی، overflow-wrap را تنظیم کنید:

word-break: normal;
overflow-wrap: break-word;

خلاصه

قانون	توضیح
`lang="fa" dir="rtl"` روی `<html>`	پایه هر صفحه
CSS Logical Properties	`ms/me` نه `ml/mr`، `ps/pe` نه `pl/pr`
OpenType برای اعداد	`font-feature-settings: "ss01" 1` — پیش‌فرض سیستم
`rtl:rotate-180`	آیکون‌های جهت‌دار مثل فلش‌ها
فونت یکان بخ	پیش‌فرض سیستم — تغییر ندهید

صفحات مرتبط

دسترسی‌پذیری — lang="fa" برای screen reader، کنتراست
تایپوگرافی — فونت یکان بخ و ویژگی‌های OpenType
فضابندی — CSS Logical Properties در padding و margin