feat: add Figma token mapping and guidelines for project implementation

.claude/skills/figma-to-feature/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: figma-to-feature
+description: وقتی کاربر یک لینک figma.com/design با node-id می‌دهد، صفحه را تحلیل
+  کن، نیازهای فرانت‌اند و بک‌اند را استخراج کن و پس از تأیید پیاده‌سازی کن.
+---
+
+## بخش ۰ — زبان (قبل از هر کاری)
+- ورودی من فارسی است. منظور را استخراج کن، نه ترجمه‌ی لغوی.
+- متن را به یک normalized English spec تبدیل کن با فیلدهای:
+  Goal / Scope (in-out) / Constraints / Acceptance criteria / Ambiguities
+- اصطلاحات فینگلیش (کامپوننت، اندپوینت، باتن) اصطلاح فنی‌اند، ترجمه نکن.
+- اسم متغیر، مسیر فایل، اسم کامپوننت و هر چیز داخل بک‌تیک را عیناً حفظ کن.
+- spec انگلیسی + خلاصه‌ی برداشتت به فارسی را نشانم بده و منتظر تأیید بمان.
+  اگر Ambiguities خالی نبود، سؤال‌ها را بپرس. بدون تأیید، کد ننویس.
+- خروجی: کد/کامنت/داکیومنت/کامیت انگلیسی. گفت‌وگو با من فارسی.
+  رشته‌های UI فارسی و از فایل i18n پروژه — هاردکد ممنوع.
+
+## بخش ۱ — استخراج از فیگما
+- fileKey و node-id را از URL دربیاور.
+- get_design_context → ساختار و لِی‌اوت
+- get_variable_defs → رنگ/اسپیسینگ/تایپوگرافی
+- get_screenshot → مرجع تطبیق بصری
+- download_assets → آیکون و تصاویر
+- توکن‌های فیگما را با mapping.md به متغیرهای واقعی پروژه نگاشت کن.
+
+## بخش ۲ — ممیزی کدبیس (اجباری، قبل از هر تحلیلی)
+
+هر بار که یک لینک صفحه می‌گیری، باید هم بک‌اند و هم فرانت‌اند را واقعاً بگردی.
+حدس زدن ممنوع؛ فقط چیزی که با Grep/Read در کد دیدی.
+
+### الف) ممیزی بک‌اند
+- routes/controllers را بگرد: کدام اندپوینت‌ها مرتبط با این صفحه از قبل وجود دارند؟
+- مدل‌ها و اسکیمای دیتابیس: کدام جدول/فیلد لازم است و از قبل هست؟
+- سرویس‌ها و validationها و middleware مرتبط
+- برای هر مورد بنویس: مسیر فایل + شماره خط
+
+### ب) ممیزی فرانت‌اند
+- کامپوننت‌های design system که می‌شود reuse کرد (با مسیر فایل)
+- روت مربوطه هست یا نه
+- hook/service/state موجود برای این داده
+- فایل i18n: کلیدهای متنی این صفحه از قبل هستند؟
+- برای هر مورد بنویس: مسیر فایل + شماره خط
+
+### ج) خروجی ممیزی — این جدول را بده
+| مورد | لایه | وضعیت | فایل | اقدام |
+|------|------|-------|------|-------|
+| نام دقیق | Frontend/Backend | ✅ موجود / ✏️ نیاز به ادیت / 🆕 جدید | مسیر:خط | یک جمله |
+
+### د) مبهم‌ها
+هر چیزی که از دیزاین معلوم نیست: empty state، حالت خطا، لودینگ، pagination،
+دسترسی/نقش کاربر، اعتبارسنجی فیلدها. لیست کن و بپرس.
+
+منتظر تأیید من بمان.
+
+---
+
+## بخش ۳ — TODO List (اجباری)
+
+بعد از تأیید ممیزی، با ابزار TodoWrite یک TODO بساز. قواعد:
+
+- ترتیب حتماً: **Backend → Frontend → i18n → تست → تطبیق بصری**
+  (فرانت را قبل از آماده شدن اندپوینت نساز.)
+- هر آیتم اتمیک و قابل تست باشد. آیتم مبهم مثل «صفحه را بساز» ممنوع.
+- هر آیتم TODO باید تست خودش را هم شامل شود، نه یک آیتم «تست» در آخر.
+- ساختار پیشنهادی:
+  1. [BE] مایگریشن/مدل X — + تست
+  2. [BE] توسعه‌ی اندپوینت Y (یا ساخت جدید، اگر توجیه شد) — + integration test
+  3. [FE] service/hook برای فراخوانی Y — + unit test
+  4. [FE] کامپوننت A (presentational) — + تست رندر
+  5. [FE] کامپوننت B (تعاملی) — + تست تعامل
+  6. [FE] مونتاژ صفحه و روت
+  7. [i18n] کلیدهای متنی فارسی
+  8. [QA] اجرای کل تست‌ها
+  9. [QA] مقایسه با اسکرین‌شات فیگما و اصلاح اختلاف‌ها
+
+TODO را قبل از شروع نشانم بده.
+
+---
+
+## بخش ۴ — اجرا، مرحله به مرحله
+
+- **همیشه فقط یک آیتم in_progress باشد.** موازی‌کاری ممنوع.
+- ترتیب TODO را رعایت کن؛ از روی آیتم‌ها نپر.
+- بعد از هر آیتم: تستش را اجرا کن. **آیتم بدون تست سبز، completed علامت نمی‌خورد.**
+- بعد از هر آیتم یک خط فارسی گزارش بده: چه ساختی، کدام فایل، تست سبز شد یا نه.
+- اگر وسط کار به چیزی برخوردی که در ممیزی ندیده بودی (اندپوینت پنهان، کامپوننت
+  مشابه، تضاد با SOLID) → **توقف کن**، TODO را به‌روز کن، و از من تأیید بگیر.
+  خودسرانه scope را عوض نکن.
+- در آخر: خروجی را با اسکرین‌شات فیگما مقایسه کن، اختلاف‌ها را لیست و اصلاح کن،
+  و کل تست‌ها را یک بار دیگر اجرا کن.
+
+## قواعد الزامی — بدون استثنا
+
+### ۱. SOLID
+- SRP: هر کامپوننت/کلاس یک مسئولیت. کامپوننتی که هم fetch می‌کند هم رندر می‌کند
+  باید به hook/service + کامپوننت presentational شکسته شود.
+- OCP: رفتار جدید با prop/strategy، نه if/else تو در تو در کد موجود.
+- LSP: هر پیاده‌سازی جایگزین قرارداد اینترفیس را کامل رعایت کند.
+- ISP: props و اینترفیس بزرگ ممنوع؛ به قراردادهای کوچک بشکن.
+- DIP: UI و لایه‌ی بیزنس مستقیم به axios/fetch/ORM وابسته نشوند.
+اگر SOLID با ساختار فعلی تضاد داشت، توقف کن و بپرس؛ خودسرانه بازنویسی نکن.
+
+### ۲. API جدید — آخرین گزینه
+1. کل لایه‌ی routes/controllers را بگرد.
+2. اگر اندپوینتی با یک پارامتر یا فیلد اضافه کافی است → همان را
+   backward-compatible توسعه بده.
+3. فقط اگر هیچ اندپوینتی نبود، جدید بساز.
+در جدول تحلیل برای هر نیاز بنویس: «موجود X» / «توسعه‌ی X» / «جدید — چون این‌ها
+را بررسی کردم و کافی نبودند: [...]». بدون این توجیه، اندپوینت جدید نساز.
+
+### ۳. مستندسازی — دقیق و مختصر
+- هر تابع/کامپوننت عمومی: بلاک کوتاه (چه می‌کند، ورودی، خروجی، خطاها).
+- هر اندپوینت: متد، مسیر، payload، response، کدهای خطا — در همان فرمت
+  مستندات فعلی پروژه.
+- کامنت بدیهی ممنوع. «چرا» را بنویس، نه «چه».
+
+### ۴. تست — بدون تست کار تمام نیست
+- منطق بیزنس/سرویس/هوک: unit test با حالت موفق + خطا + مرزی.
+- اندپوینت جدید یا توسعه‌یافته: integration test.
+- کامپوننت تعاملی: تست رندر + تست تعامل.
+- از فریم‌ورک تست موجود پروژه استفاده کن.
+- تست‌ها را اجرا کن و خروجی سبز را نشان بده.

.claude/skills/figma-to-feature/mapping.md

@@ -0,0 +1,140 @@
+# Figma → Project token mapping
+
+نگاشت توکن‌های خروجی `get_variable_defs` فیگما به متغیرهای واقعی این پروژه.
+**منبع حقیقت:** `assets/admin/styles.css` (بلاک `:root`). هرگز hex هاردکد نکن — همیشه `var(--token)`.
+
+---
+
+## Colors — brand
+
+| نقش فیگما (نمونه نام‌ها) | متغیر پروژه | مقدار |
+|---|---|---|
+| Primary / Brand / Indigo 500 | `--primary` | `#5559CE` |
+| Primary hover / 600 | `--primary-600` | `#494CB3` |
+| Primary pressed / 700 | `--primary-700` | `#3E41A0` |
+| Primary tint / subtle bg | `--primary-soft` | `#ecedfb` |
+| Primary tint 2 | `--primary-soft2` | `#d9dbf6` |
+| On-primary / text on brand | `--on-primary` | `#ffffff` |
+| Accent / Orange (CTA ثانویه، آواتار) | `--accent` | `#f0682a` |
+| Accent hover | `--accent-600` | `#db5a1f` |
+| Accent tint | `--accent-bg` | `#fdeee4` |
+
+## Colors — surface / text / border
+
+| نقش فیگما | متغیر پروژه | مقدار |
+|---|---|---|
+| Page background | `--bg` | `#fafafa` |
+| Alt background | `--bg-2` | `#f2f2f5` |
+| Card / surface | `--surface` | `#ffffff` |
+| Surface raised 2 | `--surface-2` | `#f6f8fc` |
+| Surface raised 3 | `--surface-3` | `#eef2f8` |
+| Border default | `--border` | `#e4e9f1` |
+| Border strong | `--border-2` | `#d6dde8` |
+| Text primary | `--text` | `#0f1b2e` |
+| Text secondary | `--text-2` | `#56657c` |
+| Text muted / placeholder | `--text-3` | `#8a98ad` |
+| Focus ring | `--ring` | `rgba(85,89,206,.32)` |
+
+## Colors — status
+
+| نقش | fg | bg |
+|---|---|---|
+| Success | `--success` `#15a35a` | `--success-bg` `#e6f6ed` |
+| Warning | `--warning` `#d98a09` | `--warning-bg` `#fcf2df` |
+| Danger / Error | `--danger` `#e0394a` | `--danger-bg` `#fdebed` |
+| Info | `--info` `#2b86d8` | `--info-bg` `#e7f1fb` |
+| Violet | `--violet` `#7c5cf0` | `--violet-bg` `#efeafe` |
+
+## Colors — dashboard stat cards
+
+| رنگ | bg | fg |
+|---|---|---|
+| Amber | `--stat-amber-bg` | `--stat-amber-fg` `#FFC051` |
+| Violet | `--stat-violet-bg` | `--stat-violet-fg` `#5559CE` |
+| Green | `--stat-green-bg` | `--stat-green-fg` `#009D79` |
+| Pink | `--stat-pink-bg` | `--stat-pink-fg` `#F17732` |
+
+---
+
+## Typography
+
+| فیگما | پروژه |
+|---|---|
+| Font family (fa + latin) | `--font-sans` = `"Vazirmatn", ui-sans-serif, system-ui, sans-serif` |
+| منبع فونت | `@fontsource/vazirmatn/{300,400,500,600,700,800}.css` (در `styles.css`) |
+
+اوزان موجود: 300 / 400 / 500 / 600 / 700 / 800. اندازه/line-height فیگما → کلاس‌های Tailwind (`text-sm`, `text-lg`, …).
+
+## Radius
+
+| فیگما | پروژه | مقدار |
+|---|---|---|
+| xs (chip داخلی) | `--r-xs` | `7px` |
+| sm (badge, input کوچک) | `--r-sm` | `8px` |
+| md (input, button, card عادی) | `--r` | `14px` |
+| lg (card بزرگ) | `--r-lg` | `18px` |
+| xl (modal) | `--r-xl` | `24px` |
+| full (avatar, pill, toggle) | `--r-pill` | `999px` |
+
+## Shadow / elevation
+
+| فیگما | پروژه |
+|---|---|
+| Elevation 1 (card) | `--shadow-sm` |
+| Elevation 2 (dropdown/hover) | `--shadow` |
+| Elevation 3 (modal/popover) | `--shadow-lg` |
+
+## Spacing & layout dimensions
+
+| نقش | پروژه | مقدار |
+|---|---|---|
+| Grid gap | `--gap` | `20px` (compact: `14px`) |
+| Card padding | `--card-pad` | `22px` (compact: `16px`) |
+| Table row height | `--row-h` | `56px` (compact: `46px`) |
+| Sidebar width | `--sidebar-w` | `243px` |
+| Sidebar collapsed | `--collapsed-w` | `90px` |
+| Topbar height | `--topbar-h` | `64px` |
+| Motion easing | `--ease` | `cubic-bezier(.22,.61,.36,1)` |
+
+اسپیسینگ آزاد (margin/padding داخل اجزا) → مقیاس Tailwind (`p-4`, `gap-2`, …)؛ برای ابعاد ساختاری بالا از متغیرها استفاده کن.
+
+## Theming
+
+- Dark mode: بازتعریف متغیرها زیر `[data-theme="dark"]` در `styles.css`. رنگ خام دارک ننویس؛ همان `var(--token)` خودکار سوییچ می‌شود.
+- Density: `[data-density="compact"]` مقادیر `--gap` / `--card-pad` / `--row-h` را کم می‌کند.
+- RTL: کل پنل `dir="rtl"`؛ در نگاشت left/right فیگما را به start/end منطقی تبدیل کن.
+
+---
+
+## Component mapping (فیگما → کامپوننت موجود پروژه)
+
+قبل از ساخت، از `assets/admin/components/ui/` reuse کن:
+
+| المان فیگما | کامپوننت پروژه (`assets/admin/components/ui/`) |
+|---|---|
+| Table / list با ستون | `DataTable.tsx` (sort، search، skeleton، empty، bulk) |
+| Modal / dialog | `Modal.tsx` |
+| Delete/confirm dialog | `ConfirmDialog.tsx` |
+| Page title + breadcrumb + action | `PageHeader.tsx` |
+| Stat / KPI card | `StatCard.tsx` |
+| Status pill / badge | `StatusBadge.tsx` |
+| Pagination bar | `Pagination.tsx` |
+| Searchable / async select | `SearchableSelect.tsx` |
+| Appointment status control | `AppointmentStatusDropdown.tsx` |
+| Mobile number input | `MobileInput.tsx` |
+| Price / amount input | `PriceInput.tsx` |
+| Jalali date input/picker/calendar | `PersianDateInput.tsx` / `PersianDatePicker.tsx` / `PersianCalendar.tsx` |
+| Overlay/portal مبنا | `Portal.tsx` |
+| Feature-flag gate | `FeatureGate.tsx` |
+| Captcha | `Altcha.tsx` |
+
+کامپوننت‌های ترکیبی فیچرمحور (نه generic) → `assets/admin/components/*.tsx`.
+آیکون‌ها → `@heroicons/react/24/outline` (اول موجودها؛ فقط اگر نبود از `download_assets` فیگما).
+
+---
+
+## قواعد نگاشت
+1. هر توکن فیگما را به نزدیک‌ترین متغیر بالا map کن. اگر معادل نبود → **توقف و بپرس**، توکن جدید خودسر به `styles.css` اضافه نکن.
+2. رنگ/فاصله/شعاع خام (hex/px) در کامپوننت ممنوع؛ فقط `var(--token)` یا کلاس Tailwind.
+3. اختلاف جزئی رنگ فیگما با پالت پروژه → پالت پروژه برنده است (تطبیق با design system، نه عین فیگما).
+4. منبع مقادیر همیشه `assets/admin/styles.css` است؛ این فایل خلاصه‌ی نگاشت است، نه منبع مستقل — هنگام تغییر `styles.css` این را هم به‌روز کن.