@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

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

@@ -9,7 +9,12 @@
 - 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
 
@@ -42,6 +47,18 @@ HStack {
     }
 }
 .accessibilityElement(children: .combine)
+
+// Binary custom control: prefer Toggle when possible; otherwise expose toggle state
+HStack {
+    Image(systemName: isFavorite ? "heart.fill" : "heart")
+    Text(product.name)
+}
+.onTapGesture { isFavorite.toggle() }
+.accessibilityElement()
+.accessibilityLabel("Favorite \(product.name)")
+.accessibilityValue(isFavorite ? "On" : "Off")
+.accessibilityAddTraits(.isToggle)
+.accessibilityAction { isFavorite.toggle() }
 ```
 
 ## Custom Controls and Adjustable Actions
@@ -60,6 +77,8 @@ HStack { /* custom star rating UI */ }
     }
 ```
 
+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 Management Patterns
 
 ```swift
@@ -87,17 +106,24 @@ enum A11yFocus: Hashable { case nameField, emailField, submitButton }
 
 ```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 {
-    if dynamicTypeSize.isAccessibilitySize {
-        VStack(alignment: .leading) { icon; textContent }
-    } else {
-        HStack { icon; textContent }
+    Group {
+        if dynamicTypeSize.isAccessibilitySize {
+            VStack(alignment: .leading) { icon; textContent }
+        } else {
+            HStack { icon; textContent }
+        }
     }
+    .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.
+
 ## Custom Rotors
 
 ```swift
@@ -129,6 +155,61 @@ UIAccessibility.post(notification: .layoutChanged, argument: targetView)
 UIAccessibility.post(notification: .screenChanged, argument: newScreenView)
 ```
 
+## AppKit Accessibility Patterns
+
+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.
+
+### Custom NSView with role, label, value, and action
+
+```swift
+final class FavoriteToggleView: NSView {
+    var isFavorite = false {
+        didSet {
+            NSAccessibility.post(element: self, notification: .valueChanged)
+        }
+    }
+
+    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()
+        return true
+    }
+}
+```
+
+### NSAccessibilityElement for non-view items
+
+Use `NSAccessibilityElement` when an accessible item has no backing `NSView`, such as a virtual data point in a chart or a drawn annotation.
+
+```swift
+let pointElement = NSAccessibilityElement.element(
+    withRole: .button,
+    frame: pointFrame,
+    label: "March revenue",
+    parent: chartView
+)
+```
+
+### AppKit announcements and notifications
+
+```swift
+NSAccessibility.post(element: saveStatusLabel, notification: .valueChanged)
+
+NSAccessibility.post(
+    element: self,
+    notification: .announcementRequested,
+    userInfo: [
+        .announcement: "Export complete"
+    ]
+)
+```
+
+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`
@@ -138,3 +219,180 @@ UIAccessibility.post(notification: .screenChanged, argument: newScreenView)
 - Ignoring Reduce Motion, Reduce Transparency, or Increase Contrast
 - Fixed font sizes that break Dynamic Type
 - Tap targets smaller than 44x44 points
+
+## Voice Control Patterns
+
+Voice Control generates tap targets from accessibility labels. Labels must be speakable and unique within the visible screen.
+
+### accessibilityInputLabels (iOS 14+)
+
+Provide shorter spoken alternatives when the primary label is long, awkward, repeated, localized, acronym-heavy, or commonly 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"])
+```
+
+```swift
+// Navigation link with verbose label
+NavigationLink {
+    AccountSettingsView()
+} label: {
+    Label("Account and Privacy Settings", systemImage: "person.circle")
+}
+.accessibilityInputLabels(["Account", "Settings", "Privacy"])
+```
+
+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.
+
+### Speakable Label Guidelines
+
+```swift
+// Bad: emoji-only, unspeakable
+Button("❤️") { toggleFavorite() }
+
+// Good: speakable label
+Button(action: { toggleFavorite() }) {
+    Image(systemName: "heart.fill")
+}
+.accessibilityLabel("Favorite")
+
+// Bad: duplicate labels on same screen
+ForEach(items) { item in
+    Button("Edit") { edit(item) }  // Voice Control can't distinguish
+}
+
+// Good: unique labels
+ForEach(items) { item in
+    Button("Edit") { edit(item) }
+        .accessibilityLabel("Edit \(item.name)")
+}
+```
+
+## Switch Control Patterns
+
+Switch Control scans elements sequentially. Reduce scan stops with grouping and provide custom actions for gesture-based interactions.
+
+### Custom Actions for Gesture Alternatives
+
+```swift
+// Swipe-to-delete row: Switch Control can't swipe
+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) }
+    .accessibilityAction(named: "Add to Album") { addToAlbum(photo) }
+    .accessibilityAction(named: "Delete") { deletePhoto(photo) }
+```
+
+### Grouping for Scan Efficiency
+
+```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: "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`.
+
+- 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.
+
+## Automated Accessibility Testing
+
+Use `XCUIElement` attributes to verify accessibility properties in UI tests.
+
+### Verifying Labels and Identifiers
+
+```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")
+}
+```
+
+### Testing Focus and Selection State
+
+```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)
+}
+```
+
+### Testing Custom Actions
+
+```swift
+func testSwipeToDeleteAlternative() throws {
+    let app = XCUIApplication()
+    app.launch()
+
+    let cell = app.cells["task-buy-groceries"]
+    XCTAssertTrue(cell.exists)
+
+    // Verify accessibility identifier is set for test targeting
+    XCTAssertEqual(cell.identifier, "task-buy-groceries")
+}
+```

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

@@ -0,0 +1,117 @@
+# Media Accessibility
+
+Accessibility patterns for audio and video content using AVFoundation.
+
+## Contents
+
+- [Closed Captions and Subtitles](#closed-captions-and-subtitles)
+- [SwiftUI VideoPlayer](#swiftui-videoplayer)
+- [Custom Player Controls](#custom-player-controls)
+
+## Closed Captions and Subtitles
+
+### AVMediaCharacteristic Tags
+
+AVFoundation uses media characteristics to identify accessibility tracks:
+
+Docs: [AVMediaCharacteristic](https://sosumi.ai/documentation/avfoundation/avmediacharacteristic)
+
+| Characteristic | Purpose |
+| -------------- | ------- |
+| `.transcribesSpokenDialogForAccessibility` | Captions/SDH  -  transcribes dialog for deaf or hard of hearing users |
+| `.describesMusicAndSoundForAccessibility` | Captions that include descriptions of music and sound effects |
+| `.describesVideoForAccessibility` | Audio descriptions  -  narrates visual content for blind or low-vision users |
+| `.easyToRead` | Simplified captions for cognitive accessibility |
+| `.containsOnlyForcedSubtitles` | Subtitles that display only when content differs from the device language |
+| `.languageTranslation` | Subtitles providing a language translation |
+
+### Selecting Accessible Media
+
+```swift
+import AVFoundation
+
+let asset = AVURLAsset(url: videoURL)
+let group = try await asset.load(.mediaSelectionGroup(forMediaCharacteristic: .legible))
+
+if let group {
+    // Find the closed caption option
+    let ccOptions = AVMediaSelectionGroup.mediaSelectionOptions(
+        from: group.options,
+        with: .transcribesSpokenDialogForAccessibility
+    )
+
+    if let ccOption = ccOptions.first {
+        let playerItem = AVPlayerItem(asset: asset)
+        playerItem.select(ccOption, in: group)
+    }
+}
+```
+
+### Audio Descriptions
+
+```swift
+let adGroup = try await asset.load(.mediaSelectionGroup(forMediaCharacteristic: .audible))
+
+if let adGroup {
+    let adOptions = AVMediaSelectionGroup.mediaSelectionOptions(
+        from: adGroup.options,
+        with: .describesVideoForAccessibility
+    )
+
+    if let adOption = adOptions.first {
+        playerItem.select(adOption, in: adGroup)
+    }
+}
+```
+
+### System Accessibility Settings
+
+AVPlayer automatically selects captioned/described tracks when the user
+enables these in Settings → Accessibility → Subtitles & Captioning. You don't
+need manual selection unless providing a custom media selection UI.
+
+Check user preferences:
+
+```swift
+import MediaAccessibility
+
+let captioningEnabled = MACaptionAppearanceIsDisplayedAutomatically(.user)
+```
+
+## SwiftUI VideoPlayer
+
+SwiftUI's `VideoPlayer` inherits AVPlayer's automatic accessibility track
+selection:
+
+```swift
+import AVKit
+import SwiftUI
+
+struct AccessibleVideoView: View {
+    let player: AVPlayer
+
+    var body: some View {
+        VideoPlayer(player: player)
+            .accessibilityLabel("Training video")
+            .accessibilityHint("Double-tap to play or pause")
+    }
+}
+```
+
+## Custom Player Controls
+
+When building custom video controls, ensure:
+
+- Play/pause, seek, and volume controls are all focusable and labeled
+- Current time and duration are announced on focus changes
+- Captions toggle is available and labeled
+- Progress slider uses `accessibilityValue` to announce time position
+- Controls remain visible/accessible when captions overlay is active
+
+```swift
+Button(action: toggleCaptions) {
+    Image(systemName: captionsEnabled ? "captions.bubble.fill" : "captions.bubble")
+}
+.accessibilityLabel(captionsEnabled ? "Captions on" : "Captions off")
+.accessibilityHint("Toggles closed captions")
+```

package/pipeline/skills/shared/external/ios-accessibility/references/nutrition-labels.md

@@ -0,0 +1,141 @@
+# App Store Accessibility Nutrition Labels
+
+App Store Connect lets you declare which accessibility features your app
+supports. These labels appear on the product page and help users find apps
+that support their needs before they download.
+
+Docs:
+- [Overview of Accessibility Nutrition Labels](https://developer.apple.com/help/app-store-connect/manage-app-accessibility/overview-of-accessibility-nutrition-labels)
+- [Manage Accessibility Nutrition Labels](https://developer.apple.com/help/app-store-connect/manage-app-accessibility/manage-accessibility-nutrition-labels)
+
+## Contents
+
+- [Current Label Categories](#current-label-categories)
+- [Claim Rule](#claim-rule)
+- [Pass / Fail Criteria](#pass--fail-criteria)
+- [SwiftUI Audit Example](#swiftui-audit-example)
+- [Related Non-Label Accessibility Work](#related-non-label-accessibility-work)
+
+## Current Label Categories
+
+Apple's current App Store Accessibility Nutrition Labels are:
+
+| Label | What It Means | Key Implementation |
+|-------|---------------|-------------------|
+| **VoiceOver** | Users can navigate, understand, and operate the app with VoiceOver | Concise labels, values, traits, logical order, alternatives for images/charts, accessible custom controls |
+| **Voice Control** | Users can navigate and operate the app with voice commands | Speakable visible/accessibility labels, `accessibilityInputLabels`, custom actions for hidden or gesture-only behavior |
+| **Larger Text** | Text can scale to at least 200% where supported | Dynamic Type or an equivalent in-app scaling control, layouts that avoid clipping and overlap |
+| **Dark Interface** | The app can keep common-task UI dark | System Dark Mode or an equivalent dark mode without bright flashes in common tasks |
+| **Differentiate Without Color Alone** | Color is not the only way to convey information | Text, shape, icon, position, or pattern alternatives for color-coded state and data |
+| **Sufficient Contrast** | Text, icons, controls, and state indicators have enough contrast | Semantic colors, high-contrast variants, Reduce Transparency handling, contrast checks in light and dark appearances |
+| **Reduced Motion** | Problematic motion can be reduced or replaced | Respect Reduce Motion; replace parallax, spinning, scaling, depth, and ongoing motion with fades or static states where appropriate |
+| **Captions** | Dialogue and relevant sounds are available as text for video or audio content | Captions, SDH, subtitles, or transcripts; detect and honor system caption settings |
+| **Audio Descriptions** | Visual time-based content has narrated descriptions | Audio description tracks or equivalent narration for video, cut scenes, and visual-only cues |
+
+Apple states these labels appear on Apple devices running iOS 26, iPadOS 26,
+macOS 26, tvOS 26, visionOS 26, and watchOS 26 or later. App Store Connect asks
+only for labels that apply to the device type.
+
+## Claim Rule
+
+Only claim a label when users can complete all common tasks of the app using
+that feature. Build a task matrix per device and test the common workflows
+before answering in App Store Connect.
+
+Keep claims accurate over time and do not treat App Store accessibility answers
+as marketing claims. Apple notes that App Review may contact developers to
+update intentionally misleading or harmful accessibility labels.
+
+## Pass / Fail Criteria
+
+### VoiceOver
+
+- Every interactive element has a concise, meaningful label.
+- Labels avoid control types and state words that VoiceOver already announces.
+- Images and charts provide useful descriptions or text alternatives.
+- Decorative images are hidden.
+- Custom controls expose role, value, action, and traversal order.
+- Dynamic content that matters is announced with the appropriate accessibility notification.
+
+### Voice Control
+
+- Common tasks work using only voice commands.
+- Visible labels and Voice Control names match whenever practical.
+- `accessibilityInputLabels` provide short spoken alternatives for long labels.
+- "Show Names" and "Show Numbers" expose all interactive elements.
+- Swipes, long presses, hover-only controls, and hidden actions have a speech-only path, usually through custom accessibility actions.
+
+### Larger Text
+
+- Text reaches at least 200% of the default size where the platform supports the label.
+- Main workflows avoid clipped, overlapped, or severely truncated text.
+- Layouts adapt at accessibility text sizes, often by switching from horizontal to vertical composition.
+- Meaningful icons or text-like graphics scale or have an equivalent perceivable alternative.
+
+### Dark Interface
+
+- Common-task screens remain dark when the user selects a dark appearance or the app's dark setting.
+- Bright loading flashes, interstitials, and modal surfaces are avoided.
+- Dark mode is tested together with sufficient contrast settings.
+
+### Differentiate Without Color Alone
+
+- Status, validation, selection, chart series, and game/team state never rely on color alone.
+- Use text, symbols, shape, order, pattern, or direct labels in addition to color.
+- Test important workflows with grayscale or color filters to find hidden reliance on color.
+
+### Sufficient Contrast
+
+- Most text meets generally accepted contrast guidance, commonly 4.5:1 against its background.
+- Non-text state indicators and custom controls have sufficient contrast, commonly 3:1.
+- Test light mode, dark mode, Increase Contrast, Bold Text, and Reduce Transparency combinations.
+- Custom colors provide high-contrast variants when semantic system colors are not enough.
+
+### Reduced Motion
+
+- Disable or replace parallax, spinning, scaling, vortex, multi-axis, multi-speed, and depth-simulating motion when Reduce Motion is enabled.
+- Stop ongoing motion such as auto-advancing carousels or provide a user control to stop it.
+- Preserve meaning when replacing motion; use fades, highlights, or instant transitions for state changes.
+
+### Captions
+
+- Video dialogue and comprehension-relevant sound effects are captioned.
+- Captions are synchronized, readable, and identify speakers where needed.
+- Audio-only dialogue has a transcript when time-synchronized captions do not apply.
+- AVFoundation media uses appropriate characteristics such as `.transcribesSpokenDialogForAccessibility` and `.describesMusicAndSoundForAccessibility`.
+
+### Audio Descriptions
+
+- Visual-only story, instructions, scene changes, on-screen text, and important cues are narrated.
+- Descriptions fit natural pauses and do not obscure essential dialogue.
+- AVFoundation media uses `.describesVideoForAccessibility` for audio description options.
+
+## SwiftUI Audit Example
+
+```swift
+struct ContentView: View {
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.dynamicTypeSize) private var typeSize
+
+    var body: some View {
+        VStack {
+            Image("hero")
+                .accessibilityLabel("Mountain landscape at sunset")
+
+            Text("Welcome")
+                .font(.title)
+
+            Button("Get Started") { }
+                .accessibilityHint("Opens the onboarding flow")
+        }
+        .animation(reduceMotion ? nil : .spring(), value: showContent)
+    }
+}
+```
+
+## Related Non-Label Accessibility Work
+
+Switch Control and Full Keyboard Access remain important app accessibility
+requirements, but they are not current App Store Accessibility Nutrition Label
+categories. Keep their implementation guidance in `SKILL.md` and
+`references/a11y-patterns.md`.