iOS Accessibility Agent Skill

---
name: ios-accessibility
description: 'Expert guidance on iOS accessibility best practices, patterns, and implementation. Use when developers mention: (1) iOS accessibility, VoiceOver, Dynamic Type, or assistive technologies, (2) accessibility labels, traits, hints, or values, (3) automated accessibility testing, auditing, or manual testing, (4) Switch Control, Voice Control, or Full Keyboard Access, (5) inclusive design or accessibility culture, (6) making apps work for users with disabilities.'
---

# iOS Accessibility

## Overview

This skill provides expert guidance on iOS accessibility, covering VoiceOver, Dynamic Type, assistive technologies, inclusive design practices, and both UIKit and SwiftUI implementations. Use this skill to help developers build apps that work for everyone.

## The Approach

- **Shift-left** — Accessibility is part of the process. It needs to be considered even in prototypes or MVPs.
- **User-centric** — Accessibility is about people. Checklists help, but the goal is not checklist compliance. The goal is to offer a great experience for users with disabilities.
- **Progress over perfection** — Anytime is a good time to start. Focus on iterative and incremental improvements as you go. It goes a long way.
- **Test as you go** — Manual testing is part of development.

## Agent Behavior Contract

1. **Accessibility is non-deterministic.** Propose potential solutions in order of confidence and present with clear pros, cons, and trade-offs.
2. Before proposing fixes, identify the platform (UIKit vs SwiftUI) and the assistive technology, accessibility feature, or design consideration in context.
3. Do not recommend accessibility fixes without considering the user experience impact.
4. Prefer manual testing guidance alongside code changes, together with any automated or semi-automated solutions.
5. Cross-reference multiple assistive technologies when relevant (VoiceOver, Voice Control, Switch Control, Full Keyboard Access).

### Anti-Patterns to Avoid

- **Do not add trait names to labels** — Say "Close", not "Close button" (VoiceOver adds "button" automatically, when using the button trait)
- **Do not use `.accessibilityHidden(true)` on interactive elements** — Users won't be able to access them
- **Do not use fixed font sizes** — Always use text styles for Dynamic Type support
- **Do not use hardcoded colors for text** — Use semantic colors (`.label`, `.secondaryLabel`) for contrast and Dark Mode
- **Do not group UIKit elements without a clear combined label** — If `isAccessibilityElement = true`, set `accessibilityLabel` (and value/traits as needed).
- **Do not group SwiftUI elements without a clear combined label** — If `.accessibilityElement(children: .ignore)` is used, provide label/value/traits manually.
- **Do not add hints unless needed** — It should be clear what a component expresses, and does, by its label/value/traits. Only configure for adding extra clarity or context.
- **Do not rely on `onTapGesture` alone** — Prefer semantic controls like `Button`. If gesture handling is unavoidable, add button traits and clear labels.
- **Do not scale chrome controls with Dynamic Type** — For navigation bars, toolbars, and tab bars, prefer Large Content Viewer (iOS 13+) using [`.accessibilityShowsLargeContentViewer`](https://developer.apple.com/documentation/swiftui/view/accessibilityshowslargecontentviewer(content:)) / [`UILargeContentViewerItem`](https://developer.apple.com/documentation/uikit/uilargecontentvieweritem).

### General Guidance

**Prefer native components:** Whenever possible, use Apple's native components and customize them to your needs instead of building custom components from scratch.

**Design system first:** Whenever the project uses a design system of its own (colors, text styles, component catalog), propose changes in the design system itself so the improvement snowballs everywhere in the app using an improved component.

**Platform parity:** The same accessibility principles apply to both UIKit and SwiftUI, but APIs and implementation details differ.

## Project Settings Intake (Evaluate Before Advising)

Before providing accessibility guidance, determine: