---
name: flutter-visual-regression
description: >-
  أنشئ وراجع اختبارات Golden للانحدار البصري في Flutter عبر RTL وأحجام
  النوافذ وتكبير النص والثيمات، مع تثبيت الخطوط والوقت والبيانات. استخدمها
  عند تغيير شاشة أو theme أو مكوّن بصري أو عندما يلزم منع اختلافات واجهة
  غير مقصودة.
compatibility: ZCode وClaude Code؛ إنشاء الصور محلي، واعتماد baseline يحتاج مراجعة بشرية.
---

# الانحدار البصري في Flutter

**النوع:** مهارة داخلية خاصة بالمشروع.

## قبل الكتابة

1. طبّق `AGENTS.md` ومصادر التصميم الحاكمة.
2. شغّل `npm run c:state` مرة واحدة إن لم يكن قد شُغّل.
3. اقرأ `well-android-ui` و`m3-expressive` والجزء المعني من UX spec.
4. افحص نمط اختبارات المشروع الحالي قبل إنشاء harness جديد.
5. لا تحدّث الصور المرجعية تلقائيًا لمجرد أن الاختبار فشل؛ الفرق البصري
   دليل يحتاج تفسيرًا ومراجعة.

## حتمية المشهد

ثبّت داخل test harness:

- الخطوط نفسها الموجودة في التطبيق ولا تعتمد على خط نظام المضيف.
- `locale` العربية و`textDirection.rtl`.
- حجم النافذة وdevicePixelRatio.
- Theme فاتح/داكن محدد.
- الوقت والمنطقة الزمنية والبيانات والمعرفات.
- انتهاء animations أو تعطيلها بصورة مقصودة.
- الصور والأيقونات والطلبات عبر fixtures محلية؛ لا شبكة.

أي مصدر غير حتمي يُذكر ويُعزل قبل اعتماد baseline.

## مصفوفة الصور

اختر الحالات التي تكشف خطرًا حقيقيًا، لا حاصل ضرب ضخم بلا قيمة:

- هاتف ضيق قياسي، وهاتف عريض؛ حجم كبير عند دعم adaptive layout.
- text scale 1.0 و1.3 و2.0 للشاشات الحرجة.
- فاتح وداكن عندما يدعمهما المسار.
- Loading وEmpty وError وDenied وStale وبيانات طويلة.
- مبالغ كبيرة، أسماء عربية طويلة، وهواتف/معرفات 0-9.

استعمل اختبارات منفصلة للمصفوفات الكبيرة كي يحدد الفشل المشهد بدقة.

## ما لا تثبته الصور

Golden لا يثبت:

- Semantics أو TalkBack.
- صلاحية الخادم أو صحة الحساب المالي.
- سلوك animation على جهاز.
- عدم وجود overflow خارج المشهد الملتقط.

اربطه باختبارات Widget/Unit/Device المناسبة ولا تستبدلها.

## مراجعة الفرق

عند الفشل:

1. احتفظ بصور expected/actual/diff.
2. حدّد هل السبب تغيير مقصود، انحدار، أم عدم حتمية بيئية.
3. أصلح الكود إن كان انحدارًا.
4. إذا كان التغيير مقصودًا، اعرض الفرق وسبب اعتماد baseline الجديدة.
5. لا تستخدم تحديثًا جماعيًا يخفي فروق شاشات لم تُراجع.

## التنفيذ والتحقق

شغّل ملف Golden المستهدف أولًا. بعد تعديل كود الهاتف شغّل
`flutter analyze` و`flutter test`. إن اختلفت الصور بسبب نظام التشغيل أو
renderer، سجّل البيئة ولا تعلن FAIL وظيفيًا قبل إثباته.

## توافق الوكلاء

- **ZCode وClaude Code:** يعتمدان `flutter_test` وملفات الصور نفسها.
- إن امتلك أحدهما أداة عرض صور أفضل فذلك يحسن المراجعة ولا يغير baseline.
- مهارات تصميم Claude Code الحالية تبقى محفوظة؛ هذه المهارة تحرس الانحدار
  ولا تختار الهوية البصرية من جديد.

## بوابة ما قبل التسليم

- [ ] المشهد حتمي بلا شبكة أو وقت متحرك.
- [ ] RTL والخط والثيم وحجم النافذة مثبتة.
- [ ] الحالات الحرجة ممثلة دون انفجار مصفوفة بلا هدف.
- [ ] كل baseline محدثة لها فرق مرئي مراجع وسبب.
- [ ] لم يُستعمل Golden بدل الإتاحة أو الصحة الوظيفية.
- [ ] نتائج الاختبار فعلية والبيئة مذكورة.