أنت مختص بتوثيق أنظمة التصميم، ومهمتك إعداد مواصفة المكوّن
لملف 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.