قوة اختبار إمكانية الوصول

---
name: accessibility-testing-superpower
description: |
  يقوم بإجراء تدقيقات الامتثال لمعايير WCAG ومعالجة مشاكل الوصول لتطبيقات الويب.
  استخدمه عندما: 1) تدقيق واجهة المستخدم للامتثال لمعايير WCAG 2.1/2.2 2) إصلاح مشاكل قارئ الشاشة أو التنقل بلوحة المفاتيح 3) تطبيق أنماط ARIA بشكل صحيح 4) مراجعة تباين الألوان وإمكانية الوصول البصري 5) إنشاء نماذج أو مكونات تفاعلية يمكن الوصول إليها.
---

# سير عمل اختبار إمكانية الوصول

## التكوين

- **مستوى WCAG**: ${wcag_level:AA}
- **المكون قيد الاختبار**: ${component_name:Page}
- **معيار الامتثال**: ${compliance_standard:WCAG 2.1}
- **الحد الأدنى لدرجة Lighthouse**: ${lighthouse_score:90}
- **قارئ الشاشة الأساسي**: ${screen_reader:NVDA}
- **إطار عمل الاختبار**: ${test_framework:jest-axe}

## شجرة قرار التدقيق

```
تم استلام طلب إمكانية الوصول
|
+-- مكون/صفحة جديدة؟
|   +-- قم بتشغيل الفحص الآلي أولاً (axe-core, Lighthouse)
|   +-- اختبار التنقل بلوحة المفاتيح
|   +-- التحقق من إعلانات قارئ الشاشة
|   +-- التحقق من تباين الألوان
|
+-- انتهاك موجود للإصلاح؟
|   +-- تحديد معيار نجاح WCAG
|   +-- التحقق مما إذا كان HTML الدلالي يحل المشكلة
|   +-- تطبيق ARIA فقط عندما يكون HTML غير كافٍ
|   +-- التحقق من الإصلاح باستخدام التقنيات المساعدة
|
+-- تدقيق الامتثال؟
    +-- فحص آلي (يكشف حوالي 30% من المشاكل)
    +-- قائمة تحقق الاختبار اليدوي
    +-- توثيق الانتهاكات حسب الخطورة
    +-- إنشاء خارطة طريق للمعالجة
```

## مرجع WCAG السريع

### تصنيف الخطورة

| الخطورة | التأثير | أمثلة | الجدول الزمني للإصلاح |
|----------|--------|----------|--------------|
| حرج | يمنع الوصول بالكامل | لا يوجد تركيز بلوحة المفاتيح، أزرار فارغة، alt مفقود على الصور الوظيفية | فوري |
| خطير | حواجز رئيسية | تباين ضعيف، تسميات نماذج مفقودة، لا توجد روابط تخطي | خلال السبرنت |
| معتدل | صعب ولكن قابل للاستخدام | تنقل غير متناسق، رسائل خطأ غير واضحة | الإصدار التالي |
| ثانوي | إزعاج | نص بديل زائد عن الحاجة، مشاكل طفيفة في ترتيب العناوين | قائمة المهام المتأخرة |

### الانتهاكات الشائعة والإصلاحات

**اسم يمكن الوصول إليه مفقود**
```html
<!-- انتهاك -->
<button><svg>...</svg></button>

<!-- إصلاح: aria-label -->
<button aria-label="Close dialog"><svg>...</svg></button>

<!-- إصلاح: نص مخفي بصريًا -->
<button><span class="sr-only">Close dialog</span><svg>...</svg></button>
```

**ربط تسمية النموذج**
```html
<!-- انتهاك -->
<label>Email</label>
<input type="email">

<!-- إصلاح: ربط صريح -->
<label for="email">Email</label>
<input type="email" id="email">

<!-- إصلاح: ربط ضمني -->
<label>Email <input type="email"></label>
```

**فشل تباين الألوان**
```
الحد الأدنى للنسب (WCAG ${wcag_level:AA}):
- النص العادي (<${large_text_size:18}px أو <${bold_text_size:14}px غامق): ${contrast_ratio_normal:4.5}:1
- النص الكبير (>=${large_text_size:18}px أو >=${bold_text_size:14}px غامق): ${contrast_ratio_large:3}:1
- مكونات واجهة المستخدم والرسومات: 3:1

الأدوات: WebAIM Contrast Checker، أدوات مطوري المتصفح
```

**رؤية التركيز**
```css
/* لا تفعل هذا أبدًا بدون بديل */
:focus { outline: none; }

/* تركيز مخصص صحيح */
:focus-visible {
  outline: ${focus_outline_width:2}px solid ${focus_outline_color:#005fcc};
  outline-offset: ${focus_outline_offset:2}px;
}
```

## إطار عمل قرار ARIA

```
هل تحتاج إلى نقل معلومات إلى التقنيات المساعدة؟
|
+-- هل يمكن لـ HTML الدلالي القيام بذلك؟
|   +-- نعم: استخدم HTML (<button>, <nav>, <main>, <article>)
|   +-- لا: تابع إلى ARIA
|
+-- ما نوع ARIA المطلوب؟
    +-- الدور: ما هو هذا العنصر؟ (role="dialog", role="tab")
    +-- الحالة: ما هي الحالة؟ (aria-expanded, aria-checked)
    +-- الخاصية: ما هي العلاقة؟ (aria-labelledby, aria-describedby)
    +-- المنطقة الحية: محتوى ديناميكي؟ (aria-live="${aria_live_mode:polite}")
```

### أنماط ARIA للمكونات الشائعة

**الإفصاح (إظهار/إخفاء)**
```html
<button aria-expanded="false" aria-controls="content-1">
  Show details
</button>
<div id="content-1" hidden>
  Content here
</div>
```

**واجهة التبويبات**
```html
<div role="tablist" aria-label="${component_name:Settings}">
  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
    General
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1">
    Privacy
  </button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>
```

**مربع حوار مشروط (Modal dialog)**
```html
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm action</h2>
  <p>Are you sure you want to proceed?</p>
  <button>Cancel</button>
  <button>Confirm</button>
</div>
```

## قائمة تحقق التنقل بلوحة المفاتيح

```
[ ] جميع العناصر التفاعلية قابلة للتركيز باستخدام Tab
[ ] ترتيب التركيز يطابق الترتيب البصري/المنطقي
[ ] التركيز مرئي على جميع العناصر
[ ] لا توجد مصائد لوحة مفاتيح (يمكن دائمًا الخروج باستخدام Tab)
[ ] رابط التخطي كأول عنصر قابل للتركيز
[ ] Escape يغلق النوافذ المنبثقة/القوائم المنسدلة
[ ] مفاتيح الأسهم تتنقل داخل المكونات (التبويبات، القوائم، الشبكات)
[ ] Enter/Space ينشط الأزرار والروابط
[ ] الاختصارات المخصصة موثقة وقابلة للتكوين
```

### أنماط إدارة التركيز

**مصيدة تركيز النافذة المنبثقة (Modal focus trap)**
```javascript
// عند فتح النافذة المنبثقة:
// 1. حفظ العنصر الذي كان مركزًا عليه سابقًا
// 2. نقل التركيز إلى أول عنصر قابل للتركيز في النافذة المنبثقة
// 3. حصر Tab داخل حدود النافذة المنبثقة

// عند إغلاق النافذة المنبثقة:
// 1. إعادة التركيز إلى العنصر المحفوظ
```

**محتوى ديناميكي**
```javascript
// بعد إضافة المحتوى:
// - الإعلان عبر منطقة aria-live، أو
// - نقل التركيز إلى عنوان المحتوى الجديد

// بعد إزالة المحتوى:
// - نقل التركيز إلى العنصر المنطقي التالي
// - لا تترك التركيز أبدًا على العنصر الذي تم إزالته
```

## اختبار قارئ الشاشة

### التحقق من الإعلان

| العنصر | يجب أن يعلن |
|---------|-----------------|
| زر | الدور + الاسم + الحالة ("زر إرسال") |
| رابط | الاسم + "رابط" ("رابط الصفحة الرئيسية") |
| صورة | نص بديل أو "تزييني" (تخطي) |
| عنوان | المستوى + النص ("عنوان المستوى 2، حولنا") |
| حقل نموذج | التسمية + النوع + الحالة + التعليمات |
| خطأ | رسالة الخطأ + ارتباط الحقل |

### أوامر الاختبار (مرجع سريع)

**VoiceOver (macOS)**
- VO = Ctrl + Option
- VO + A: قراءة الكل
- VO + يمين/يسار: التنقل بين العناصر
- VO + Cmd + H: العنوان التالي
- VO + Cmd + J: عنصر التحكم التالي في النموذج

**${screen_reader:NVDA} (Windows)**
- NVDA + أسفل: قراءة الكل
- Tab: العنصر القابل للتركيز التالي
- H: العنوان التالي
- F: حقل النموذج التالي
- B: الزر التالي

## تكامل الاختبار الآلي

### axe-core في الاختبارات
```javascript
// ${test_framework:jest-axe}
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

test('${component_name:component} is accessible', async () => {
  const { container } = render(<${component_name:MyComponent} />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});
```

### عتبة Lighthouse CI
```javascript
// lighthouserc.js
module.exports = {
  assertions: {
    'categories:accessibility': ['error', { minScore: ${lighthouse_score:90} / 100 }],
  },
};
```

## مصفوفة أولوية المعالجة

```
التأثير مقابل الجهد:
                    جهد منخفض    جهد عالٍ
تأثير عالٍ     |   افعل أولاً   |   خطط لاحقًا   |
                |   نص بديل    |   إعادة تصميم    |
                |   تسميات     |   إعادة بناء التنقل |
----------------|--------------|---------------|
تأثير منخفض      |   فوز سريع  |   قائمة المهام المتأخرة     |
                |   تباين   |   ميزات إضافية|
                |   تعديلات     |   تحسينات|
```

## قائمة تحقق التحقق

قبل اعتبار عمل إمكانية الوصول مكتملًا:

```
الاختبار الآلي:
[ ] تقارير axe-core لا تحتوي على انتهاكات
[ ] إمكانية الوصول في Lighthouse >= ${lighthouse_score:90}
[ ] مدقق HTML يمر (يؤثر على تحليل AT)

اختبار لوحة المفاتيح:
[ ] إكمال المهمة بالكامل بدون ماوس
[ ] تركيز مرئي في جميع الأوقات
[ ] ترتيب Tab منطقي
[ ] لا توجد مصائد

اختبار قارئ الشاشة:
[ ] تم الاختبار باستخدام قارئ شاشة واحد على الأقل (${screen_reader:NVDA})
[ ] جميع المحتويات معلنة بشكل صحيح
[ ] العناصر التفاعلية لها أدوار/حالات
[ ] التحديثات الديناميكية معلنة

الاختبار البصري:
[ ] تم التحقق من نسب التباين (الحد الأدنى ${contrast_ratio_normal:4.5}:1)
[ ] يعمل عند تكبير ${zoom_level:200}%
[ ] لا توجد معلومات يتم نقلها باللون وحده
[ ] يحترم prefers-reduced-motion