Accessibility Patterns — Expert Decisions
Expert decision frameworks for accessibility choices. Claude knows accessibilityLabel and VoiceOver — this skill provides judgment calls for element grouping, label strategies, and compliance trade-offs.
Decision Trees
Element Grouping Strategy
How should VoiceOver read this content?
├─ Logically related (card, cell, profile)
│ └─ Combine: .accessibilityElement(children: .combine)
│ Read as single unit
│
├─ Each part independently actionable
│ └─ Keep separate
│ User needs to interact with each
│
├─ Container with multiple actions
│ └─ Combine + custom actions
│ Single element with .accessibilityAction
│
├─ Decorative image with text
│ └─ Combine, image hidden
│ Image adds no meaning
│
└─ Image conveys different info than text
└─ Keep separate with distinct labels
Both need to be announced
The trap: Combining elements that have different actions. User can't interact with individual parts.
Label vs Hint Decision
What should be in label vs hint?
├─ What the element IS
│ └─ Label
│ "Play button", "Submit form"
│
├─ What happens when activated
│ └─ Hint (only if not obvious)
│ "Double tap to start playback"
│
├─ Current state
│ └─ Value
│ "50 percent", "Page 3 of 10"
│
└─ Control behavior
└─ Traits
.isButton, .isSelected, .isHeader
Dynamic Type Layout Strategy
How should layout adapt to larger text?
├─ Simple HStack (icon + text)
│ └─ Stay horizontal
│ Icons scale with text
│
├─ Complex HStack (image + multi-line)
│ └─ Stack vertically at xxxLarge
│ Check @Environment(\.dynamicTypeSize)
│
├─ Fixed-height cells
│ └─ Self-sizing
│ Remove height constraints
│
└─ Toolbar/navigation elements
└─ Consider overflow menu
Or scroll at extreme sizes
Reduce Motion Response
What happens when Reduce Motion is enabled?
├─ Transition between screens
│ └─ Instant or simple fade
│ No slide/zoom animations
│
├─ Loading indicators
│ └─ Static or minimal
│ No bouncing/spinning
│
├─ Autoplay video/animation
│ └─ Don't autoplay
│ User controls playback
│
├─ Parallax/motion effects
│ └─ Disable completely
│ Can cause vestibular issues
│
└─ Essential animation (progress)
└─ Keep but simplify
Linear, no bounce
NEVER Do
VoiceOver Labels
NEVER include element type in labels:
// ❌ Redundant — VoiceOver announces "Submit button, button"
Button("Submit") { }
.accessibilityLabel("Submit button")
// ✅ VoiceOver announces "Submit, button"
Button("Submit") { }
.accessibilityLabel("Submit")
// ❌ Redundant — "Profile image, image"
Image("profile")
.accessibilityLabel("Profile image")
// ✅ Describe what the image shows
Image("profile")
.accessibilityLabel("John Doe's profile photo")
NEVER use generic labels:
// ❌ User has no idea what this does
Button(action: deleteItem) {
Image(systemName: "trash")
}
.accessibilityLabel("Button")
// ❌ Still not helpful
Button(action: deleteItem) {
Image(systemName: "trash")
}
.accessibilityLabel("Icon")
// ✅ Describe the action
Button(action: deleteItem) {
Image(systemName: "trash")
}
.accessibilityLabel("Delete \(item.name)")
NEVER forget to label icon-only buttons:
// ❌ VoiceOver says nothing useful
Button(action: share) {
Image(systemName: "square.and.arrow.up")
}
// VoiceOver: "Button" (no label!)
// ✅ Always label icon buttons
Button(action: share) {
Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share")
Element Visibility
NEVER hide interactive elements from accessibility:
// ❌ User can't access this control
Button("Settings") { }
.accessibilityHidden(true) // Why would you do this?
// ✅ Every interactive element must be accessible
// Only hide truly decorative elements
Image("decorative-pattern")
.accessibilityHidden(true) // This is OK — adds nothing
NEVER leave decorative images accessible:
// ❌ VoiceOver reads meaningless "image"
Image("background-gradient")
// VoiceOver: "Image"
// ✅ Hide decorative elements
Image("background-gradient")
.accessibilityHidden(true)
Dynamic Type
NEVER use fixed font sizes for user content:
// ❌ Doesn't respect user's text size preference
Text("Hello, World!")
.font(.system(size: 16)) // Never scales!
// ✅ Use Dynamic Type styles
Text("Hello, World!")
.font(.body) // Scales automatically
// ✅ Custom font with scaling
Text("Custom")
.font(.custom("MyFont", size: 16, relativeTo: .body))
NEVER truncate text at larger sizes without alternative:
// ❌ Content disappears at larger text sizes
Text(longContent)
.lineLimit(2)
.font(.body)
// At xxxLarge, user sees "Lorem ips..."
// ✅ Allow expansion or provide full content path
Text(longContent)
.lineLimit(dynamicTypeSize >= .xxxLarge ? nil : 2)
.font(.body)
// Or use "Read more" expansion
Reduce Motion
NEVER ignore reduce motion for essential navigation:
// ❌ User with vestibular disorders feels sick
.transition(.slide)
// Reduce Motion enabled, but still slides
// ✅ Respect reduce motion
@Environment(\.accessibilityReduceMotion) var reduceMotion
.transition(reduceMotion ? .opacity : .slide)
NEVER autoplay video when reduce motion is enabled:
// ❌ Autoplay ignores user preference
VideoPlayer(player: player)
.onAppear { player.play() } // Always autoplays
// ✅ Check reduce motion
VideoPlayer(player: player)
.onAppear {
if !UIAccessibility.isReduceMotionEnabled {
player.play()
}
}
Color and Contrast
NEVER convey information by color alone:
// ❌ Color-blind users can't distinguish states
Circle()
.fill(isOnline ? .green : .red) // Only color differs
// ✅ Use shape/icon in addition to color
HStack {
Circle()
.fill(isOnline ? .green : .red)
Text(isOnline ? "Online" : "Offline")
}
// Or
Image(systemName: isOnline ? "checkmark.circle.fill" : "xmark.circle.fill")
.foregroundColor(isOnline ? .green : .red)
Essential Patterns
Accessible Card Component
struct AccessibleCard: View {
let item: Item
let onTap: () -> Void
let onDelete: () -> Void
let onShare: () -> Void
var body: some View {
VStack(alignment: .leading, spacing: 8) {
Text(item.title)
.font(.headline)
Text(item.description)
.font(.body)
.foregroundColor(.secondary)
Text(item.date, style: .date)
.font(.caption)
}
.padding()
.background(Color(.systemBackground))
.cornerRadius(12)
// Combine all text for VoiceOver
.accessibilityElement(children: .combine)
.accessibilityLabel("\(item.title). \(item.description). \(item.date.formatted())")
.accessibilityAddTraits(.isButton)
// Custom actions instead of hidden buttons
.accessibilityAction(.default) { onTap() }
.accessibilityAction(named: "Delete") { onDelete() }
.accessibilityAction(named: "Share") { onShare() }
}
}
Dynamic Type Adaptive Layout
struct AdaptiveProfileView: View {
@Environment(\.dynamicTypeSize) private var dynamicTypeSize
let user: User
var body: some View {
if dynamicTypeSize.isAccessibilitySize {
// Vertical layout for accessibility sizes
VStack(alignment: .leading, spacing: 12) {
profileImage
userInfo
}
} else {
// Horizontal layout for standard sizes
HStack(spacing: 16) {
profileImage
userInfo
}
}
}
private var profileImage: some View {
Image(user.avatarName)
.resizable()
.scaledToFill()
.frame(width: imageSize, height: imageSize)
.clipShape(Circle())
.accessibilityLabel("\(user.name)'s profile photo")
}
private var userInfo: some View {
VStack(alignment: .leading, spacing: 4) {
Text(user.name)
.font(.headline)
Text(user.title)
.font(.subheadline)
.foregroundColor(.secondary)
}
}
private var imageSize: CGFloat {
dynamicTypeSize.isAccessibilitySize ? 80 : 60
}
}
extension DynamicTypeSize {
var isAccessibilitySize: Bool {
self >= .accessibility1
}
}
Reduce Motion Wrapper
struct MotionSafeAnimation<Content: View>: View {
@Environment(\.accessibilityReduceMotion) private var reduceMotion
let fullAnimation: Animation
let reducedAnimation: Animation
let content: Content
init(
full: Animation = .spring(),
reduced: Animation = .linear(duration: 0.2),
@ViewBuilder content: () -> Content
) {
self.fullAnimation = full
self.reducedAnimation = reduced
self.content = content()
}
var body: some View {
content
.animation(reduceMotion ? reducedAnimation : fullAnimation, value: UUID())
}
}
// Usage
struct AnimatedButton: View {
@State private var isPressed = false
@Environment(\.accessibilityReduceMotion) private var reduceMotion
var body: some View {
Button("Tap Me") { }
.scaleEffect(isPressed ? 0.95 : 1.0)
.animation(reduceMotion ? nil : .spring(), value: isPressed)
.onLongPressGesture(minimumDuration: .infinity, pressing: { pressing in
isPressed = pressing
}, perform: {})
}
}
Accessible Form
struct AccessibleForm: View {
@State private var email = ""
@State private var password = ""
@State private var emailError: String?
@FocusState private var focusedField: Field?
enum Field: Hashable {
case email, password
}
var body: some View {
Form {
Section {
TextField("Email", text: $email)
.focused($focusedField, equals: .email)
.textContentType(.emailAddress)
.keyboardType(.emailAddress)
.accessibilityLabel("Email address")
.accessibilityValue(email.isEmpty ? "Empty" : email)
if let error = emailError {
Text(error)
.font(.caption)
.foregroundColor(.red)
.accessibilityLabel("Error: \(error)")
}
SecureField("Password", text: $password)
.focused($focusedField, equals: .password)
.textContentType(.password)
.accessibilityLabel("Password")
.accessibilityHint("Minimum 8 characters")
}
Button("Sign In") {
signIn()
}
.accessibilityLabel("Sign in")
.accessibilityHint("Double tap to sign in with entered credentials")
}
.onSubmit {
switch focusedField {
case .email:
focusedField = .password
case .password:
signIn()
case nil:
break
}
}
.onChange(of: emailError) { _, error in
if error != nil {
// Announce error to VoiceOver
UIAccessibility.post(notification: .announcement,
argument: "Error: \(error ?? "")")
}
}
}
}
Quick Reference
WCAG AA Requirements
| Criterion | Requirement | iOS Implementation | |-----------|-------------|-------------------| | 1.4.3 Contrast | 4.5:1 normal, 3:1 large | Use semantic colors | | 1.4.4 Resize Text | 200% without loss | Dynamic Type support | | 2.1.1 Keyboard | All functionality | VoiceOver navigation | | 2.4.7 Focus Visible | Clear focus indicator | @FocusState | | 2.5.5 Target Size | 44x44pt minimum | .frame(minWidth:minHeight:) |
Accessibility Traits
| Trait | When to Use | |-------|-------------| | .isButton | Custom tappable views | | .isHeader | Section titles | | .isSelected | Currently selected item | | .isLink | Navigates to URL | | .isImage | Meaningful images | | .playsSound | Audio triggers | | .startsMediaSession | Video/audio playback | | .adjustable | Swipe up/down to change value |
Focus Notifications
| Notification | Use Case | |--------------|----------| | .screenChanged | Major UI change, new screen | | .layoutChanged | Minor UI update | | .announcement | Status message | | .pageScrolled | Scroll position changed |
Red Flags
| Smell | Problem | Fix | |-------|---------|-----| | "Button" in label | Redundant | Remove type from label | | Icon without label | Inaccessible | Add accessibilityLabel | | .accessibilityHidden(true) on control | Can't interact | Remove or rethink | | .font(.system(size:)) | Doesn't scale | Use .font(.body) | | Color-only status | Color-blind exclusion | Add icon or text | | Animation ignores reduceMotion | Vestibular issues | Check environment | | Decorative image without hidden | Noisy VoiceOver | accessibilityHidden(true) | | Combined elements with separate actions | Can't interact individually | Keep separate or use custom actions |