# سند جامع سیستم طراحی بصری و استانداردهای رابط کاربری (UI Design System & Typography Standard)
**سامانه مدیریت و پلتفرم عقیله (Aqila)**
**مرجع سیستم:** کلاینت وب و پنل مدیریت (`aqila_panel`) و راهنمای سراسری هوش مصنوعی (AI Agent Directive)
**نسخه:** 1.0.0
**وضعیت:** مصوب و الزامی (Mandatory Reference)
---
## ۱. هدف و دامنه کاربرد (Objective & Scope)
این سند، **مرجع واحد و غیرقابلتغییر (Single Source of Truth)** برای تمامی استانداردهای بصری، تایپوگرافی، رنگبندی، چیدمان، فاصلهگذاری، کامپوننتهای تعاملی و رفتارهای چندزبانه در رابط کاربری سامانه عقیله است.
> [!IMPORTANT]
> **قانون الزامآور هوش مصنوعی (AI Agent Rule):**
> هوش مصنوعی (AI Agent) در زمان ایجاد هر صفحه جدید، ساخت هر کامپوننت، ویرایش صفحات موجود، بازطراحی فرمها، فیلترها، جداول، تگها و وضعیتهای بارگذاری (Loading)، **باید ابتدا و بدون استثنا این سند را به عنوان مرجع قطعی رعایت نماید.** هرگونه کدنویسی بصری سلیقهای، استفاده از رنگهای رنگینکمانی مدادرنگی (Crayon-like)، فونتهای متفرقه یا ساختارهای ناهمگون اکیداً ممنوع است.
---
## ۲. زبان، تایپوگرافی و نگارش چندزبانه (Language & Typography)
سامانه عقیله یک سیستم بینالمللی با تمرکز بر سه زبان اصلی **فارسی (FA)**، **عربی (AR)** و **انگلیسی (EN)** است.
```
┌────────────────────────────────────────────────────────────────────────┐
│ مقیاس تایپوگرافی عقیله │
├───────────────────┬────────────┬─────────┬──────────────┬──────────────┤
│ سطح متنی (Role) │ سایز (Size)│ وزن (Wt)│ Line-Height │ کلاس Tailwind│
├───────────────────┼────────────┼─────────┼──────────────┼──────────────┤
│ Display / H1 │ 24px (1.5r)│ Black/900│ 1.35 (32px) │ text-2xl │
│ Page Title / H2 │ 20px (1.25)│ Bold/800│ 1.4 (28px) │ text-xl │
│ Section Title / H3│ 16px (1.0r)│ Bold/700│ 1.45 (24px) │ text-base │
│ Card Title / H4 │ 14px (.875)│ Bold/700│ 1.5 (21px) │ text-sm │
│ Body Text (اصلی) │ 13px-14px │ Medium/500│ 1.6 (22px) │ text-xs/sm │
│ Secondary / Muted │ 12px (.75r)│ Regular │ 1.5 (18px) │ text-xs │
│ Caption / Footnote│ 11px (.687)│ Medium │ 1.4 (16px) │ text-[11px] │
│ Badge / Tag Label │ 10px-11px │ Bold/700│ 1.0 (12px) │ text-[10px] │
│ Monospace / Stats │ 12px-20px │ Bold/900│ 1.2 (Tabular)│ font-mono │
└───────────────────┴────────────┴─────────┴──────────────┴──────────────┘
```
### ۲.۱. خانواده فونتها (Font Families)
1. **فارسی و عربی (RTL):**
- فونت استاندارد: `Vazirmatn` (وزنهای 400, 500, 700, 800, 900)
- فونت فالبک: `system-ui, -apple-system, 'Segoe UI', Tahoma, sans-serif`
2. **انگلیسی و ارقام/دادههای فنی (LTR):**
- متون انگلیسی: `Inter, system-ui, sans-serif`
- ارقام مالی، شناسهها، شماره سفارش، تاریخهای میلادی و ساعت: `font-mono` (فونت مونو اسپیس با Tabular Figures جهت تراز دقیق در جداول و کارتها).
### ۲.۲. ترکیب متون دوزبانه و اعداد (Mixed-Language Content)
- **ارقام فارسی در برابر انگلیسی:**
- در متون توضیحی و عناوین فارسی از ارقام بومی (`toFa(number)`) استفاده شود.
- در کد رهگیری، شماره کارت، شناسه دیتابیس (`#1240`)، مبالغ ارزی دلاری/دیناری (`$1,200` یا `15,000 IQD`) و تاریخهای لاگ، منحصراً از ارقام انگلیسی درون بلوک `font-mono` و با جهت `dir="ltr"` استفاده شود.
- **اصطلاحات فنی و لاتین در متن فارسی:**
- کلیه اسلاگها، نام فایلها و عبارتهای انگلیسی درون متون فارسی باید درون محفظه مجزا یا با `dir="ltr"` قرار گیرند تا نظم کلمات به هم نخورد.
- **پرهیز از Letter-Spacing غیرمجاز:**
- در خطوط فارسی و عربی به هیچ وجه از `letter-spacing` (کلاسهای `tracking-widest` و...) استفاده نشود؛ زیرا باعث تکهتکه شدن حروف متصل میشود.
---
## ۳. جهتچینی، ترازبندی و قواعد RTL / LTR
### ۳.۱. اصول جهتچینی (Directionality Rules)
- رابط کاربری به صورت پیشفرض **راستبهچپ (`dir="rtl"`)** است.
- **ویژگیهای منطقی (CSS Logical Properties):**
- به جای `left` و `right`، همواره از ویژگیهای منطقی استفاده شود:
- پدینگ و مارجین: `ps-` (padding-start)، `pe-` (padding-end)، `ms-` (margin-start)، `me-` (margin-end).
- گوشهها: `rounded-s-` (start) و `rounded-e-` (end).
- ترازبندی متن: `text-start` و `text-end` به جای `text-left` و `text-right`.
### ۳.۲. آیکونها در RTL
- آیکونهای هدایتی (مانند پیکان بازگشت، بعدی/قبلی، Breadcrumbs) باید در حالت RTL متناسب با جهت جریان اطلاعات بچرخند یا به صورت طبیعی بر اساس `start/end` قرار گیرند.
- آیکونهای متقارن (مانند جستجو، تقویم، تنظیمات، سبد خرید) نیاز به چرخش ندارند.
---
## ۴. پالت رنگی خنثی، مینیمال و معنادار (Neutral & Semantic Color System)
> [!CAUTION]
> **پرهیز جدی از رابط کاربری مدادرنگی (No "Crayon-like" Overly Colorful UI):**
> بیش از **۹۰٪ رابط کاربری** باید از رنگهای خنثی (سفید، خاکستری، اسلیت، تیره) تشکیل شود. استفاده از رنگهای تند (آبی روشن، نارنجی فسفری، بنفش تیره، سبز فسفری) به عنوان پسزمینه کارتها، بجها و کادرها کاملاً ممنوع است مگر اینکه معنای وضعیتی مشخصی داشته باشد.
```
┌────────────────────────────────────────────────────────────────────────┐
│ معماری پالت رنگی عقیله │
├───────────────────┬──────────────────────┬─────────────────────────────┤
│ توکن معنایی │ تم دارک (Dark Mode) │ تم لایت (Light Mode) │
├───────────────────┼──────────────────────┼─────────────────────────────┤
│ background │ #18191D (تیره مات) │ #F8FAFC (سفید-خاکستری محو) │
│ surface / card │ #22252C (کارت پایه) │ #FFFFFF (سفید خالص) │
│ surface-muted │ #1E2128 (پسزمینه فرعی)│ #F1F5F9 (خاکستری بسیار روشن)│
│ border │ rgba(255,255,255,0.1)│ rgba(15,23,42,0.10) │
│ border-soft │ rgba(255,255,255,0.06)│ rgba(15,23,42,0.06) │
│ primary (هویت برنز)│ #D09460 │ #D09460 │
│ primary-muted │ rgba(208,148,96,0.12)│ rgba(208,148,96,0.10) │
│ text-foreground │ #FFFFFF (خوانایی کامل)│ #0F172A (سرمهای-مشکی پرکنتراست)│
│ text-muted │ #8B8B8B (خاکستری متوسط)│ #64748B (خاکستری خوانا) │
│ text-subtle │ #666666 │ #94A3B8 │
└───────────────────┴──────────────────────┴─────────────────────────────┘
```
### ۴.۱. رنگهای معنایی و وضعیتها (Semantic Status Colors)
رنگهای اشباع منحصراً برای اعلام وضعیت و فیدبکهای مهم سیستم رزرو شدهاند:
1. **موفقیت / تایید (Success):**
- کارکرد: پرداخت موفق، تور تکمیلشده، رزرو فعال.
- رنگ: `Emerald` (لایت: `text-emerald-700 bg-emerald-50 border-emerald-200` | دارک: `text-emerald-400 bg-emerald-500/10 border-emerald-500/20`).
2. **هشدار / در انتظار (Warning / Pending):**
- کارکرد: در انتظار پرداخت، بررسی فیش، نزدیک به ظرفیت.
- رنگ: `Amber` (لایت: `text-amber-700 bg-amber-50 border-amber-200` | دارک: `text-amber-400 bg-amber-500/10 border-amber-500/20`).
3. **خطا / رد شده (Error / Destructive):**
- کارکرد: فیش نامعتبر، سفارش لغوشده، حذف آیتم.
- رنگ: `Rose / Red` (لایت: `text-rose-700 bg-rose-50 border-rose-200` | دارک: `text-rose-400 bg-rose-500/10 border-rose-500/20`).
4. **اطلاعات عمومی (Informational / Neutral):**
- کارکرد: دستهبندیها، تعداد بازدید، مشخصات عادی، تگهای عمومی.
- رنگ: **کاملاً خنثی (Neutral / Slate)** (`bg-muted/40 text-muted-foreground border-border-soft`). هرگز برای تگهای معمولی از رنگهای رنگینکمانی استفاده نشود.
---
## ۵. مقیاس فواصل، ابعاد و شعاع انحناها (Spacing, Sizing & Radii)
سامانه از سیستم فاصلهگذاری مضرب ۴ و ۸ پیکسلی تبعیت میکند:
```
┌────────────────────────────────────────────────────────────────────────┐
│ مقیاس فواصل استاندارد (Spacing) │
├─────────────┬─────────────┬────────────────────────────────────────────┤
│ توکن │ مقدار (px) │ کاربرد و موارد مصرف │
├─────────────┼─────────────┼────────────────────────────────────────────┤
│ space-xs │ 4px │ فاصله بین آیکون و متن، پدینگ میکرو │
│ space-sm │ 8px │ فاصله عناصر درون یک کامپوننت، گپ دکمهها │
│ space-md │ 12px │ فاصله آیتمهای لیست، پدینگ فیلدها │
│ space-lg │ 16px │ پدینگ افقی صفحات، پدینگ پیشفرض کارتها │
│ space-xl │ 20px │ فاصله بین بخشها و ستونهای فرمها │
│ space-2xl │ 24px │ گپ بین کارتهای اصلی و سکشنهای داشبورد │
│ space-3xl │ 32px │ فاصله عمودی سکشنهای بزرگ │
└─────────────┴─────────────┴────────────────────────────────────────────┘
```
### ۵.۱. شعاع انحناها (Border Radii)
- **تگها، بجها و المانهای کوچک:** `rounded-lg` (8px الی 10px)
- **فیلدهای ورودی و دکمهها:** `rounded-xl` (12px)
- **کارتها، جداول و بخشها:** `rounded-2xl` (16px)
- **دیالوگها، پاپآپها و مودالها:** `rounded-2xl` الی `rounded-3xl` (20px - 24px)
- **بجهای کپسولی / قرصی:** `rounded-full` (9999px)
---
## ۶. استاندارد جامع تگها و بجهای وضعیتی (Tags & Status Badges)
کلیه تگها باید ساختاری منسجم و یکدست داشته باشند:
```tsx
// ۱. تگ خنثی استاندارد (اطلاعات عمومی، دستهبندی، کشور، نسخه)
عراق
// ۲. بج وضعیتی تایید شده / موفق (Approved / Success)
تأیید شده
// ۳. بج وضعیتی در انتظار / بررسی (Pending / Warning)
در انتظار پرداخت
// ۴. بج وضعیتی رد شده / خطا (Rejected / Error)
رد شده
```
---
## ۷. استانداردهای کامپوننتهای پایه (Core Components Standard)
### ۷.۱. دکمهها (Buttons)
- **دکمه اصلی (Primary):** زمینه برنز عقیله (`bg-primary text-primary-foreground`)، ارتفاع 36px (`h-9`)، متن ضخیم (`font-bold text-xs`)، گوشههای `rounded-xl`.
- **دکمه ثانویه (Secondary / Outline):** زمینه خنثی یا بوردر ملایم (`border border-border-soft hover:bg-card/70 text-foreground`).
- **دکمه شبح (Ghost / Icon):** بدون کادر برای آیکونهای عملیاتی داخل جدول با هاور لطیف.
- **دکمه خطرناک (Destructive):** رنگ رز ملایم (`text-rose-500 hover:bg-rose-500/10`).
### ۷.۲. فیلدهای ورودی و جستجو (Inputs & Filters)
- ارتفاع استاندارد: `h-9` (36px).
- رنگ زمینه: `bg-surface-base` یا `bg-card/60`.
- بوردر: `border border-border-soft focus:border-primary/50 focus:ring-1 focus:ring-primary/30`.
- سایز متن ورودی و Placeholder: `text-xs`.
### ۷.۳. جداول دادهای (Data Tables)
- هدر جدول: زمینه ملایم `bg-card/60`، متن کمرنگ `text-muted-foreground text-xs font-bold`.
- ردیفها: ارتفاع مناسب، بوردر جداکننده `divide-y divide-border-soft`، هاور روان `hover:bg-card/50`.
- سلولها: پدینگ یکدست `p-3.5` یا `p-4`، اعداد به صورت `font-mono font-bold`.
### ۷.۴. کارتهای شاخص آماری (KPI Metric Cards)
- ساختار: کانتینر خنثی با کادر ملایم، عنوان کوچک در بالا (`text-xs text-muted-foreground`)، عدد بزرگ مونو در مرکز (`text-2xl font-black font-mono`) و توضیح کوتاه در زیر.
- رنگآمیزی: زمینه ملایم بدون اشباع شدید رنگی.
---
## ۸. استاندارد لودینگ و اسکلتون (Shimmer / Loading Skeleton Standard)
> [!IMPORTANT]
> **الگوی واحد لودینگ:**
> مطابق مصوبه سیستم، لودینگ تمامی صفحات و جداول پنل باید منحصراً از کامپوننت بازاستفادهپذیر **`Shimmer`** (برگرفته از صفحه صورتحسابها) استفاده کنند و از قراردادن اسپینرهای ناهماهنگ خودداری شود.
### مشخصات استاندارد Shimmer:
- **کانتینر:** `p-8 space-y-3` (یا درون `Card` با بوردر استاندارد).
- **ردیفها:** `h-12 bg-muted/30 animate-pulse rounded-lg`.
- **رفتار در تم لایت و دارک:** پالس ملایم با کنتراست طبیعی متناسب با توکن `--muted`.
```tsx
// نحوه فراخوانی استاندارد در صفحات
import { Shimmer } from '@/components/shared/Shimmer'
{isLoading ? (
) : (
)}
```
---
## ۹. دسترسیپذیری و تمهای تاریک و روشن (Accessibility, Light & Dark Mode)
1. **حداقل کنتراست متنی (WCAG AA Compliance):**
- تمامی متون اصلی باید دارای نسبت کنتراست حداقل `4.5:1` با پسزمینه باشند.
- از قرار دادن متن خاکستری روشن روی پسزمینه سفید یا خاکستری تیره روی پسزمینه مشکی اکیداً خودداری شود.
2. **حالت غیرفعال (Disabled States):**
- شفافیت `opacity-50` همراه با `cursor-not-allowed` بدون ناخوانا شدن متن.
3. **وضوح فوکوس (Focus Rings):**
- تمامی فیلدها و دکمهها باید دارای `focus-visible:ring-2 focus-visible:ring-primary/40` باشند تا ناوبری با کیبورد به درستی کار کند.
---
## ۱۰. چکلیست طلایی هوش مصنوعی قبل از تحویل هر تسک UI
قبل از تحویل هرگونه خروجی یا ثبت تغییرات در رابط کاربری، Agent باید این چکلیست را بررسی کند:
- [ ] **بررسی عدم استفاده از رنگهای مدادرنگی:** آیا از رنگهای تند غیرضروری برای کارتها و تگهای عادی پرهیز شده است؟
- [ ] **بررسی تایپوگرافی چندزبانه:** آیا متون فارسی از `Vazirmatn` و اعداد/کدها از `font-mono` تبعیت میکنند؟
- [ ] **بررسی ابعاد و فواصل:** آیا پدینگها و مارجینها مضرب ۴ و ۸ بوده و پدینگ افقی صفحات `16px` است؟
- [ ] **بررسی وضعیت لودینگ:** آیا لودینگ از کامپوننت استاندارد `Shimmer` با انیمیشن پالس استفاده میکند؟
- [ ] **بررسی دوگانگی تم:** آیا صفحه در هر دو حالت Light Mode و Dark Mode کنتراست و خوانایی کامل دارد؟
- [ ] **بررسی اصطلاحات و کلیدها:** آیا منطق برنامه صرفاً با کلیدهای انگلیسی کار کرده و هیچ متنی هاردکد نشده است؟