23 KiB

Raw Permalink Blame History

سند جامع سیستم طراحی بصری و استانداردهای رابط کاربری (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)

فارسی و عربی (RTL):
- فونت استاندارد: Vazirmatn (وزن‌های 400, 500, 700, 800, 900)
- فونت فال‌بک: system-ui, -apple-system, 'Segoe UI', Tahoma, sans-serif
انگلیسی و ارقام/داده‌های فنی (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)

رنگ‌های اشباع منحصراً برای اعلام وضعیت و فیدبک‌های مهم سیستم رزرو شده‌اند:

موفقیت / تایید (Success):
- کارکرد: پرداخت موفق، تور تکمیل‌شده، رزرو فعال.
- رنگ: Emerald (لایت: text-emerald-700 bg-emerald-50 border-emerald-200 | دارک: text-emerald-400 bg-emerald-500/10 border-emerald-500/20).
هشدار / در انتظار (Warning / Pending):
- کارکرد: در انتظار پرداخت، بررسی فیش، نزدیک به ظرفیت.
- رنگ: Amber (لایت: text-amber-700 bg-amber-50 border-amber-200 | دارک: text-amber-400 bg-amber-500/10 border-amber-500/20).
خطا / رد شده (Error / Destructive):
- کارکرد: فیش نامعتبر، سفارش لغوشده، حذف آیتم.
- رنگ: Rose / Red (لایت: text-rose-700 bg-rose-50 border-rose-200 | دارک: text-rose-400 bg-rose-500/10 border-rose-500/20).
اطلاعات عمومی (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)

کلیه تگ‌ها باید ساختاری منسجم و یکدست داشته باشند:

// ۱. تگ خنثی استاندارد (اطلاعات عمومی، دسته‌بندی، کشور، نسخه)
<Badge variant="outline" className="border-border-soft bg-surface-base text-muted-foreground text-[11px] font-medium px-2.5 py-0.5 rounded-lg">
  عراق
</Badge>

// ۲. بج وضعیتی تایید شده / موفق (Approved / Success)
<span className="inline-flex items-center gap-1.5 rounded-full bg-emerald-500/10 border border-emerald-500/20 px-2.5 py-0.5 text-[11px] font-bold text-emerald-600 dark:text-emerald-400">
  <span className="size-1.5 rounded-full bg-emerald-500" />
  تأیید شده
</span>

// ۳. بج وضعیتی در انتظار / بررسی (Pending / Warning)
<span className="inline-flex items-center gap-1.5 rounded-full bg-amber-500/10 border border-amber-500/20 px-2.5 py-0.5 text-[11px] font-bold text-amber-600 dark:text-amber-400">
  <span className="size-1.5 rounded-full bg-amber-500 animate-pulse" />
  در انتظار پرداخت
</span>

// ۴. بج وضعیتی رد شده / خطا (Rejected / Error)
<span className="inline-flex items-center gap-1.5 rounded-full bg-rose-500/10 border border-rose-500/20 px-2.5 py-0.5 text-[11px] font-bold text-rose-600 dark:text-rose-400">
  <span className="size-1.5 rounded-full bg-rose-500" />
  رد شده
</span>

۷. استانداردهای کامپوننت‌های پایه (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] الگوی واحد و سراسری لودینگ (Unified Shimmer Standard):
لودینگ تمامی صفحات، جداول و کارت‌ها در سامانه عقیله (هم در پنل وب و هم در اپلیکیشن فلاتر) باید منحصراً از اسکلتون یکپارچه شیمر با پالت خنثی (Neutral Slate) و ریتم پالس متناسب تبعیت کنند. هرگونه اسپینر ناهماهنگ، کانتینرهای بدون انیمیشن یا استفاده از رنگ‌های متفرقه در لودینگ اکیداً ممنوع است.

۸.۱. پالت رنگی و زمان‌بندی استاندارد شیمر (Shimmer Color Tokens & Timing)

برای جلوگیری از چندپارگی بصری و پرهیز از لودینگ‌های کدر یا مدادرنگی، رنگ‌های شیمر در تمام کلاینت‌ها قفل شده است:

تم روشن (Light Mode):
- رنگ پایه (Base): #E2E8F0 (توکن outline / muted-200)
- رنگ درخشش (Highlight): #F8FAFC (توکن muted-50)
تم تاریک (Dark Mode):
- رنگ پایه (Base): #22252C (توکن card-base)
- رنگ درخشش (Highlight): #333742 (توکن card-highlight)
دوره تناوب انیمیشن (Cycle Period): دقیقاً 1500ms (۱.۵ ثانیه) برای ایجاد پالس موجی لطیف، طبیعی و یکنواخت.

۸.۲. مشخصات پیاده‌سازی در وب و پنل مدیریت (`aqila_panel`)

کامپوننت مرجع: @/components/shared/Shimmer
کانتینر: p-8 space-y-3 (یا درون Card با بوردر استاندارد).
ردیف‌ها: h-12 bg-muted/30 animate-pulse rounded-lg.
رفتار در تم لایت و دارک: پالس ملایم با کنتراست طبیعی متناسب با توکن --muted.

// نحوه فراخوانی استاندارد در صفحات پنل
import { Shimmer } from '@/components/shared/Shimmer'

{isLoading ? (
  <Shimmer withCard cardHeaderTitle="صورت‌حساب‌ها" rows={5} />
) : (
  <TableContent />
)}

۸.۳. مشخصات پیاده‌سازی در اپلیکیشن فلاتر (`aqila_flutter`)

مرجع واحد هماهنگ‌کننده موج (Single Source of Truth): ویجت AppShimmer در مسیر: lib/core/ui_kit/atoms/app_shimmer.dart
ویجت‌های اتمیک درون اسکلتون:
1. ShimmerBox: جهت ترسیم کارت‌ها، بنرها، تصاویر و دکمه‌ها (AppRadii.radiusSm تا AppRadii.radiusLg).
2. ShimmerLine: جهت ترسیم سطرهای متنی و عناوین با ارتفاع پیش‌فرض 14px و انحنای 4px.
3. ShimmerCircle: جهت ترسیم آواتارها، آیکون‌ها و بج‌های دایره‌ای.
وضعیت ویجت ShimmerWidget:
ویجت ShimmerWidget در مسیر lib/core/widgets/shimmer_widget.dart صرفاً یک آداپتور سازگاری گذشته‌نگر (Legacy Adapter) است تا کدهای قدیمی متوقف نشوند. در کلیه فیچرها، صفحات و پول‌ریکوئست‌های جدید باید منحصراً از AppShimmer استفاده شود.

// نحوه فراخوانی استاندارد در اپلیکیشن فلاتر
import 'package:tourism/core/ui_kit/atoms/app_shimmer.dart';

return const AppShimmer(
  child: Column(
    children: [
      ShimmerBox(width: double.infinity, height: 160, borderRadius: 16),
      SizedBox(height: 12),
      ShimmerLine(width: 140, height: 16),
      SizedBox(height: 8),
      ShimmerLine(width: 220, height: 12),
    ],
  ),
);

۹. دسترسی‌پذیری و تم‌های تاریک و روشن (Accessibility, Light & Dark Mode)

حداقل کنتراست متنی (WCAG AA Compliance):
- تمامی متون اصلی باید دارای نسبت کنتراست حداقل 4.5:1 با پس‌زمینه باشند.
- از قرار دادن متن خاکستری روشن روی پس‌زمینه سفید یا خاکستری تیره روی پس‌زمینه مشکی اکیداً خودداری شود.
حالت غیرفعال (Disabled States):
- شفافیت opacity-50 همراه با cursor-not-allowed بدون ناخوانا شدن متن.
وضوح فوکوس (Focus Rings):
- تمامی فیلدها و دکمه‌ها باید دارای focus-visible:ring-2 focus-visible:ring-primary/40 باشند تا ناوبری با کیبورد به درستی کار کند.

۱۰. چک‌لیست طلایی هوش مصنوعی قبل از تحویل هر تسک UI

قبل از تحویل هرگونه خروجی یا ثبت تغییرات در رابط کاربری، Agent باید این چک‌لیست را بررسی کند:

بررسی عدم استفاده از رنگ‌های مدادرنگی: آیا از رنگ‌های تند غیرضروری برای کارت‌ها و تگ‌های عادی پرهیز شده است؟
بررسی تایپوگرافی چندزبانه: آیا متون فارسی از Vazirmatn و اعداد/کدها از font-mono تبعیت می‌کنند؟
بررسی ابعاد و فواصل: آیا پدینگ‌ها و مارجین‌ها مضرب ۴ و ۸ بوده و پدینگ افقی صفحات 16px است؟
بررسی وضعیت لودینگ: آیا لودینگ از کامپوننت استاندارد Shimmer با انیمیشن پالس استفاده می‌کند؟
بررسی دوگانگی تم: آیا صفحه در هر دو حالت Light Mode و Dark Mode کنتراست و خوانایی کامل دارد؟
بررسی اصطلاحات و کلیدها: آیا منطق برنامه صرفاً با کلیدهای انگلیسی کار کرده و هیچ متنی هاردکد نشده است؟

23 KiB Raw Permalink Blame History