دیزاین سیستم تقویمم
زبان مشترک طراحی و کد برای «تقویمم» — تقویم جلالی، وظایف و رزرو وقت. این سیستم همهچیز را از توکنهای رنگ تا الگوهای کاربری تعریف میکند تا وب و موبایل دقیقاً از یک سیستم واحد ساخته شوند؛ نه دو پیادهسازی شبیه به هم.
۱این سیستم چیست و برای چه کسی است؟
تقویمم یک محصول دادهمحور است: شبکههای ماه، هفته و روز، فهرست وظایف، فرمهای رویداد و جریانهای ورود و رزرو. چنین محصولی بیش از هر چیز به سازگاری نیاز دارد — هر پیکسل رنگ، هر شعاع گوشه و هر پیام خطا باید در همه صفحهها یک منطق واحد داشته باشد. این مستندات همان منطق را کدگذاری میکند: مبانی (توکنها)، کامپوننتها (قطعات آماده با کلاسهای واقعی) و الگوهای کاربری (راهحلهای تکرارشونده برای جریانهای محصول).
مخاطب این مستندات دو گروهاند: طراحان که هنگام طراحی صفحه جدید باید از توکنها و الگوهای موجود شروع کنند، و توسعهدهندگان که با لینککردن دو فایل CSS و یک فایل JS به همه قطعات دسترسی دارند — بدون بازنویسی استایل.
منبع حقیقت (Source of Truth)
| فایل | نقش | محتوا |
|---|---|---|
| assets/app.css | توکنها + کامپوننتهای پایه | متغیرهای رنگ/شکل/حرکت در دو پوسته، دکمه، فیلد، دیالوگ، چیپ، سوییچ، منو، FAB، توست، شبکه ماه |
| assets/jalali.js | موتور تقویم جلالی | تبدیل دقیق جلالی↔میلادی، تعطیلات ثابت شمسی، نام ماهها و روزها، قالببندی با رقم فارسی |
| assets/docs.css | پوسته همین مستندات | چارچوب مستندسازی، قاب نمونهها، جدولها، کارتهای بایدر/نبایدر |
| calendar.html | پیادهسازی مرجع | همه کامپوننتها و الگوها در کارکرد واقعی — هر نمونه این مستندات از همین کلاسها رندر شده است |
راهاندازی در هر صفحه جدید — فقط همین سه خط:
<link rel="stylesheet" href="assets/app.css"> <script src="assets/jalali.js"></script> <html lang="fa" dir="rtl" data-theme="light|dark">
۲اصول طراحی
هر تصمیم طراحی در این سیستم با یکی از این پنج اصل توجیه میشود. وقتی دو راه همارز پیش رو است، اصل بالاتر برنده است.
| اصل | یعنی چه | در عمل |
|---|---|---|
| ۱. جلالیمحور | تقویم جلالی هویت محصول است، نه یک پوسته محلی روی تقویم میلادی. | هفته از شنبه، جمعه و تعطیلات بهصورت قرمز، همه ارقام فارسی، نمای سال جلالی، محاسبات کبیسی دقیق. |
| ۲. راستچین اصیل | راستچین بودن از ابتدا در معماری کد است، نه آینهکردن چپچین. | فقط خصوصیتهای منطقی (inline-start/end)، آیکون برگشت به راست، ساعت و ارقام با جهت کنترلشده. |
| ۳. آرام و مطمئن | سطح سفیدِ خوانا، یک رنگ برند برای کنش، رنگ = اطلاعات نه تزئین. | آبی برند فقط برای اکشن اصلی و حالت فعال؛ رنگ قرمز تعطیلات فقط برای داده تقویمی؛ بدون گرادیان و سایههای نمایشی. |
| ۴. دسترسپذیر بهصورت پیشفرض | کنتراست، فوکوس و کیبورد جزو تعریف کامپوننتاند، نه اصلاح بعدی. | حلقه focus-visible روی همه کنشها، هدف لمسی ≥ ۴۴px، کاهش حرکت با prefers-reduced-motion، aria-checked و aria-label. |
| ۵. یکپارچه در همه سطوح | وب و موبایل از یک توکنست میسازند؛ شباهت ظاهری نتیجه است نه هدف. | آبی واحد #2563EB در هر دو سکو، پالت ۸رنگی یکسان برای تقویمها، حالت تاریک فقط با تعویض توکنها. |
۳ساختار مستندات
ساختار دستهبندی از الگوی رایج دیزاینسیستمهای بالغ (مانند سرخآب آرانکلود) پیروی میکند: مبانی ← کامپوننتها ← الگوها؛ هر سطح بر سطح قبل سوار است.
۴نقشه سریع توکنها
شش نقش پایه که همهچیز روی آنها سوار است. مقادیر کامل هر نقش در بخش رنگها مستند شده است.
| نقش | توکن | روشن | تاریک | کاربرد |
|---|---|---|---|---|
| پسزمینه | --bg | #FBFBFC | #101318 | بوم پشت صفحه |
| سطح | --surface … --surface-3 | پلهای تا #E8E9ED | پلهای تا #2E343D | کارتها، دیالوگها، نوارها |
| متن | --fg / --muted / --faint | سه سطح از #1B1E24 | سه سطح از #E5E7EC | متن اصلی / ثانویه / کمکی |
| خط | --border / --border-strong | #E3E5EA و #CFD3DB | #333945 و #454C59 | جداسازی سطحها بدون سایه |
| برند | --brand / --brand-container | #2563EB + نسخه ۱۱٪ | #8FB4FF + نسخه ۱۶٪ | اکشن اصلی و حالت فعال |
| معنایی | --holiday · --error · --warn · --ok | نسخههای روشنشده | تعطیلات/خطر · خطا · هشدار · موفقیت |
۵پوشش و نقشه راه
| بخش | وضعیت | توضیح |
|---|---|---|
| توکنها (رنگ، شکل، حرکت) | کامل | دو پوسته روشن/تاریک، پیادهشده در app.css |
| کامپوننتهای وب | ۱۶ کامپوننت | همه در اپ مرجع فعالاند؛ مستندات با نمونه زنده |
| الگوهای کاربری وب | ۱۰ الگو | شامل کلاسهای پنجره MD3 و جریان پیشنمایش→ویرایش |
| موتور تقویم جلالی | کامل | jalali.js — تبدیل، کبیس، تعطیلات، قالببندی |
| کیت موبایل (KMP) | در حال انطباق | نقشه توکن مشترک آماده است؛ FaScaffold و کامپوننتها باید روی همین توکنها سوار شوند (بریف §۲.۴) |
| خروجی Figma / توکنهای JSON | برنامه آینده | تولید خودکار از app.css پس از تثبیت نسخه ۱ |
نقطه شروع پیشنهادی: مبانی دیزاین ← کتابخانه کامپوننت ← الگوهای کاربری.