Accessibility Diagnostics

Overview

Systematic accessibility diagnosis and remediation for iOS/macOS apps. Covers the 7 most common accessibility issues that cause App Store rejections and user complaints.

Core principle Accessibility is not optional. iOS apps must support VoiceOver, Dynamic Type, and sufficient color contrast to pass App Store Review. Users with disabilities depend on these features.

When to Use This Skill

• Fixing VoiceOver navigation issues (missing labels, wrong element order)
• Supporting Dynamic Type (text scaling for vision disabilities)
• Meeting color contrast requirements (WCAG AA/AAA)
• Fixing touch target size violations (< 44x44pt)
• Adding keyboard navigation (iPadOS/macOS)
• Supporting Reduce Motion (vestibular disorders)
• Preparing for App Store Review accessibility requirements
• Responding to user complaints about accessibility

The 7 Critical Accessibility Issues

1. VoiceOver Labels & Hints (CRITICAL - App Store Rejection)

Problem Missing or generic accessibility labels prevent VoiceOver users from understanding UI purpose.

WCAG 4.1.2 Name, Role, Value (Level A)

Common violations

// ❌ WRONG - No label (VoiceOver says "Button")
Button(action: addToCart) {
  Image(systemName: "cart.badge.plus")
}

// ❌ WRONG - Generic label
.accessibilityLabel("Button")

// ❌ WRONG - Reads implementation details
.accessibilityLabel("cart.badge.plus") // VoiceOver: "cart dot badge dot plus"

// ✅ CORRECT - Descriptive label
Button(action: addToCart) {
  Image(systemName: "cart.badge.plus")
}
.accessibilityLabel("Add to cart")

// ✅ CORRECT - With hint for complex actions
.accessibilityLabel("Add to cart")
.accessibilityHint("Double-tap to add this item to your shopping cart")

When to use hints

• Action is not obvious from label ("Add to cart" is obvious, no hint needed)
• Multi-step interaction ("Swipe right to confirm, left to cancel")
• State change ("Double-tap to toggle notifications on or off")

Decorative elements

// ✅ CORRECT - Hide decorative images from VoiceOver
Image("decorative-pattern")
  .accessibilityHidden(true)

// ✅ CORRECT - Combine multiple elements into one label
HStack {
  Image(systemName: "star.fill")
  Text("4.5")
  Text("(234 reviews)")
}
.accessibilityElement(children: .combine)
.accessibilityLabel("Rating: 4.5 stars from 234 reviews")

Testing

• Enable VoiceOver: Cmd+F5 (simulator) or triple-click side button (device)
• Navigate: Swipe right/left to move between elements
• Listen: Does VoiceOver announce purpose clearly?
• Check order: Does navigation order match visual layout?

2. Dynamic Type Support (HIGH - User Experience)

Problem Fixed font sizes prevent users with vision disabilities from reading text.

WCAG 1.4.4 Resize Text (Level AA - support 200% scaling without loss of content/functionality)

Common violations

// ❌ WRONG - Fixed size, won't scale
Text("Price: $19.99")
  .font(.system(size: 17))

UILabel().font = UIFont.systemFont(ofSize: 17)

// ❌ WRONG - Custom font without scaling
Text("Headline")
  .font(Font.custom("CustomFont", size: 24))

// ✅ CORRECT - SwiftUI semantic styles (auto-scales)
Text("Price: $19.99")
  .font(.body)

Text("Headline")
  .font(.headline)

// ✅ CORRECT - UIKit semantic styles
label.font = UIFont.preferredFont(forTextStyle: .body)

// ✅ CORRECT - Custom font with scaling
let customFont = UIFont(name: "CustomFont", size: 24)!
label.font = UIFontMetrics.default.scaledFont(for: customFont)
label.adjustsFontForContentSizeCategory = true

Custom sizes that scale with Dynamic Type

// ❌ WRONG - Fixed size, won't scale
Text("Price: $19.99")
  .font(.system(size: 17))

// ⚠️ ACCEPTABLE - Custom font without scaling (accessibility violation)
Text("Headline")
  .font(Font.custom("CustomFont", size: 24))

// ✅ GOOD - Custom size that scales with Dynamic Type
Text("Large Title")
  .font(.system(size: 60).relativeTo(.largeTitle))

Text("Custom Headline")
  .font(.system(size: 24).relativeTo(.title2))

// ✅ BEST - Use semantic styles when possible
Text("Headline")
  .font(.headline)

How relativeTo: works

• Base size: Your exact pixel size (24pt, 60pt, etc.)
• Scales with: The text style you specify (.title2, .largeTitle, etc.)
• Result: When user increases text size in Settings, your custom size grows proportionally

Example

• .title2 base: ~22pt → Your custom: 24pt (1.09x larger)
• User increases to "Extra Large" text
• .title2 grows to ~28pt → Your custom grows to ~30.5pt (maintains 1.09x ratio)

Fix hierarchy (best to worst)

1. Best: Use semantic styles (.title, .body, .caption)
2. Good: Use .system(size:).relativeTo() for required custom sizes
3. Acceptable: Custom font with .dynamicTypeSize() modifier
4. Unacceptable: Fixed sizes that never scale

SwiftUI text styles

• .largeTitle - 34pt (scales to 44pt at accessibility sizes)
• .title - 28pt
• .title2 - 22pt
• .title3 - 20pt
• .headline - 17pt semibold
• .body - 17pt (default)
• .callout - 16pt
• .subheadline - 15pt
• .footnote - 13pt
• .caption - 12pt
• .caption2 - 11pt

Layout considerations

// ❌ WRONG - Fixed frame breaks with large text
Text("Long product description...")
  .font(.body)
  .frame(height: 50) // Clips at large text sizes

// ✅ CORRECT - Flexible frame
Text("Long product description...")
  .font(.body)
  .lineLimit(nil) // Allow multiple lines
  .fixedSize(horizontal: false, vertical: true)

// ✅ CORRECT - Stack rearranges at large sizes
HStack {
  Text("Label:")
  Text("Value")
}
.dynamicTypeSize(...DynamicTypeSize.xxxLarge) // Limit maximum size if needed

Testing

1. Xcode Preview: Environment override

   .environment(\.sizeCategory, .ac