توثيق مواصفات المكوّنات

أنت مختص بتوثيق أنظمة التصميم، ومهمتك إعداد مواصفة المكوّن لملف CLAUDE.md. سيستخدم هذا التوثيق مساعدو البرمجة بالذكاء الاصطناعي (Claude, Cursor, Copilot) لتوليد كود واجهات موحّد ومتّسق. ## السياق - **نظام رموز التصميم (Tokens):** [الصق ناتج المرحلة 2 أو أشر إليه] - **المكوّن المطلوب توثيقه:** [اسم المكوّن، أو كل المكوّنات من قائمة الحصر] - **إطار العمل:** [Next.js + React + Tailwind / إلخ] ## لكل مكوّن، وثّق ما يلي: ### 1. نظرة عامة - اسم المكوّن بصيغة PascalCase - وصف مختصر من سطر واحد - التصنيف (Navigation / Input / Feedback / Layout / Data Display) ### 2. بنية المكوّن - اذكر كل جزء مرئي في المكوّن (مثال: Button = container + label + icon-left + icon-right) - وضّح الأجزاء الاختيارية والإلزامية - قواعد التداخل: ما الذي يمكن أو لا يمكن وضعه داخل هذا المكوّن ### 3. مواصفة الخصائص (Props) لكل خاصية (prop): - الاسم، والنوع، والقيمة الافتراضية، وهل هي إلزامية أو اختيارية - القيم المسموح بها إذا كانت من نوع enum - وصف مختصر لما تتحكم فيه بصريًا - مثال استخدام ### 4. التنويعات المرئية (Variants) - تنويعات الحجم مع قيم رموز التصميم الدقيقة (padding, font-size, height) - تنويعات الألوان مع مراجع رموز التصميم الدقيقة - حالات المكوّن: default, hover, active, focus, disabled, loading, error - لكل حالة: حدّد رموز التصميم التي تتغير والقيم التي تتغير إليها ### 5. خريطة استهلاك رموز التصميم (Tokens) Component: Button ├── background → button-bg- → color-brand- ├── text-color → button-text- → color-white ├── padding-x → button-padding-x- → spacing-{n} ├── padding-y → button-padding-y- → spacing-{n} ├── border-radius → button-radius → radius-md ├── font-size → button-font- → font-size-{n} ├── font-weight → button-font-weight → font-weight-semibold └── transition → motion-duration-fast + motion-ease-default ### 6. إرشادات الاستخدام - متى يُستخدم المكوّن، ومتى لا يُستخدم، مع اقتراح بدائل مناسبة - الحد الأعلى لعدد مرات ظهوره داخل نفس الشاشة/القسم، مثل: «زر إجراء رئيسي (Primary CTA) واحد فقط لكل قسم» - إرشادات المحتوى: طول النص، أسلوب الصياغة، استخدام الأيقونات، وحالة الأحرف عند الحاجة ### 7. إمكانية الوصول (Accessibility) - سمات ARIA المطلوبة - نمط التفاعل باستخدام لوحة المفاتيح - قواعد إدارة التركيز (Focus) - سلوك قارئ الشاشة - الحد الأدنى لنسب التباين التي تحققها رموز التصميم الافتراضية ### 8. مثال كود قدّم مثال كود جاهزًا للنسخ واللصق باستخدام أنماط الكود الفعلية في المشروع، مثل مسارات الاستيراد، اصطلاحات className، وأي أنماط معتمدة في قاعدة الكود. ## تنسيق الناتج بتنسيق Markdown، ومنظّم بعناوين واضحة لكل قسم. سيُدرج الناتج مباشرةً داخل ملف CLAUDE.md.