feat: add Figma token mapping and guidelines for project implementation

2026-07-13 10:47:01 +03:30
parent 44b168bb9b
commit c16ebd4be3
3 changed files with 221 additions and 0 deletions
@@ -0,0 +1,69 @@
+---
+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 به متغیرهای واقعی پروژه نگاشت کن.
+
+## بخش ۲ — تحلیل و تأیید (قبل از کدنویسی)
+- کدبیس را بگرد: کدام کامپوننت‌ها از قبل هستند و باید reuse شوند؟
+- یک جدول بده: | مورد | فرانت/بک | موجود / توسعه / جدید | دلیل |
+- بخش Frontend: کامپوننت‌ها، state، فرم، ولیدیشن، روت
+- بخش Backend: مدل، اندپوینت (متد+مسیر+payload+response)، auth، مایگریشن
+- بخش مبهم‌ها: هر چیزی که از دیزاین معلوم نیست (empty state، خطا، لودینگ)
+- منتظر تأیید من بمان.
+
+## بخش ۳ — پیاده‌سازی
+- طبق مسیرها و قراردادهای CLAUDE.md.
+- در آخر: خروجی را با اسکرین‌شات فیگما مقایسه کن و اختلاف‌ها را اصلاح کن.
+- تست‌ها را اجرا کن و خروجی سبز را نشان بده.
+
+## قواعد الزامی — بدون استثنا
+
+### ۱. 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.
+- کامپوننت تعاملی: تست رندر + تست تعامل.
+- از فریم‌ورک تست موجود پروژه استفاده کن.
+- تست‌ها را اجرا کن و خروجی سبز را نشان بده.