accessibility-testing

What this skill does

# Accessibility Testing Skill

**WCAG compliance and accessibility quality assurance for iOS applications**

## Overview

This skill teaches accessibility-first testing strategies for iOS apps. Accessibility testing ensures apps are usable by everyone, including people with disabilities. It combines automated validation of accessibility metadata with manual verification of user experience patterns.

**Why accessibility testing matters:**
- **Legal compliance:** WCAG 2.1 is required in many jurisdictions
- **User reach:** 15% of population has some form of disability
- **Better UX:** Accessible apps are better for everyone
- **SEO benefits:** Better structure improves discoverability
- **Cost savings:** Fix issues early vs. retrofitting

## When to Use This Skill

**Use this skill when:**
1. Validating accessibility compliance before release
2. Debugging VoiceOver issues or user reports
3. Implementing new features that need accessibility support
4. Running accessibility audits as part of CI/CD
5. Testing Dynamic Type support and contrast ratios
6. Verifying semantic markup and element roles
7. Checking keyboard navigation and focus management

**This skill covers:**
- Accessibility tree analysis and interpretation
- WCAG 2.1 compliance checking (A, AA, AAA levels)
- VoiceOver testing patterns
- Dynamic Type validation
- Common accessibility violations and fixes

## Quick Reference

| Task | Tool/Operation | Typical Time |
|------|---------------|--------------|
| Check accessibility quality | `accessibility-quality-check` | ~80ms |
| Query full accessibility tree | `idb-ui-describe` | ~120ms |
| Find element by label | `idb-ui-find-element` | ~100ms |
| Screenshot (fallback only) | `screenshot` | ~2000ms |
| VoiceOver simulation | Manual testing | - |

## Core Principle: Accessibility Tree First

**The accessibility tree IS your primary testing interface.**

Unlike visual testing (screenshots), the accessibility tree reveals:
- What screen readers "see"
- Semantic structure and relationships
- Focus order and navigation paths
- Element roles and states
- Text alternatives for non-text content

**3-4x faster and more reliable than visual inspection.**

## Key Concepts

### WCAG 2.1 Levels

**Level A (Minimum):**
- Text alternatives for images
- Keyboard accessibility
- No color-only information
- Headings and labels present

**Level AA (Recommended):**
- Contrast ratio 4.5:1 for normal text
- Contrast ratio 3:1 for large text
- Resize text up to 200%
- Meaningful focus order
- Descriptive labels and instructions

**Level AAA (Enhanced):**
- Contrast ratio 7:1 for normal text
- Contrast ratio 4.5:1 for large text
- No timing requirements
- Comprehensive error handling

**Target Level AA for most apps.**

### iOS Accessibility Properties

**Essential Properties:**

1. **accessibilityLabel:** What element is
   - Example: "Profile photo", "Send message button"
   - Should be concise, descriptive

2. **accessibilityValue:** Current state/value
   - Example: "50%", "Selected", "3 of 10"

3. **accessibilityHint:** What happens when activated
   - Example: "Opens your profile settings"
   - Use sparingly, only when action isn't obvious

4. **accessibilityTraits:** Element behavior
   - Button, Link, Header, Selected, etc.

5. **isAccessibilityElement:** Should be exposed
   - `true` for interactive/informative elements
   - `false` for decorative elements

### Accessibility Tree vs Visual UI

**Accessibility tree is semantic, not visual:**

```
Visual UI:
┌─────────────────┐
│ [img] John Doe  │  ← Visual: Image + Text
│ Online          │
└─────────────────┘

Accessibility Tree:
• Button: "John Doe, Online, Profile"  ← Single focusable element
  - label: "John Doe"
  - value: "Online"
  - hint: "Opens profile"
  - traits: [Button]
```

**Good accessibility = logical semantic structure.**

## Standard Workflow

### 1. Initial Accessibility Quality Check

**Start here to assess app's accessibility implementation:**

```json
{
  "operation": "check-accessibility",
  "target": "booted"
}
```

**Interprets accessibility tree quality:**
- **"excellent":** 90%+ elements have labels, good semantic structure
- **"good":** 70-90% coverage, minor issues
- **"fair":** 50-70% coverage, needs improvement
- **"poor":** <50% coverage, serious accessibility problems
- **"insufficient":** Cannot perform accessibility-based testing

**Decision tree:**
```
excellent/good → Proceed with accessibility-first testing
fair           → Test but expect to find issues
poor           → Major remediation needed
insufficient   → App may not support assistive tech
```

**Note:** Most modern iOS apps score "good" or "excellent".

### 2. Query Accessibility Tree

**Core operation for all accessibility testing:**

```json
{
  "operation": "describe",
  "target": "booted",
  "parameters": {
    "operation": "all"
  }
}
```

**Returns complete accessibility tree:**
```json
{
  "elements": [
    {
      "label": "Login",
      "type": "Button",
      "frame": { "x": 100, "y": 400, "width": 175, "height": 50 },
      "enabled": true,
      "visible": true,
      "traits": ["Button"],
      "value": null,
      "hint": "Sign in to your account"
    },
    {
      "label": "Email address",
      "type": "TextField",
      "value": "",
      "frame": { "x": 50, "y": 300, "width": 275, "height": 44 },
      "enabled": true,
      "visible": true,
      "traits": ["TextField"]
    }
  ]
}
```

**Analyze for:**
- All interactive elements have labels
- Labels are descriptive and concise
- Proper element types/traits
- Logical reading order (top-to-bottom, left-to-right)
- No duplicate or confusing labels

### 3. Validate Specific Elements

**Find and verify accessibility of specific UI elements:**

```json
{
  "operation": "find-element",
  "target": "booted",
  "parameters": {
    "query": "Submit button"
  }
}
```

**Validates:**
- Element exists in accessibility tree
- Has appropriate label
- Correct type and traits
- Enabled/visible state correct

### 4. Test Navigation and Focus

**Verify logical focus order:**

1. Query accessibility tree
2. Check elements appear in logical order
3. No gaps in navigation
4. Focus lands on meaningful elements first

**Focus order issues:**
```
Bad:  [Button: Cancel] → [Image: Decorative] → [Button: Submit] → [TextField]
Good: [TextField] → [Button: Submit] → [Button: Cancel]
```

## WCAG Compliance Workflows

### Testing Checklist

#### 1. Text Alternatives (WCAG 1.1)

**All non-text content needs text alternative:**

```
Query accessibility tree for all images
For each image:
  ✓ Has accessibilityLabel
  ✓ Label describes image content
  ✓ Or marked as decorative (isAccessibilityElement: false)
```

**Common violations:**
- Images with no label
- Generic labels: "image", "icon", "photo"
- Labels don't describe content: "png_12345"

**Fix:**
```swift
// Bad
imageView.isAccessibilityElement = true // No label

// Good
imageView.isAccessibilityElement = true
imageView.accessibilityLabel = "Profile photo of John Doe"

// Decorative (best if truly decorative)
imageView.isAccessibilityElement = false
```

#### 2. Keyboard/Focus Navigation (WCAG 2.1)

**All functionality available via sequential navigation:**

```
Query accessibility tree
Verify elements appear in logical order:
  ✓ Top to bottom
  ✓ Left to right
  ✓ Grouped logically
  ✓ Interactive elements are focusable
  ✓ Decorative elements are not focusable
```

**Test pattern:**
```
1. describe → Get all elements
2. Map order: element[0], element[1], element[2]...
3. Verify order matches visual/logical flow
4. Check no important elements missing
```

#### 3. Contrast Ratios (WCAG 1.4.3)

**Minimum contrast requirements:**
- **Normal text (<18pt):** 4.5:1 ratio (AA), 7:1 ratio (AAA)
- **Large text (≥18pt or ≥14pt bold):** 3:1 ratio (AA), 4.5:1 (AAA)
- **UI components:** 3:1 ratio (AA)

**Testing approach:**
```
1. screenshot → Capture current screen
2. Use color picker to sample text/background
3. Calculate con