accessibility-voiceover-specialist

# AppKit VoiceOver Patterns

## Criterion 1 — Missing accessibility labels

### Bad: Image button without label
```swift
let button = NSButton()
button.image = NSImage(systemSymbolName: "trash", accessibilityDescription: nil)
button.bezelStyle = .toolbar
button.isBordered = false
button.target = self
button.action = #selector(deleteTapped)
```
VoiceOver announces: "Button" — no description. Note: `accessibilityDescription: nil` on `NSImage` means the image provides no label.

### Good: Image button with label via NSImage
```swift
let button = NSButton()
button.image = NSImage(systemSymbolName: "trash", accessibilityDescription: "Delete")
button.bezelStyle = .toolbar
button.isBordered = false
```
The `accessibilityDescription` on the `NSImage` provides the button's label.

### Good: Image button with explicit label
```swift
let button = NSButton()
button.image = NSImage(systemSymbolName: "trash", accessibilityDescription: nil)
button.setAccessibilityLabel("Delete")
```

### Good: Button with title (auto-labeled)
```swift
let button = NSButton(title: "Save", target: self, action: #selector(saveTapped))
```
VoiceOver announces: "Save, button" — the title provides the label.

## Criterion 2 — Non-human-readable labels

### Bad: Auto-generated identifier as label
```swift
cell.setAccessibilityLabel("cell_id_4f3a2b")
```

### Bad: Variable name as label
```swift
imageView.setAccessibilityLabel("imgHeaderBanner_v2")
```

### Good: Human-readable labels
```swift
cell.setAccessibilityLabel("\(document.title), \(document.dateFormatted)")
imageView.setAccessibilityLabel("Company logo")
```

## Criterion 3 — Incorrect or missing traits (roles in AppKit)

AppKit uses `setAccessibilityRole()` instead of `accessibilityTraits`.

### Bad: Clickable view with no role
```swift
class ClickableCard: NSView {
    override func mouseDown(with event: NSEvent) {
        openDetail()
    }

    init() {
        super.init(frame: .zero)
        setAccessibilityElement(true)
        setAccessibilityLabel("View details")
    }
}
```
VoiceOver does not announce this as a button.

### Good: Clickable view with button role
```swift
class ClickableCard: NSView {
    override func mouseDown(with event: NSEvent) {
        openDetail()
    }

    init() {
        super.init(frame: .zero)
        setAccessibilityElement(true)
        setAccessibilityLabel("View details")
        setAccessibilityRole(.button)
    }
}
```

### Good: Header with heading role
```swift
let header = NSTextField(labelWithString: "Recent Items")
header.font = .preferredFont(forTextStyle: .title2)
if #available(macOS 26.0, *) {
    header.setAccessibilityRole(.headingRole)
}
```
The heading role is available starting in macOS 26. On earlier versions, leave the role unset and rely on the visual styling alone.

## Criterion 4 — Inaccessible images

### Bad: NSImageView with meaningful content but no label
```swift
let imageView = NSImageView()
imageView.image = NSImage(named: "productPhoto")
view.addSubview(imageView)
```
`NSImageView` is not typically an accessibility element by default in AppKit.

### Good: NSImageView with label
```swift
let imageView = NSImageView()
imageView.image = NSImage(named: "productPhoto")
imageView.setAccessibilityElement(true)
imageView.setAccessibilityLabel("Red running shoes")
imageView.setAccessibilityRole(.image)
```

### Good: Decorative image correctly excluded
```swift
let decorativeView = NSImageView()
decorativeView.image = NSImage(named: "separator")
decorativeView.setAccessibilityElement(false)
```

### Good: NSImage with accessibilityDescription
```swift
let image = NSImage(systemSymbolName: "heart.fill", accessibilityDescription: "Favorite")
let imageView = NSImageView()
imageView.image = image
```
The image's `accessibilityDescription` provides the label.

## Criterion 5 — Missing setAccessibilityElement

### Bad: Custom interactive view not exposed to VoiceOver
```swift
class ColorWell: NSView {
    override func mouseDown(with event: NSEvent) {
        showColorPicker()
    }
}
```
This view handles clicks but is not an accessibility element.

### Good: Custom interactive view exposed to VoiceOver
```swift
class ColorWell: NSView {
    override init(frame: NSRect) {
        super.init(frame: frame)
        setAccessibilityElement(true)
        setAccessibilityLabel("Color picker")
        setAccessibilityRole(.button)
    }

    override func mouseDown(with event: NSEvent) {
        showColorPicker()
    }
}
```

### Additional roles (recommendations)

#### Search field subrole

```swift
let searchField = NSTextField()
searchField.placeholderString = "Search items"
searchField.setAccessibilityRole(.textField)
searchField.setAccessibilitySubrole(.searchField)
```
Note: `searchField` is a Subrole (not a Role) on AppKit.

#### Static text role on a non-text container

```swift
container.setAccessibilityRole(.staticText)
container.setAccessibilityValue(combinedText)
```

#### Tab group role for a custom segmented bar

```swift
tabBar.setAccessibilityRole(.tabGroup)
for tab in tabs {
    tab.setAccessibilityRole(.radioButton)
    tab.setAccessibilityValue(tab.isSelected ? 1 : 0)
}
```

#### Announcing a frequently-updating value (AppKit equivalent of UpdatesFrequently)

AppKit has no `accessibilityLiveRegion` setter. To announce updates, post the value-changed notification when the underlying value changes, or post an explicit announcement:

```swift
let scoreLabel = NSTextField(labelWithString: "0")

func updateScore(_ newScore: Int) {
    scoreLabel.stringValue = "\(newScore)"
    NSAccessibility.post(element: scoreLabel, notification: .valueChanged)
}
```

## Element grouping (informational)

### Recommendation: Group related elements
```swift
// Group child elements so VoiceOver reads them together
let container = NSStackView(views: [titleField, subtitleField, dateField])
container.setAccessibilityElement(true)
container.setAccessibilityLabel("\(title), \(subtitle), \(date)")
```

## Custom actions (informational)

### Custom view with hidden alternate actions

```swift
// Sighted users right-click for a menu; VoiceOver users have no path
class RowView: NSView {
    override func rightMouseDown(with event: NSEvent) { showContextMenu() }
}
```

### Same view exposing custom actions

```swift
class RowView: NSView {
    override init(frame: NSRect) {
        super.init(frame: frame)
        setAccessibilityElement(true)
        setAccessibilityCustomActions([
            NSAccessibilityCustomAction(name: "Archive") { [weak self] in
                self?.archive(); return true
            },
            NSAccessibilityCustomAction(name: "Delete") { [weak self] in
                self?.delete(); return true
            }
        ])
    }
}
```

## Reading order (informational)

### Override `accessibilityChildren()` to set reading order

```swift
class HeroCard: NSView {
    override func accessibilityChildren() -> [Any]? {
        [badgeView, titleField, subtitleField]
    }
}
```

# Platform-Specific VoiceOver Considerations

This doc captures behaviors that vary across Apple platforms and are not adequately
covered by the per-framework patterns. Read this in addition to the SwiftUI/UIKit/
AppKit references when auditing code targeting these platforms.

## iOS

Default platform. The patterns in `uikit-patterns.md` and `swiftui-patterns.md`
apply directly. No iOS-specific quirks affect the five hard FAIL criteria.

## iPadOS

Uses UIKit / SwiftUI identically to iOS for VoiceOver. Two iPad-specific
traits worth noting on hover-affordance views:

- `.accessibilityRespondsToUserInteraction` — set when a non-control view
  becomes tappable through a pointer/keyboard.
- Pointer hover does not change VoiceOver behavior; do not gate accessibility
  on pointer presence.

## macOS

Uses AppKit / SwiftUI. Key differences from iOS captured in
`appkit-patterns.md`:

- AppKit uses `setAccessibilityRole()` instead of `accessibilityTraits`.
- Standard NSControls are accessible by default; custom NSViews are not.
- VoiceOver on macOS uses different gestures (VO+arrow keys, VO+Space).
  Code does not change because of this; just be aware that "tappable" on
  macOS means "clickable / VO-Space-activatable".

## tvOS

Uses UIKit + SwiftUI. The focus engine drives navigation, but VoiceOver
still operates as a separate layer.

- A view that is `.focusable(true)` is not automatically a VoiceOver
  element. If a custom focusable view handles `pressesBegan` or a
  `UITapGestureRecognizer`, it still needs `isAccessibilityElement = true`
  + `accessibilityLabel` + `.button` trait, exactly like iOS.
- SwiftUI: `Button { ... } label: { ... }` is auto-accessible. A
  `.focusable()` modifier with `.onTapGesture` is **not** — apply
  `.accessibilityLabel` and `.accessibilityAddTraits(.isButton)`.

## watchOS

Uses SwiftUI. Two watchOS-specific accessibility surfaces:

- **Digital Crown / adjustable values** — Slider-like custom views must
  attach `.accessibilityAdjustableAction { direction in ... }`. The Crown
  maps to VoiceOver increment/decrement when this is set; the adjustable
  role is implicit, no separate trait is required in SwiftUI.
- **Limited screen real estate makes grouping more important** — the
  Recommendations section of the audit should call out cards/rows that
  would benefit from `.accessibilityElement(children: .combine)` more
  aggressively on watchOS.

## visionOS

Uses SwiftUI primarily, plus UIKit for catalysed apps. visionOS-specific
notes:

- Eye + pinch input does not change accessibility-element requirements.
  A view that is tappable via pinch must still have a label and the
  button trait if it is custom.
- Spatial containers (`RealityView`, `Model3D`) need explicit
  `.accessibilityLabel` — the system cannot describe 3D content.
- `.accessibilityRotor` is fully supported and especially useful in
  spatial UIs where focus order is hard to predict.

## How to use this doc during an audit

1. Identify the deployment platforms from the file's imports
   (`import WatchKit`, `import UIKit` + tvOS-specific symbols, etc.) or
   from the surrounding project context.
2. Apply the framework patterns first.
3. Layer on platform-specific behavior from this doc only when the file
   targets a non-default platform.
4. Platform behavior never changes the five hard FAIL criteria — it only
   adds context for recommendations and trait selection.

# SwiftUI VoiceOver Patterns

## Criterion 1 — Missing accessibility labels

### Bad: Icon-only button without label
```swift
Button {
    viewModel.delete()
} label: {
    Image(systemName: "trash")
}
```
VoiceOver announces: "Button" — no description of what the button does.

### Good: Icon-only button with explicit label
```swift
Button {
    viewModel.delete()
} label: {
    Image(systemName: "trash")
}
.accessibilityLabel("Delete")
```

### Good: Button with text content (auto-labeled)
```swift
Button("Save") {
    viewModel.save()
}
```
VoiceOver announces: "Save, button" — the text content provides the label automatically.

### Good: Button with Label (auto-labeled)
```swift
Button {
    openSettings()
} label: {
    Label("Settings", systemImage: "gear")
}
```
VoiceOver announces: "Settings, button" — the Label's text provides the accessibility label.

### Good: Toggle, Picker, Slider with title (auto-labeled)
```swift
Toggle("Dark Mode", isOn: $isDark)
Picker("Sort by", selection: $sort) { ... }
Slider(value: $volume, in: 0...1, label: { Text("Volume") })
```
The title parameter provides the label automatically.

## Criterion 2 — Non-human-readable labels

### Bad: Programmer identifier as label
```swift
Button {
    submit()
} label: {
    Image(systemName: "paperplane")
}
.accessibilityLabel("btn_submit_v2_final")
```

### Bad: File name as label
```swift
Image("hero_banner")
    .accessibilityLabel("hero_banner.png")
```

### Good: Human-readable labels
```swift
Button { submit() } label: { Image(systemName: "paperplane") }
    .accessibilityLabel("Send message")

Image("hero_banner")
    .accessibilityLabel("Mountain landscape at sunset")
```

## Criterion 3 — Incorrect or missing traits

### Bad: Custom tappable view without button trait
```swift
Text("Show Details")
    .padding()
    .background(.blue)
    .foregroundStyle(.white)
    .cornerRadius(8)
    .onTapGesture { showDetails = true }
```
VoiceOver announces as static text — the user does not know it is tappable.

### Good: Custom tappable view with button trait and label
```swift
Text("Show Details")
    .padding()
    .background(.blue)
    .foregroundStyle(.white)
    .cornerRadius(8)
    .onTapGesture { showDetails = true }
    .accessibilityAddTraits(.isButton)
```

### Bad: Section header without header trait
```swift
Text("Recent Items")
    .font(.title2)
    .bold()
```
VoiceOver will not include this in the headings rotor.

### Good: Section header with header trait
```swift
Text("Recent Items")
    .font(.title2)
    .bold()
    .accessibilityAddTraits(.isHeader)
```

## Criterion 4 — Inaccessible images

### Bad: Meaningful image without label
```swift
Image("userAvatar")
    .resizable()
    .frame(width: 60, height: 60)
    .clipShape(Circle())
```

### Good: Meaningful image with label
```swift
Image("userAvatar")
    .resizable()
    .frame(width: 60, height: 60)
    .clipShape(Circle())
    .accessibilityLabel("Profile photo")
```

### Good: Decorative image correctly excluded
```swift
Image(decorative: "backgroundPattern")
    .resizable()
```

### Good: Decorative image hidden from VoiceOver
```swift
Image("dividerLine")
    .accessibilityHidden(true)
```

### Good: SF Symbol inside a labeled container
```swift
Label("Favorites", systemImage: "heart.fill")
```
The Label provides the text — the SF Symbol does not need its own label.

### Bad: Variable image with unclear intent
```swift
Image(item.imageName)
    .resizable()
    .frame(width: 80, height: 80)
```
Cannot determine if decorative. Should either add `.accessibilityLabel()` or `.accessibilityHidden(true)`.

### Additional traits (recommendations)

#### Selected state in a segmented picker

```swift
ForEach(tabs, id: \.self) { tab in
    Text(tab.title)
        .onTapGesture { selection = tab }
        .accessibilityAddTraits(selection == tab ? [.isButton, .isSelected] : .isButton)
}
```

#### Updates-frequently for a live counter

```swift
Text(timerString)
    .font(.system(.title, design: .monospaced))
    .accessibilityAddTraits(.updatesFrequently)
```

#### Search field for a custom filter input

```swift
TextField("Search items", text: $query)
    .accessibilityAddTraits(.isSearchField)
```

#### Adjustable view with crown / increment+decrement

```swift
Text("\(rating) of 5")
    .accessibilityElement()
    .accessibilityLabel("Rating")
    .accessibilityValue("\(rating) of 5")
    .accessibilityAdjustableAction { direction in
        switch direction {
        case .increment: rating = min(rating + 1, 5)
        case .decrement: rating = max(rating - 1, 0)
        @unknown default: break
        }
    }
```

## Element grouping (informational)

### Recommendation: Combine related elements in a card
```swift
// Before: VoiceOver focuses on each element separately (verbose)
VStack {
    Image("product")
    Text("Widget Pro")
    Text("$9.99")
    Text("In Stock")
}

// After: VoiceOver reads the card as one unit
VStack {
    Image("product")
    Text("Widget Pro")
    Text("$9.99")
    Text("In Stock")
}
.accessibilityElement(children: .combine)
```

## Custom actions (informational)

### List row with swipe actions but no custom action

```swift
// Before — only sighted users can delete
ForEach(items) { item in
    Text(item.title)
        .swipeActions {
            Button("Delete", role: .destructive) { delete(item) }
        }
}
```

### List row with both swipe and custom action

```swift
ForEach(items) { item in
    Text(item.title)
        .swipeActions {
            Button("Delete", role: .destructive) { delete(item) }
        }
        .accessibilityAction(named: "Delete") { delete(item) }
}
```

### Multiple custom actions on a row

```swift
Text(item.title)
    .accessibilityAction(named: "Archive") { archive(item) }
    .accessibilityAction(named: "Pin") { pin(item) }
    .accessibilityAction(named: "Delete") { delete(item) }
```

## Reading order (informational)

### ZStack overlay read last by default

```swift
ZStack {
    MainContent()           // read first by default
    BannerOverlay()         // read second — but visually on top
}
```

### Promote the overlay to read first

```swift
ZStack {
    MainContent()
    BannerOverlay()
        .accessibilitySortPriority(1)
}
```

# UIKit VoiceOver Patterns

## Criterion 1 — Missing accessibility labels

### Bad: Image button without label
```swift
let button = UIButton(type: .system)
button.setImage(UIImage(systemName: "trash"), for: .normal)
button.addTarget(self, action: #selector(deleteTapped), for: .touchUpInside)
```
VoiceOver announces: "Button" — no description.

### Good: Image button with label
```swift
let button = UIButton(type: .system)
button.setImage(UIImage(systemName: "trash"), for: .normal)
button.addTarget(self, action: #selector(deleteTapped), for: .touchUpInside)
button.accessibilityLabel = "Delete"
```

### Good: Button with title (auto-labeled)
```swift
let button = UIButton(type: .system)
button.setTitle("Save", for: .normal)
```
VoiceOver announces: "Save, button" — the title provides the label.

### Good: Accessible image view
```swift
let imageView = UIImageView(image: UIImage(named: "userPhoto"))
imageView.isAccessibilityElement = true
imageView.accessibilityLabel = "Profile photo"
```

## Criterion 2 — Non-human-readable labels

### Bad: File path as label
```swift
imageView.accessibilityLabel = "IMG_2847.heic"
```

### Bad: Auto-generated identifier
```swift
cell.accessibilityLabel = "cell_row_\(indexPath.row)"
```

### Good: Human-readable labels
```swift
imageView.accessibilityLabel = "Beach at sunset"
cell.accessibilityLabel = "\(contact.name), \(contact.jobTitle)"
```

## Criterion 3 — Incorrect or missing traits

### Bad: Tappable view with isAccessibilityElement but no button trait
```swift
let cardView = UIView()
cardView.isAccessibilityElement = true
cardView.accessibilityLabel = "View details"
let tap = UITapGestureRecognizer(target: self, action: #selector(cardTapped))
cardView.addGestureRecognizer(tap)
```
VoiceOver does not announce this as a button — the user does not know it is tappable.

### Good: Tappable view with correct traits
```swift
let cardView = UIView()
cardView.isAccessibilityElement = true
cardView.accessibilityLabel = "View details"
cardView.accessibilityTraits = .button
let tap = UITapGestureRecognizer(target: self, action: #selector(cardTapped))
cardView.addGestureRecognizer(tap)
```

### Good: Header label with header trait
```swift
let headerLabel = UILabel()
headerLabel.text = "Recent Items"
headerLabel.font = .preferredFont(forTextStyle: .title2)
headerLabel.accessibilityTraits = .header
```

## Criterion 4 — Inaccessible images

### Bad: UIImageView with meaningful content but no label
```swift
let imageView = UIImageView(image: UIImage(named: "productPhoto"))
imageView.contentMode = .scaleAspectFill
view.addSubview(imageView)
```
`UIImageView` has `isAccessibilityElement = false` by default — it is invisible to VoiceOver.

### Good: UIImageView with label exposed to VoiceOver
```swift
let imageView = UIImageView(image: UIImage(named: "productPhoto"))
imageView.isAccessibilityElement = true
imageView.accessibilityLabel = "Red running shoes"
```

### Good: Decorative image correctly excluded
```swift
let decorativeView = UIImageView(image: UIImage(named: "separator"))
decorativeView.isAccessibilityElement = false
```

## Criterion 5 — Missing isAccessibilityElement

### Bad: Custom interactive view not exposed to VoiceOver
```swift
class RatingView: UIView {
    override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
        updateRating(from: touches)
    }
}
```
This view handles touches but is not an accessibility element — VoiceOver users cannot interact with it.

### Good: Custom interactive view exposed to VoiceOver
```swift
class RatingView: UIView {
    override init(frame: CGRect) {
        super.init(frame: frame)
        isAccessibilityElement = true
        accessibilityLabel = "Rating"
        accessibilityTraits = .adjustable
    }

    override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
        updateRating(from: touches)
    }

    override func accessibilityIncrement() { increaseRating() }
    override func accessibilityDecrement() { decreaseRating() }
}
```

### Additional traits (recommendations)

#### Selected state on a segmented control item

```swift
let tab = TabButton()
tab.accessibilityTraits = isSelected ? [.button, .selected] : .button
```

#### Updates-frequently for a live counter

```swift
let timerLabel = UILabel()
timerLabel.font = .monospacedDigitSystemFont(ofSize: 24, weight: .regular)
timerLabel.accessibilityTraits = .updatesFrequently
```

#### Search field for a custom filter input

```swift
let searchTextField = UITextField()
searchTextField.placeholder = "Search items"
searchTextField.accessibilityTraits = .searchField
```

#### Adjustable rating control

```swift
class RatingView: UIView {
    override init(frame: CGRect) {
        super.init(frame: frame)
        isAccessibilityElement = true
        accessibilityLabel = "Rating"
        accessibilityTraits = .adjustable
    }
    override var accessibilityValue: String? {
        get { "\(rating) of 5" } set {}
    }
    override func accessibilityIncrement() { rating = min(rating + 1, 5) }
    override func accessibilityDecrement() { rating = max(rating - 1, 0) }
}
```

## Element grouping (informational)

### Recommendation: Group related elements in a cell
```swift
// Before: VoiceOver focuses on each label separately
let nameLabel = UILabel()
let subtitleLabel = UILabel()
let priceLabel = UILabel()
stackView.addArrangedSubview(nameLabel)
stackView.addArrangedSubview(subtitleLabel)
stackView.addArrangedSubview(priceLabel)

// After: Group into a single accessibility element
stackView.isAccessibilityElement = true
stackView.accessibilityLabel = "\(name), \(subtitle), \(price)"
// Or:
stackView.shouldGroupAccessibilityChildren = true
```

## Custom actions (informational)

### Cell with editing actions but no custom actions

```swift
// Sighted users get swipe-to-delete; VoiceOver users do not
override func tableView(_ tableView: UITableView,
                        trailingSwipeActionsConfigurationForRowAt indexPath: IndexPath)
                        -> UISwipeActionsConfiguration? {
    UISwipeActionsConfiguration(actions: [
        UIContextualAction(style: .destructive, title: "Delete") { _, _, done in
            self.delete(indexPath); done(true)
        }
    ])
}
```

### Same cell, exposed via accessibilityCustomActions

```swift
override func tableView(_ tableView: UITableView,
                        cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = ...
    cell.accessibilityCustomActions = [
        UIAccessibilityCustomAction(name: "Delete") { [weak self] _ in
            self?.delete(indexPath); return true
        }
    ]
    return cell
}
```

## Reading order (informational)

### Override `accessibilityElements` to set reading order

```swift
class HeroCard: UIView {
    let titleLabel = UILabel()
    let subtitleLabel = UILabel()
    let badgeView = UIView()

    override var accessibilityElements: [Any]? {
        get { [badgeView, titleLabel, subtitleLabel] }
        set {}
    }
}
```