/accessibility-testing

name: accessibility-testing
description: WCAG compliance testing and accessibility quality assurance workflows for iOS apps. Use when validating accessibility labels, testing VoiceOver compatibility, checking contrast ratios, or ensuring WCAG 2.1 compliance. Covers accessibility tree analysis, semantic validation, and automated accessibility testing patterns.
version: 0.0.1
token_cost: ~40

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:**

{
  "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:**

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

**Returns complete accessibility tree:**

{
  "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