ملاحظات تسليم التصميم — للذكاء الاصطناعي ومقروءة للمطورين

1# ملاحظات تسليم التصميم — للذكاء الاصطناعي ومقروءة للمطورين
2
3### مستند تسليم منظّم ومهيّأ لوكلاء تنفيذ البرمجة بالذكاء الاصطناعي (Claude Code, Cursor, Copilot)، مع بقائه واضحًا للمطورين البشر
4
5---
6
7## عن هذا الموجّه
8
9**الوصف:** ينشئ مستند تسليم تصميم يعمل كتعليمات تنفيذ مباشرة لوكلاء البرمجة بالذكاء الاصطناعي. بدلًا من ملاحظات التسليم التقليدية التي تكتفي بوصف الانطباع المطلوب من التصميم، يقدّم هذا المستند مواصفات قابلة للمعالجة آليًا من دون أي غموض. كل قيمة صريحة، كل حالة معرّفة، وكل حالة حدّية لها قاعدة واضحة. المستند منظّم بحيث يستطيع وكيل الذكاء الاصطناعي قراءته من الأعلى إلى الأسفل والتنفيذ من دون الحاجة إلى أسئلة توضيحية — وفي الوقت نفسه يستطيع المطور البشري قراءته بسلاسة.
10
11**الفلسفة الأساسية:** إذا قرأ الذكاء الاصطناعي هذا المستند واضطر إلى تخمين أي شيء، فالمستند لم ينجح.
12
13**متى تستخدمه:** بعد اعتماد التصميم النهائي وقبل بدء التنفيذ. هذا المستند يغني عن تسليم Figma، وملفات مواصفات التصميم PDF، ومحادثات مثل «خلّه يطلع مثل التصميم».
14
15**من يقرأه:**
16- الأساسي: وكلاء البرمجة بالذكاء الاصطناعي (Claude Code, Cursor, Copilot، وغيرها)
17- الثانوي: المطورون البشر عند مراجعة مخرجات الذكاء الاصطناعي أو تصحيحها
18- الثالث: أنت بصفتك المصمم، عند التحقق من مطابقة التنفيذ للنية التصميمية
19
20**العلاقة مع CLAUDE.md:** يفترض هذا المستند وجود ملف نظام تصميم باسم CLAUDE.md في جذر المشروع. تشير ملاحظات التسليم إلى الرموز tokens الموجودة في CLAUDE.md ولا تعيد تعريفها. إذا لم يكن ملف CLAUDE.md موجودًا، شغّل أولًا موجّهات استخراج نظام التصميم.
21
22---
23
24## الموجّه
25
26```
27أنت مهندس أنظمة تصميم تكتب مواصفات تنفيذ.
28ستُقرأ مخرجاتك بشكل أساسي من وكلاء برمجة بالذكاء الاصطناعي (Claude Code, Cursor)
29وبشكل ثانوي من مطورين بشر.
30
31يجب أن تتبع كتابتك قاعدة واحدة مطلقة:
32**إذا اضطر القارئ إلى التخمين أو الاستنتاج أو افتراض أي شيء، فقد فشلت.**
33
34كل قيمة يجب أن تكون صريحة. كل حالة يجب أن تكون معرّفة. كل حالة حدّية
35يجب أن تكون لها قاعدة واضحة. لا تستخدم عبارات مثل «حسب المناسب» أو «تقريبًا» أو «مشابه لـ».
36
37## سياق المشروع
38- **المشروع:** 
39- **إطار العمل:** [Next.js 14+ / React / إلخ]
40- **أسلوب التنسيق:** [Tailwind 3.x / CSS Modules / إلخ]
41- **مكتبة المكونات:** [shadcn/ui / custom / إلخ]
42- **موقع CLAUDE.md:** [المسار — أو «لم يُنشأ بعد»]
43- **مصدر التصميم:** [كود مرفوع / رابط مباشر / لقطات شاشة]
44- **الصفحات المطلوب توثيقها:** [كل الصفحات / صفحات محددة]
45
46## قواعد تنسيق المخرجات
47
48قبل كتابة أي مواصفات، اتبع قواعد التنسيق التالية بدقة:
49
501. **القيم دائمًا جاهزة للاستخدام في الكود.**
51   خطأ: «مسافة متوسطة»
52   صحيح: `p-6` (24px)
53
542. **الألوان دائمًا تكون مرجع token + قيمة hex احتياطية.**
55   خطأ: «أزرق الهوية»
56   صحيح: `text-brand-500` (#2563EB) — من رموز CLAUDE.md
57
583. **الأحجام دائمًا تكون بنظام الوحدات المستخدم في المشروع.**
59   إذا كان Tailwind: استخدم class من Tailwind كقيمة أساسية، وpx كملاحظة
60   إذا كان CSS: استخدم rem كقيمة أساسية، وpx كملاحظة
61   خطأ: «كبّره على desktop»
62   صحيح: `text-lg` (18px) عند ≥768px، و`text-base` (16px) أقل من ذلك
63
644. **الشروط تستخدم if/else بشكل صريح، وليس «حسب الحاجة».**
65   خطأ: «اعرض حالة التحميل عند الحاجة»
66   صحيح: if data fetch takes >300ms, show skeleton. If fetch fails, show error state. If data returns empty array, show empty state.
67
685. **مسارات الملفات يجب أن تكون صريحة.**
69   خطأ: «أنشئ مكون زر»
70   صحيح: create `src/components/ui/Button.tsx`
71
726. **كل خاصية بصرية يجب أن تُذكر، ولا تعتمد على الافتراض أو الوراثة غير المصرّح بها.**
73   حتى لو كانت «واضحة» — اذكرها. وكلاء الذكاء الاصطناعي لا يملكون سياقًا بصريًا.
74
75---
76
77## هيكل المستند
78
79أنشئ مستند التسليم بالأقسام التالية:
80
81### SECTION 1: IMPLEMENTATION MAP
82
83جدول مرتب حسب الأولوية لكل ما يجب بناؤه.
84يجب على وكلاء الذكاء الاصطناعي التنفيذ بهذا الترتيب حتى تُحل الاعتماديات بشكل صحيح.
85
86| Order | Component/Section | File Path | Dependencies | Complexity | Notes |
87|-------|------------------|-----------|-------------|-----------|-------|
88| 1 | إعداد رموز التصميم | `tailwind.config.ts` | None | Low | يجب أن يكون أولًا — كل المكونات الأخرى تعتمد على هذه القيم |
89| 2 | مكونات النصوص | `src/components/ui/Text.tsx` | Tokens | Low | متغيرات Heading, Body, Caption, Label |
90| 3 | الزر | `src/components/ui/Button.tsx` | Tokens, Typography | Medium | 3 variants × 3 sizes × 6 states |
91| ... | ... | ... | ... | ... | ... |
92
93القواعد:
94- لا يجوز لأي عنصر أن يعتمد على مكون يأتي بعده في الجدول
95- Complexity = عدد المتغيرات × الحالات داخل المكون
96- Notes = أي أمر غير بديهي في التنفيذ
97
98---
99
100### SECTION 2: GLOBAL SPECIFICATIONS
101
102هذه المواصفات تُطبق في كل مكان. يجب على وكيل الذكاء الاصطناعي إعدادها قبل بناء أي مكونات.
103
104#### 2.1 Breakpoints
105عرّف حدود السلوك بدقة:
106
107```
108BREAKPOINTS {
109  mobile:  0px    — 767px
110  tablet:  768px  — 1023px
111  desktop: 1024px — 1279px
112  wide:    1280px — ∞
113}
114```
115
116لكل breakpoint، اذكر:
117- أقصى عرض للحاوية والـ padding
118- حجم الخط الأساسي
119- معامل المسافات العام إذا كان يتغير
120- وضع التنقل Navigation mode (hamburger / horizontal / إلخ)
121
122#### 2.2 Transition Defaults
123```
124TRANSITIONS {
125  default:    duration-200 ease-out
126  slow:       duration-300 ease-in-out
127  spring:     duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)
128  none:       duration-0
129}
130
131RULE: كل عنصر تفاعلي يستخدم `default` ما لم يحدد هذا المستند خلاف ذلك.
132RULE: الانتقالات تطبق على: background-color, color, border-color,
133      opacity, transform, box-shadow. لا تطبق أبدًا على: width, height, padding,
134      margin لأنها تسبب إعادة حساب التخطيط.
135```
136
137#### 2.3 Z-Index Scale
138```
139Z-INDEX {
140  base:       0
141  dropdown:   10
142  sticky:     20
143  overlay:    30
144  modal:      40
145  toast:      50
146  tooltip:    60
147}
148
149RULE: لا تستخدم أي قيمة z-index خارج هذا السلم. نهائيًا.
150```
151
152#### 2.4 Focus Style
153```
154FOCUS {
155  style:      ring-2 ring-offset-2 ring-brand-500
156  applies-to: كل عنصر تفاعلي (buttons, links, inputs, selects, checkboxes)
157  visible:    فقط عند التنقل بلوحة المفاتيح (استخدم focus-visible، وليس focus)
158}
159```
160
161---
162
163### SECTION 3: PAGE SPECIFICATIONS
164
165لكل صفحة، قدّم مواصفات تنفيذ كاملة.
166
167#### Page: 
168**Route:** `/exact-route-path`
169**Layout:** 
170**Data requirements:** [ما البيانات التي تحتاجها هذه الصفحة، ومن أين تأتي]
171
172##### Page Structure (من الأعلى إلى الأسفل)
173
174```
175PAGE STRUCTURE: 
176├── Section: Hero
177│   ├── Component: Heading (h1)
178│   ├── Component: Subheading (p)
179│   ├── Component: CTA Button (primary, lg)
180│   └── Component: HeroImage
181├── Section: Features
182│   ├── Component: SectionHeading (h2)
183│   └── Component: FeatureCard × 3 (grid)
184├── Section: Testimonials
185│   └── Component: TestimonialSlider
186└── Section: CTA
187    ├── Component: Heading (h2)
188    └── Component: CTA Button (primary, lg)
189```
190
191##### مواصفات كل قسم
192
193لكل قسم:
194
195****
196
197```
198LAYOUT {
199  container:    max-w-[1280px] mx-auto px-6 (mobile: px-4)
200  direction:    flex-col (mobile) → flex-row (desktop)
201  gap:          gap-8 (32px)
202  padding:      py-16 (64px) (mobile: py-10)
203  background:   bg-white
204}
205
206CONTENT {
207  heading {
208    text:       ""
209    element:    h2
210    class:      text-3xl font-bold text-gray-900 (mobile: text-2xl)
211    max-width:  max-w-[640px]
212  }
213  body {
214    text:       ""
215    class:      text-lg text-gray-600 leading-relaxed (mobile: text-base)
216    max-width:  max-w-[540px]
217  }
218}
219
220GRID (if applicable) {
221  columns:      grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1)
222  gap:          gap-6 (24px)
223  items:        
224  alignment:    items-start
225}
226
227ANIMATION (if applicable) {
228  type:         fade-up on scroll
229  trigger:      when section enters viewport (threshold: 0.2)
230  stagger:      each child delays 100ms after previous
231  duration:     duration-500
232  easing:       ease-out
233  runs:         once (do not re-trigger on scroll up)
234}
235```
236
237---
238
239### SECTION 4: COMPONENT SPECIFICATIONS
240
241لكل مكون، قدّم عقد تنفيذ كاملًا وواضحًا.
242
243#### Component: 
244**File:** `src/components//.tsx`
245**Purpose:** [جملة واحدة — وظيفة هذا المكون]
246
247##### Props Interface
248```typescript
249interface Props {
250  variant: 'primary' | 'secondary' | 'ghost'     // visual style
251  size: 'sm' | 'md' | 'lg'                        // dimensions
252  disabled?: boolean                                // default: false
253  loading?: boolean                                 // default: false
254  icon?: React.ReactNode                           // optional leading icon
255  children: React.ReactNode                         // label content
256  onClick?: () => void                              // click handler
257}
258```
259
260##### Variant × Size Matrix
261عرّف القيم الدقيقة لكل تركيبة:
262
263```
264VARIANT: primary
265  SIZE: sm
266    height:           h-8 (32px)
267    padding:          px-3 (12px)
268    font:             text-sm font-medium (14px)
269    background:       bg-brand-500 (#2563EB)
270    text:             text-white (#FFFFFF)
271    border:           none
272    border-radius:    rounded-md (6px)
273    shadow:           none
274
275  SIZE: md
276    height:           h-10 (40px)
277    padding:          px-4 (16px)
278    font:             text-sm font-medium (14px)
279    background:       bg-brand-500 (#2563EB)
280    text:             text-white (#FFFFFF)
281    border:           none
282    border-radius:    rounded-lg (8px)
283    shadow:           shadow-sm
284
285  SIZE: lg
286    height:           h-12 (48px)
287    padding:          px-6 (24px)
288    font:             text-base font-semibold (16px)
289    background:       bg-brand-500 (#2563EB)
290    text:             text-white (#FFFFFF)
291    border:           none
292    border-radius:    rounded-lg (8px)
293    shadow:           shadow-sm
294
295VARIANT: secondary
296  [نفس الهيكل، بقيم مختلفة]
297
298VARIANT: ghost
299  [نفس الهيكل، بقيم مختلفة]
300```
301
302##### State Specifications
303كل حالة يجب تعريفها لكل variant:
304
305```
306STATES (تطبق على كل variants ما لم يذكر خلاف ذلك):
307
308  hover {
309    background:      — أغمق بدرجة واحدة من الحالة الافتراضية
310    transform:      none (لا تستخدم scale/translate عند hover)
311    shadow:         
312    cursor:         pointer
313    transition:     default (duration-200 ease-out)
314  }
315
316  active {
317    background:      — أغمق بدرجتين من الحالة الافتراضية
318    transform:      scale-[0.98]
319    transition:     duration-75
320  }
321
322  focus-visible {
323    ring:           ring-2 ring-offset-2 ring-brand-500
324    all other:      نفس الحالة الافتراضية
325  }
326
327  disabled {
328    opacity:        opacity-50
329    cursor:         not-allowed
330    pointer-events: none
331    ALL hover/active/focus states: لا تطبق
332  }
333
334  loading {
335    content:        استبدل children بـ spinner (16px, animate-spin)
336    width:          حافظ على نفس عرض حالة عدم التحميل (لتجنب layout shift)
337    pointer-events: none
338    opacity:        opacity-80
339  }
340```
341
342##### Icon Behavior
343```
344ICON RULES {
345  position:       قبل نص الزر دائمًا (leading). في واجهات RTL تظهر يمين النص ما لم تحدد المواصفة خلاف ذلك
346  size:           16px (sm), 16px (md), 20px (lg)
347  gap:            gap-1.5 (sm), gap-2 (md), gap-2 (lg)
348  color:          يرث لون النص (currentColor)
349  when loading:   تختفي الأيقونة، ويأخذ الـ spinner مكانها
350  icon-only:      إذا لم يوجد children، يصبح المكون مربعًا (width = height)
351                  أضف متطلب aria-label prop
352}
353```
354
355---
356
357### SECTION 5: INTERACTION FLOWS
358
359لكل مسار مستخدم، قدّم خطوات تنفيذ واضحة:
360
361#### Flow: [اسم المسار، مثل «إنشاء حساب مستخدم»]
362```
363TRIGGER:     المستخدم يضغط زر «إنشاء حساب» في الهيدر
364
365STEP 1:      يفتح Modal
366             animation:   fade-in (opacity 0→1, duration-200)
367             backdrop:    bg-black/50، الضغط خارج النافذة يغلق الـ modal
368             focus:       احصر التركيز داخل الـ modal، واجعل أول input يأخذ التركيز تلقائيًا
369             body:        scroll-lock (منع تمرير الخلفية)
370
371STEP 2:      المستخدم يعبئ النموذج
372             fields:      
373             validation:  on blur (وليس on change — لتقليل الإزعاج)
374             
375             field: email {
376               type:       email
377               required:   true
378               validate:   regex pattern + "must contain @ and domain"
379               error:      "البريد الإلكتروني غير صحيح — تأكد من كتابته بدون أخطاء"
380               success:    تظهر أيقونة صح خضراء (fade-in, duration-150)
381             }
382             
383             field: password {
384               type:       password (مع زر إظهار/إخفاء)
385               required:   true
386               validate:   min 8 chars, 1 uppercase, 1 number
387               error:      اعرض قائمة تحقق بالمتطلبات، وميّز غير المكتمل منها
388               strength:   اعرض مؤشر قوة كلمة المرور (ضعيفة/متوسطة/قوية)
389             }
390
391STEP 3:      المستخدم يرسل النموذج
392             button:      يعرض حالة التحميل (راجع مواصفات مكون Button)
393             request:     POST /api/auth/signup
394             duration:    المتوقع 1-3 ثوانٍ
395
396STEP 4a:     نجاح
397             modal:       يتحول المحتوى إلى رسالة نجاح (crossfade, duration-200)
398             message:     "تم إنشاء الحساب! راجع بريدك الإلكتروني للتفعيل."
399             action:      زر "حسنًا" يغلق الـ modal
400             redirect:    بعد الإغلاق، وجّه المستخدم إلى /dashboard
401             toast:       none (الـ modal هو رسالة التأكيد)
402
403STEP 4b:     خطأ — البريد الإلكتروني مستخدم مسبقًا
404             field:       حقل email يعرض حالة الخطأ
405             message:     "هذا البريد عليه حساب مسجل — هل ترغب بتسجيل الدخول بدلًا من ذلك؟"
406             action:      رابط "تسجيل الدخول" يبدّل الـ modal إلى نموذج تسجيل الدخول
407             button:      يرجع للحالة الافتراضية (ليس loading)
408
409STEP 4c:     خطأ — فشل الشبكة
410             display:     error banner أعلى الـ modal (ليس toast)
411             message:     "حدث خلل من طرفنا. حاول مرة أخرى؟"
412             action:      زر "إعادة المحاولة" يعيد الإرسال
413             button:      يرجع للحالة الافتراضية
414
415STEP 4d:     خطأ — تم تجاوز الحد المسموح للمحاولات
416             display:     error banner
417             message:     "محاولات كثيرة. انتظر 60 ثانية ثم حاول مرة أخرى."
418             button:      disabled لمدة 60 ثانية مع عداد ظاهر
419```
420
421---
422
423### SECTION 6: RESPONSIVE BEHAVIOR RULES
424
425لا تكتفِ بوصف ما يتغير — حدّد القواعد الدقيقة:
426
427```
428RESPONSIVE RULES:
429
430Rule 1: Navigation
431  ≥1024px:    horizontal nav، كل العناصر ظاهرة
432  <1024px:    hamburger icon، drawer ينزلق من اليمين
433              drawer-width: 80vw (max-w-[320px])
434              animation: translate-x (duration-300 ease-out)
435              backdrop: bg-black/50، الضغط خارج النافذة يغلقها
436
437Rule 2: Grid Sections
438  ≥1024px:    grid-cols-3
439  768-1023px: grid-cols-2 (العنصر الأخير يمتد لكامل العرض إذا كان العدد فرديًا)
440  <768px:     grid-cols-1
441
442Rule 3: Hero Section
443  ≥1024px:    عمودان — في RTL: النص يمين والصورة يسار، وفي LTR: النص يسار والصورة يمين — تقسيم 55/45
444  <1024px:    عمود واحد (النص أعلى، الصورة أسفل)
445              image max-height: 400px, object-cover
446
447Rule 4: Typography Scaling
448  ≥1024px:    h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base
449  <1024px:    h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base
450
451Rule 5: Spacing Scaling
452  ≥1024px:    section-padding: py-16, container-padding: px-8
453  768-1023px: section-padding: py-12, container-padding: px-6
454  <768px:     section-padding: py-10, container-padding: px-4
455
456Rule 6: Touch Targets
457  <1024px:    كل العناصر التفاعلية يجب أن يكون hit area لها على الأقل 44×44px
458              إذا كان الحجم البصري أقل من 44px، استخدم padding غير مرئي للوصول إلى 44px
459
460Rule 7: Images
461  all images: استخدم next/image مع responsive sizes prop
462  hero:       sizes="(max-width: 1024px) 100vw, 50vw"
463  grid items: sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
464```
465
466---
467
468### SECTION 7: EDGE CASES & BOUNDARY CONDITIONS
469
470هذا القسم يمنع مشاكل «طيب وش يصير إذا...؟»:
471
472```
473EDGE CASES:
474
475Text Overflow {
476  headings:     حد أقصى سطران، بعدها truncate مع text-ellipsis (أضف title attr للنص الكامل)
477  body text:    اتركه يلتف بشكل طبيعي، بدون truncation
478  button labels: سطر واحد فقط، حد أقصى 30 حرفًا، بدون truncation (قيد تصميمي)
479  nav items:    سطر واحد، truncate إذا تجاوز 16 حرفًا على الجوال
480  table cells:  truncate مع tooltip عند hover
481}
482
483Empty States {
484  lists/grids with 0 items: اعرض مكون 
485    - illustration: 
486    - heading: ""
487    - body: ""
488    - CTA: "" → 
489  
490  user avatar missing: اعرض الأحرف الأولى على خلفية ملوّنة
491    - background: ولّد اللون من hash اسم المستخدم (deterministic)
492    - initials: أول حرف من الاسم الأول + اسم العائلة، uppercase
493    - font: text-sm font-medium text-white
494  
495  image fails to load: اعرض placeholder رمادي مع أيقونة صورة
496    - background: bg-gray-100
497    - icon: ImageOff from lucide-react, text-gray-400, 24px
498}
499
500Loading States {
501  page load:      full-page skeleton (ليس spinner)
502  component load: component-level skeleton مطابق لأبعاد المحتوى النهائي
503  button action:  inline spinner داخل الزر (راجع مواصفات Button)
504  infinite list:  skeleton row × 3 في الأسفل أثناء جلب الصفحة التالية
505  
506  skeleton style: bg-gray-200 rounded animate-pulse
507  skeleton rule:  شكل skeleton يجب أن يطابق شكل المحتوى النهائي
508                  (rectangle للنص، circle للأفاتار، rounded-lg للبطاقات)
509}
510
511Error States {
512  API error (500):     اعرض inline error banner مع زر retry
513  Network error:       اعرض banner أعلى الصفحة "يبدو أنك غير متصل بالإنترنت" (يختفي تلقائيًا عند عودة الاتصال)
514  404 content:         اعرض مكون 404 مخصصًا (وليس الافتراضي من Next.js)
515  Permission denied:   وجّه إلى /login مع return URL param
516  Form validation:     inline لكل حقل (راجع flow specs)، لا تستخدم alert() نهائيًا
517}
518
519Data Extremes {
520  username 1 character:   اعرضه بشكل طبيعي
521  username 50 characters: اختصره إلى 20 حرفًا في nav، واعرضه كاملًا في profile
522  price 0.00 ر.س:         اعرض "مجاني"
523  price 999,999.99 ر.س:   تأكد أن التخطيط لا ينكسر (اختبر الرقم بعد التنسيق)
524  list with 1 item:       نفس تخطيط العناصر المتعددة (بدون حالة خاصة)
525  list with 500 items:    paginate عند 20 عنصرًا، واعرض زر "تحميل المزيد"
526  date today:             اعرض "اليوم" وليس التاريخ
527  date this year:         اعرض "13 مارس" وليس "13 مارس 2026"
528  date other year:        اعرض "13 مارس 2025"
529}
530```
531
532---
533
534### SECTION 8: IMPLEMENTATION VERIFICATION CHECKLIST
535
536بعد التنفيذ، يجب على وكيل الذكاء الاصطناعي أو المطور البشري التحقق من التالي:
537
538```
539VERIFICATION:
540
541□ كل مكون يطابق variant × size matrix بدقة
542□ كل حالة (hover, active, focus, disabled, loading) تعمل
543□ ترتيب Tab يتبع الترتيب البصري في كل الصفحات
544□ حلقة focus-visible تظهر عند التنقل بلوحة المفاتيح، وليس عند النقر بالماوس
545□ كل transitions تستخدم المدة والـ easing المحددين (وليس الافتراضي من المتصفح)
546□ لا يوجد layout shift أثناء تحميل الصفحة (افحص CLS)
547□ حالات skeleton تطابق أبعاد المحتوى النهائي
548□ كل الحالات الحدّية من Section 7 تم التعامل معها
549□ touch targets ≥ 44×44px عند breakpoints الجوال
550□ لا يوجد horizontal scroll في أي breakpoint
551□ كل الصور تستخدم next/image مع sizes prop صحيح
552□ قيم z-index تستخدم السلم المحدد فقط
553□ حالات الخطأ تظهر بشكل صحيح (اختبر باستخدام network throttle)
554□ حالات الفراغ تظهر بشكل صحيح (اختبر ببيانات فارغة)
555□ اختصار النص يعمل عند أطوال الحدود المحددة
556□ رموز الوضع الداكن Dark mode tokens، إن وجدت، كلها مربوطة بشكل صحيح
557```
558
559---
560
561## كيف يجب على وكيل الذكاء الاصطناعي استخدام هذا المستند
562
563أدرج هذه التعليمات في أعلى مستند التسليم الناتج
564حتى يعرف وكيل التنفيذ كيف يتعامل معه:
565
566```
567INSTRUCTIONS FOR AI IMPLEMENTATION AGENT:
568
5691. اقرأ هذا المستند كاملًا قبل كتابة أي كود.
5702. نفّذ بالترتيب المحدد في SECTION 1 (Implementation Map).
5713. ارجع إلى CLAUDE.md لقيم tokens. إذا كان هناك token مذكور هنا
572   وغير موجود في CLAUDE.md، نبّه عليه واستخدم قيمة fallback المقدمة.
5734. كل قيمة في هذا المستند مقصودة. لا تستبدلها بقيم «قريبة بما يكفي».
574   `gap-6` تعني `gap-6`، وليس `gap-5`.
5755. كل حالة يجب تنفيذها. إذا لم تُذكر حالة لمكون معين، فهذا نقص في المواصفة —
576   نبّه عليه ولا تخمّن.
5776. بعد تنفيذ كل مكون، راجع state matrix الخاصة به
578   وتأكد أن كل الحالات تعمل قبل الانتقال للمكون التالي.
5797. عند وجود غموض، اختر التفسير الأكثر صراحة.
580   إذا بقي الغموض، أضف تعليق TODO: "// HANDOFF-AMBIGUITY: [description]"
581```
582```
583
584---
585
586## ملاحظات التخصيص
587
588**إذا كنت لا تستخدم Tailwind:** استبدل كل مراجع class الخاصة بـ Tailwind في الموجّه بما يقابلها في نظامك. يبقى الهيكل كما هو — الذي يتغير فقط هو صيغة القيم. قل لـ Claude: `Use CSS custom properties as primary, px values as annotations.`
589
590**إذا كنت تسلّم لأداة ذكاء اصطناعي محددة:** أضف ملاحظات خاصة بالأداة. مثال لـ Cursor: `Generate implementation as step-by-step edits to existing files, not full file rewrites.` ومثال لـ Claude Code: `Create each component as a complete file, test it, then move to the next.`
591
592**إذا لم يكن CLAUDE.md موجودًا بعد:** اطلب من الموجّه أن ينشئ قسم tokens بسيطًا في أعلى مستند التسليم يغطي فقط الرموز المطلوبة لهذا التسليم المحدد. لن يكون نظام تصميم كاملًا، لكنه يمنع استخدام قيم hardcoded.
593
594**للمشاريع متعددة الصفحات:** شغّل الموجّه مرة لكل صفحة، لكن أدرج Section 1 (Implementation Map) وSection 2 (Global Specs) في التشغيل الأول فقط. الصفحات اللاحقة تشير إلى المواصفات العامة نفسها.