@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/ios-accessibility/references/a11y-patterns.md

@@ -1,398 +1,452 @@
-# Accessibility Patterns Reference
+# Accessibility Code Patterns
+
+Back to [SKILL.md](../SKILL.md).
 
 ## Contents
-- Labels, Values, and Hints
-- Traits and Element Grouping
-- Custom Controls and Adjustable Actions
-- Focus Management Patterns
-- Dynamic Type and Layout
-- Custom Rotors
-- System Accessibility Preferences
-- UIKit Accessibility Patterns
-- AppKit Accessibility Patterns
-- Common Mistakes Checklist
-- Voice Control Patterns
-- Switch Control Patterns
-- Full Keyboard Access Patterns
-- Automated Accessibility Testing
-
-## Labels, Values, and Hints
+
+- [Labels, values, hints](#labels-values-hints)
+- [Traits and grouping](#traits-and-grouping)
+- [Custom and adjustable controls](#custom-and-adjustable-controls)
+- [Focus patterns](#focus-patterns)
+- [Dynamic Type and layout](#dynamic-type-and-layout)
+- [Custom rotors](#custom-rotors)
+- [System preference values](#system-preference-values)
+- [UIKit](#uikit)
+- [AppKit](#appkit)
+- [Mistakes to catch in review](#mistakes-to-catch-in-review)
+- [Voice Control](#voice-control)
+- [Switch Control](#switch-control)
+- [Full Keyboard Access](#full-keyboard-access)
+- [Automated checks with XCTest](#automated-checks-with-xctest)
+
+## Labels, values, hints
 
 ```swift
-Button(action: { }) {
-    Image(systemName: "heart.fill")
+// Icon-only button: the label is what VoiceOver and Voice Control use.
+Button { bookmark(article) } label: {
+    Image(systemName: article.isSaved ? "bookmark.fill" : "bookmark")
 }
-.accessibilityLabel("Favorite")
+.accessibilityLabel("Bookmark")
 
-Slider(value: $volume, in: 0...100)
-    .accessibilityValue("\(Int(volume)) percent")
+// Value: speak the number people care about, not the raw slider position.
+Slider(value: $brightness)                  // 0.0 ... 1.0
+    .accessibilityLabel("Brightness")
+    .accessibilityValue("\(Int(brightness * 100)) percent")
 
-Button("Submit")
-    .accessibilityHint("Submits the form and sends your feedback")
+// Hint: what happens when activated, read last and only after a pause.
+Button("Archive", action: archiveThread)
+    .accessibilityHint("Moves this conversation out of the inbox")
 ```
 
-## Traits and Element Grouping
+## Traits and grouping
+
+`.accessibilityAddTraits` adds to the element's existing traits rather than
+replacing them:
 
 ```swift
-// Add traits without overwriting defaults
-Button("Go") { }
+Text(departureCountdown)
     .accessibilityAddTraits(.updatesFrequently)
+```
+
+Merge a row so it is one stop instead of three:
 
-// Group children into a single accessibility element
+```swift
 HStack {
-    Image(systemName: "person.circle")
-    VStack {
-        Text("John Doe")
-        Text("Engineer")
+    Image(driver.photoName)
+    VStack(alignment: .leading) {
+        Text(driver.name)
+        Text(driver.vehicle)
     }
 }
 .accessibilityElement(children: .combine)
+```
 
-// Binary custom control: prefer Toggle when possible; otherwise expose toggle state
-HStack {
-    Image(systemName: isFavorite ? "heart.fill" : "heart")
-    Text(product.name)
+### Two-state custom control
+
+First choice is a real `Toggle`. When the design forces a custom view, expose
+it as a toggle yourself:
+
+```swift
+struct PinChip: View {
+    let noteTitle: String
+    @Binding var isPinned: Bool
+
+    var body: some View {
+        HStack(spacing: 6) {
+            Image(systemName: isPinned ? "pin.fill" : "pin")
+            Text(noteTitle)
+        }
+        .onTapGesture { isPinned.toggle() }
+        .accessibilityElement()
+        .accessibilityLabel("Pin \(noteTitle)")
+        .accessibilityValue(isPinned ? "On" : "Off")
+        .accessibilityAddTraits(.isToggle)          // iOS 17+
+        .accessibilityAction { isPinned.toggle() }  // default activate action
+    }
 }
-.onTapGesture { isFavorite.toggle() }
-.accessibilityElement()
-.accessibilityLabel("Favorite \(product.name)")
-.accessibilityValue(isFavorite ? "On" : "Off")
-.accessibilityAddTraits(.isToggle)
-.accessibilityAction { isFavorite.toggle() }
 ```
 
-## Custom Controls and Adjustable Actions
+## Custom and adjustable controls
+
+For quantities, steppers, ratings, sliders and any other adjustable value,
+start from the native control (`Stepper`, `Slider`, `Picker`). Only a truly
+custom control needs the work below: in SwiftUI
+`.accessibilityAdjustableAction`, in UIKit
+`accessibilityTraits.insert(.adjustable)` plus `accessibilityIncrement()` /
+`accessibilityDecrement()`.
 
 ```swift
-HStack { /* custom star rating UI */ }
-    .accessibilityElement()
-    .accessibilityLabel("Rating")
-    .accessibilityValue("\(rating) out of 5 stars")
-    .accessibilityAdjustableAction { direction in
-        switch direction {
-        case .increment: if rating < 5 { rating += 1 }
-        case .decrement: if rating > 1 { rating -= 1 }
-        @unknown default: break
+struct SpiceLevelPicker: View {
+    @Binding var level: Int          // 1...4
+    private let range = 1...4
+
+    var body: some View {
+        HStack {
+            ForEach(range, id: \.self) { value in
+                Image(systemName: value <= level ? "flame.fill" : "flame")
+                    .onTapGesture { level = value }
+            }
+        }
+        .accessibilityElement()
+        .accessibilityLabel("Spice level")
+        .accessibilityValue("\(level) of \(range.upperBound)")
+        .accessibilityAdjustableAction { change in
+            switch change {
+            case .increment: level = min(level + 1, range.upperBound)
+            case .decrement: level = max(level - 1, range.lowerBound)
+            @unknown default: break
+            }
         }
     }
+}
 ```
 
-For custom quantity controls, steppers, ratings, sliders, or other adjustable values, prefer the native control first. If the control is custom, SwiftUI needs `.accessibilityAdjustableAction`; UIKit custom controls also need `accessibilityTraits.insert(.adjustable)`.
+## Focus patterns
 
-## Focus Management Patterns
+Returning focus after a sheet, with a `Bool`:
 
 ```swift
-@AccessibilityFocusState private var focusOnTrigger: Bool
-
-Button("Open Settings") { showSheet = true }
-    .accessibilityFocused($focusOnTrigger)
-    .sheet(isPresented: $showSheet) {
-        SettingsSheet()
-            .onDisappear {
-                Task { @MainActor in
-                    try? await Task.sleep(for: .milliseconds(100))
-                    focusOnTrigger = true
-                }
+struct InvoiceHeader: View {
+    @State private var editing = false
+    @AccessibilityFocusState private var editButtonFocused: Bool
+
+    var body: some View {
+        Button("Edit invoice", systemImage: "pencil") { editing = true }
+            .accessibilityFocused($editButtonFocused)
+            .sheet(isPresented: $editing) {
+                InvoiceEditor()
+                    .onDisappear {
+                        Task { @MainActor in
+                            try? await Task.sleep(nanoseconds: 100_000_000)
+                            editButtonFocused = true
+                        }
+                    }
             }
     }
+}
 ```
 
+Several targets, with an optional enum:
+
 ```swift
-enum A11yFocus: Hashable { case nameField, emailField, submitButton }
-@AccessibilityFocusState private var focus: A11yFocus?
+enum AddressFocus: Hashable { case street, city, postcode }
+
+@AccessibilityFocusState private var addressFocus: AddressFocus?
+// TextField("Street", text: $street).accessibilityFocused($addressFocus, equals: .street)
+// On a bad postcode: addressFocus = .postcode
 ```
 
-## Dynamic Type and Layout
+## Dynamic Type and layout
 
 ```swift
-@ScaledMetric(relativeTo: .title) private var iconSize: CGFloat = 24
-@ScaledMetric(relativeTo: .body) private var rowSpacing: CGFloat = 12
-@ScaledMetric(relativeTo: .body) private var controlHeight: CGFloat = 44
-@Environment(\.dynamicTypeSize) var dynamicTypeSize
-
-var body: some View {
-    Group {
-        if dynamicTypeSize.isAccessibilitySize {
-            VStack(alignment: .leading) { icon; textContent }
-        } else {
-            HStack { icon; textContent }
+struct TransferRow: View {
+    @Environment(\.dynamicTypeSize) private var typeSize
+    @ScaledMetric(relativeTo: .body) private var rowHeight: CGFloat = 44
+    @ScaledMetric(relativeTo: .body) private var gap: CGFloat = 12
+    @ScaledMetric(relativeTo: .title) private var glyphSize: CGFloat = 24
+
+    let transfer: Transfer
+
+    var body: some View {
+        let layout = typeSize.isAccessibilitySize
+            ? AnyLayout(VStackLayout(alignment: .leading, spacing: gap))
+            : AnyLayout(HStackLayout(spacing: gap))
+
+        layout {
+            Image(systemName: "arrow.up.arrow.down")
+                .font(.system(size: glyphSize))
+            Text(transfer.counterparty).font(.body)
+            Text(transfer.amountText).font(.headline)
         }
+        .frame(minHeight: rowHeight)
     }
-    .frame(minHeight: controlHeight)
 }
 ```
 
-Use `@ScaledMetric(relativeTo:)` for non-text dimensions that need to track text size, including icon sizes, spacing, control heights, and custom hit-region dimensions.
+- `@ScaledMetric(relativeTo:)` is for custom hit regions, control heights,
+  spacing and glyph sizes that should keep pace with the text.
+- `dynamicTypeSize.isAccessibilitySize` is the usual switch point from a
+  horizontal row to a leading-aligned vertical stack.
 
-## Custom Rotors
+## Custom rotors
 
 ```swift
-List(items) { item in ItemRow(item: item) }
-    .accessibilityRotor("Unread") {
-        ForEach(items.filter { !$0.isRead }) { item in
-            AccessibilityRotorEntry(item.title, id: item.id)
-        }
+List(inbox) { item in
+    MessageRow(message: item)
+}
+.accessibilityRotor("Flagged") {
+    ForEach(inbox.filter(\.isFlagged)) { item in
+        AccessibilityRotorEntry(item.subject, id: item.id)
     }
+}
 ```
 
-## System Accessibility Preferences
+## System preference values
 
-```swift
-@Environment(\.accessibilityReduceMotion) var reduceMotion
-@Environment(\.accessibilityReduceTransparency) var reduceTransparency
-@Environment(\.colorSchemeContrast) var contrast
-@Environment(\.legibilityWeight) var legibilityWeight
-```
+The four environment values to read are `\.accessibilityReduceMotion`,
+`\.accessibilityReduceTransparency`, `\.colorSchemeContrast` and
+`\.legibilityWeight`. Usage is in [SKILL.md](../SKILL.md#system-preferences).
 
-## UIKit Accessibility Patterns
+## UIKit
 
 ```swift
-customButton.accessibilityTraits.insert(.button)
-customButton.accessibilityTraits.remove(.staticText)
+final class StatusPill: UIView {
+    func configureAccessibility(title: String) {
+        isAccessibilityElement = true
+        accessibilityLabel = title
+        accessibilityTraits.insert(.button)
+        accessibilityTraits.remove(.staticText)
+    }
+}
 
-UIAccessibility.post(notification: .announcement, argument: "Upload complete")
-UIAccessibility.post(notification: .layoutChanged, argument: targetView)
-UIAccessibility.post(notification: .screenChanged, argument: newScreenView)
+// Status, partial update, full screen change:
+UIAccessibility.post(notification: .announcement, argument: "3 files uploaded")
+UIAccessibility.post(notification: .layoutChanged, argument: resultsTable)
+UIAccessibility.post(notification: .screenChanged, argument: onboardingTitle)
 ```
 
-## AppKit Accessibility Patterns
+## AppKit
 
-AppKit accessibility centers on `NSAccessibilityProtocol`. Use standard AppKit controls when possible, then override or add accessibility behavior only where the default metadata is wrong or incomplete.
+Everything flows through `NSAccessibilityProtocol`. Customize only the pieces
+AppKit gets wrong or leaves out.
 
-### Custom NSView with role, label, value, and action
+### Custom view: role, label, value, action
 
 ```swift
-final class FavoriteToggleView: NSView {
-    var isFavorite = false {
+final class LockToggleView: NSView {
+    private(set) var isLocked = false {
         didSet {
             NSAccessibility.post(element: self, notification: .valueChanged)
+            needsDisplay = true
         }
     }
 
+    override func accessibilityLabel() -> String? { "Lock layer" }
+    override func accessibilityValue() -> Any? { isLocked ? "Locked" : "Unlocked" }
     override func isAccessibilityElement() -> Bool { true }
-    override func accessibilityRole() -> NSAccessibility.Role? { .button }
-    override func accessibilityLabel() -> String? { "Favorite" }
-    override func accessibilityValue() -> Any? { isFavorite ? "On" : "Off" }
-
     override func accessibilityPerformPress() -> Bool {
-        isFavorite.toggle()
+        isLocked.toggle()
         return true
     }
+    override func accessibilityRole() -> NSAccessibility.Role? { .button }
 }
 ```
 
-### NSAccessibilityElement for non-view items
+### Elements with no view
 
-Use `NSAccessibilityElement` when an accessible item has no backing `NSView`, such as a virtual data point in a chart or a drawn annotation.
+For things that are drawn rather than backed by an `NSView`, such as one bar
+in a chart or an annotation painted on a canvas, create an
+`NSAccessibilityElement`:
 
 ```swift
-let pointElement = NSAccessibilityElement.element(
+let barElement = NSAccessibilityElement.element(
     withRole: .button,
-    frame: pointFrame,
-    label: "March revenue",
+    frame: barFrameInScreenCoordinates,
+    label: "March revenue, 42 thousand",
     parent: chartView
 )
 ```
 
-### AppKit announcements and notifications
+### Notifications
 
 ```swift
-NSAccessibility.post(element: saveStatusLabel, notification: .valueChanged)
+// The accessible value changed.
+NSAccessibility.post(element: sliderView, notification: .valueChanged)
 
+// A passing status message.
 NSAccessibility.post(
-    element: self,
+    element: exportPanelView,
     notification: .announcementRequested,
-    userInfo: [
-        .announcement: "Export complete"
-    ]
+    userInfo: [.announcement: "Backup finished"]
 )
 ```
 
-Use `.announcementRequested` when assistive apps need to announce transient status. Use state-specific notifications such as `.valueChanged` when the accessible value changed.
-
-## Common Mistakes Checklist
-
-- Direct trait assignment instead of `.accessibilityAddTraits`
-- Missing focus restoration after dismissing sheets
-- Ungrouped list rows creating excessive swipe stops
-- Icon-only buttons missing labels
-- Ignoring Reduce Motion, Reduce Transparency, or Increase Contrast
-- Fixed font sizes that break Dynamic Type
-- Tap targets smaller than 44x44 points
+Pick `.announcementRequested` for transient status and the specific
+notification (such as `.valueChanged`) when the element's accessible value
+actually changed.
 
-## Voice Control Patterns
+## Mistakes to catch in review
 
-Voice Control generates tap targets from accessibility labels. Labels must be speakable and unique within the visible screen.
+- Tap targets below 44x44 pt.
+- Traits assigned directly instead of through `.accessibilityAddTraits`.
+- Hard-coded font sizes, so Dynamic Type has no effect.
+- Focus not restored after a sheet closes.
+- Icon-only buttons with no label.
+- Increase Contrast, Reduce Transparency or Reduce Motion settings ignored.
+- List rows left ungrouped, each producing several swipe stops.
 
-### accessibilityInputLabels (iOS 14+)
+## Voice Control
 
-Provide shorter spoken alternatives when the primary label is long, awkward, repeated, localized, acronym-heavy, or commonly shortened in speech:
+Voice Control builds its tap targets from accessibility labels, so every label
+must be something a person can say, and unique among what is visible.
+`accessibilityInputLabels` (iOS 14+) supplies shorter spoken alternatives when
+the main label is long, clumsy, repeated, localized, acronym-heavy, or
+normally shortened in speech.
 
 ```swift
-// Primary label is descriptive but long to speak
-Button(action: { startWorkout() }) {
-    VStack {
-        Image(systemName: "figure.run")
-        Text("Start Outdoor Running Workout")
-    }
-}
-.accessibilityLabel("Start Outdoor Running Workout")
-.accessibilityInputLabels(["Start Run", "Run", "Start Workout"])
-```
+Button("Start 45-minute progressive endurance ride") { startRide() }
+    .accessibilityLabel("Start 45-minute progressive endurance ride")
+    .accessibilityInputLabels(["Start ride", "Endurance ride", "Ride"])
 
-```swift
-// Navigation link with verbose label
-NavigationLink {
-    AccountSettingsView()
-} label: {
-    Label("Account and Privacy Settings", systemImage: "person.circle")
+NavigationLink(value: Route.notifications) {
+    Label("Notification and alert preferences", systemImage: "bell.badge")
 }
-.accessibilityInputLabels(["Account", "Settings", "Privacy"])
+.accessibilityInputLabels(["Notifications", "Alerts"])
 ```
 
-Also consider input labels for repeated row actions, quantity controls, media controls, and product-name labels where Voice Control users are likely to speak a shorter command than the visible text.
+Also worth input labels: labels built from product names, playback controls,
+steppers for quantities, and the same action repeated on every row.
 
-### Speakable Label Guidelines
+### Speakable labels
 
 ```swift
-// Bad: emoji-only, unspeakable
-Button("❤️") { toggleFavorite() }
+// Bad: nothing to say.
+Button("\u{1F5D1}") { remove(entry) }   // a wastebasket emoji
 
-// Good: speakable label
-Button(action: { toggleFavorite() }) {
-    Image(systemName: "heart.fill")
-}
-.accessibilityLabel("Favorite")
+// Good: symbol on screen, words for speech.
+Button { remove(entry) } label: { Image(systemName: "trash") }
+    .accessibilityLabel("Delete")
 
-// Bad: duplicate labels on same screen
-ForEach(items) { item in
-    Button("Edit") { edit(item) }  // Voice Control can't distinguish
+// Bad: ten identical "Rename" buttons; Voice Control cannot tell them apart.
+ForEach(playlists) { playlist in
+    Button("Rename") { rename(playlist) }
 }
 
-// Good: unique labels
-ForEach(items) { item in
-    Button("Edit") { edit(item) }
-        .accessibilityLabel("Edit \(item.name)")
+// Good: keep the visible word, make the spoken name unique.
+ForEach(playlists) { playlist in
+    Button("Rename") { rename(playlist) }
+        .accessibilityLabel("Rename \(playlist.name)")
 }
 ```
 
-## Switch Control Patterns
-
-Switch Control scans elements sequentially. Reduce scan stops with grouping and provide custom actions for gesture-based interactions.
+## Switch Control
 
-### Custom Actions for Gesture Alternatives
+Switch Control scans element by element, so group to cut stops and add custom
+actions for anything gesture-driven.
 
 ```swift
-// Swipe-to-delete row: Switch Control can't swipe
+// Swipe actions also exposed as named actions.
 TaskRow(task: task)
-    .accessibilityAction(named: "Complete") { completeTask(task) }
-    .accessibilityAction(named: "Delete") { deleteTask(task) }
-    .accessibilityAction(named: "Reschedule") { rescheduleTask(task) }
-```
-
-```swift
-// Long-press context menu: expose actions directly
-PhotoThumbnail(photo: photo)
-    .contextMenu { /* ... */ }
-    .accessibilityAction(named: "Share") { sharePhoto(photo) }
+    .swipeActions {
+        Button("Delete", role: .destructive) { delete(task) }
+    }
+    .accessibilityAction(named: "Mark done") { complete(task) }
+    .accessibilityAction(named: "Delete") { delete(task) }
+    .accessibilityAction(named: "Snooze until tomorrow") { snooze(task) }
+
+// Context-menu operations reachable without a long press.
+PhotoTile(photo: photo)
+    .contextMenu {
+        Button("Share") { share(photo) }
+        Button("Add to Album") { addToAlbum(photo) }
+        Button("Delete", role: .destructive) { delete(photo) }
+    }
+    .accessibilityAction(named: "Delete") { delete(photo) }
+    .accessibilityAction(named: "Share") { share(photo) }
     .accessibilityAction(named: "Add to Album") { addToAlbum(photo) }
-    .accessibilityAction(named: "Delete") { deletePhoto(photo) }
 ```
 
-### Grouping for Scan Efficiency
+Grouping in numbers: this attachment row is five scan stops as written (icon,
+name, date, size, chevron). With `.combine` it becomes one.
 
 ```swift
-// Bad: 5 scan stops per row
-HStack {
-    Image(systemName: "doc")
-    VStack {
-        Text(document.title)
-        Text(document.date.formatted())
-    }
-    Spacer()
-    Text(document.size)
-    Image(systemName: "chevron.right")
-}
-
-// Good: 1 scan stop per row
 HStack {
-    Image(systemName: "doc")
-    VStack {
-        Text(document.title)
-        Text(document.date.formatted())
-    }
-    Spacer()
-    Text(document.size)
+    Image(systemName: "paperclip")
+    Text(file.name)
+    Text(file.modified, style: .date)
+    Text(file.sizeText)
     Image(systemName: "chevron.right")
 }
 .accessibilityElement(children: .combine)
 ```
 
-## Full Keyboard Access Patterns
-
-Full Keyboard Access review checks whether keyboard users can complete the same common tasks without touch. Keep the implementation mechanics in the `focus-engine` skill when the fix requires Tab-order wiring, skipped custom cards, `.focusable()`, SwiftUI keyboard focus state, focus sections, directional movement, tvOS focus, or `UIFocusGuide`.
+VoiceOver users benefit from the same change: one swipe per attachment instead
+of five.
 
-- Every interactive control is reachable by keyboard.
-- Activation works with expected keyboard input.
-- Focus indicators are visible and not hidden by custom styling.
-- Focus traversal is logical and does not trap users in a region.
-- Gesture-only interactions have keyboard-operable alternatives.
-- App shortcuts do not override system shortcuts.
-- Custom controls skipped by Tab should be filed as keyboard focus implementation issues and routed to `focus-engine`; keep the accessibility finding here.
-- Explicitly assess traversal impact: accessibility element order and grouping affect VoiceOver swipe order, Switch Control scan order, Voice Control overlay targeting, and Full Keyboard Access reachability review.
+## Full Keyboard Access
 
-## Automated Accessibility Testing
+The question a review asks: can someone using only a keyboard complete the
+same common tasks as someone using touch? The mechanics (`UIFocusGuide`, tvOS
+focus, arrow-key movement, focus sections, SwiftUI keyboard focus state,
+`.focusable()`, cards that Tab skips, Tab order wiring) are `hig-inputs`
+work.
 
-Use `XCUIElement` attributes to verify accessibility properties in UI tests.
+Check:
 
-### Verifying Labels and Identifiers
+- every interactive control can be reached from the keyboard;
+- it activates with the keys people expect (Space, Return);
+- the focus ring is visible and no custom style hides it;
+- traversal is logical and never gets stuck in one region;
+- gesture-only interactions have a keyboard alternative;
+- the app's shortcuts do not shadow system shortcuts.
 
-```swift
-func testAccessibilityLabels() throws {
-    let app = XCUIApplication()
-    app.launch()
-
-    // Verify buttons have meaningful labels
-    let settingsButton = app.buttons["Settings"]
-    XCTAssertTrue(settingsButton.exists, "Settings button must exist")
-    XCTAssertTrue(settingsButton.isEnabled, "Settings button must be enabled")
-
-    // Verify a cell groups content correctly
-    let productCell = app.cells.element(boundBy: 0)
-    XCTAssertFalse(productCell.label.isEmpty, "Product cell must have a combined label")
-}
-```
+A custom control that Tab skips is filed as a keyboard-focus implementation
+issue for `hig-inputs`, while the accessibility finding is recorded here.
+Whatever the bug, write down what the current ordering and grouping do to the
+four traversal paths: VoiceOver swipes, switch scanning, Voice Control
+overlays and keyboard reach.
 
-### Testing Focus and Selection State
+## Automated checks with XCTest
 
 ```swift
-func testTabNavigationOrder() throws {
-    let app = XCUIApplication()
-    app.launch()
-
-    let usernameField = app.textFields["Username"]
-    let passwordField = app.secureTextFields["Password"]
-
-    usernameField.tap()
-    XCTAssertTrue(usernameField.hasFocus)
-
-    // Tab to next field
-    usernameField.typeText("\t")
-    XCTAssertTrue(passwordField.hasFocus)
-}
-```
+@MainActor
+final class AccountScreenAccessibilityTests: XCTestCase {
+    private func launchedApp() -> XCUIApplication {
+        let app = XCUIApplication()
+        app.launch()
+        return app
+    }
 
-### Testing Custom Actions
+    func testControlsExposeLabels() {
+        let app = launchedApp()
+        let logout = app.buttons["Sign out"]
+        XCTAssertTrue(logout.exists, "Sign out button should be exposed")
+        XCTAssertTrue(logout.isEnabled, "Sign out button should be enabled")
 
-```swift
-func testSwipeToDeleteAlternative() throws {
-    let app = XCUIApplication()
-    app.launch()
+        let firstRow = app.cells.element(boundBy: 0)
+        XCTAssertTrue(firstRow.exists)
+        XCTAssertTrue(firstRow.buttons["Remove device"].exists)
+        XCTAssertFalse(firstRow.label.isEmpty, "Grouped row should read as one label")
+    }
 
-    let cell = app.cells["task-buy-groceries"]
-    XCTAssertTrue(cell.exists)
+    func testTabMovesBetweenFields() {
+        let app = launchedApp()
+        let email = app.textFields["Email"]
+        let password = app.secureTextFields["Password"]
+        email.tap()
+        XCTAssertTrue(email.hasFocus)
+        email.typeText("\t")
+        XCTAssertTrue(password.hasFocus)
+    }
 
-    // Verify accessibility identifier is set for test targeting
-    XCTAssertEqual(cell.identifier, "task-buy-groceries")
+    func testRowKeepsItsIdentifier() {
+        let app = launchedApp()
+        let row = app.cells["device-row-primary"]
+        XCTAssertTrue(row.exists)
+        XCTAssertEqual(row.identifier, "device-row-primary")
+    }
 }
 ```
+
+The identifier check matters because UI tests and custom-action tests target
+rows by accessibility identifier.