@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,117 +1,147 @@
 # Media Accessibility
 
-Accessibility patterns for audio and video content using AVFoundation.
+Back to [SKILL.md](../SKILL.md).
 
-## Contents
+How to make audio and video accessible with AVFoundation: tagging and choosing
+caption and audio-description tracks, following system settings, and building
+player controls that assistive technologies can use.
 
-- [Closed Captions and Subtitles](#closed-captions-and-subtitles)
-- [SwiftUI VideoPlayer](#swiftui-videoplayer)
-- [Custom Player Controls](#custom-player-controls)
+## Captions, SDH and subtitles
 
-## Closed Captions and Subtitles
+AVFoundation marks accessibility-related tracks with media characteristics
+(`AVMediaCharacteristic`,
+https://developer.apple.com/documentation/avfoundation/avmediacharacteristic).
 
-### AVMediaCharacteristic Tags
+| Characteristic | Meaning |
+|---|---|
+| `.transcribesSpokenDialogForAccessibility` | Text of what is said, as captions or SDH, for viewers who are deaf or hard of hearing |
+| `.describesMusicAndSoundForAccessibility` | The text track also covers music and sound effects, not just speech |
+| `.describesVideoForAccessibility` | An audio track that narrates the picture for viewers who are blind or have low vision |
+| `.easyToRead` | Captions written in simpler language, for cognitive accessibility |
+| `.containsOnlyForcedSubtitles` | Only the forced lines, shown where the content's language differs from the device's |
+| `.languageTranslation` | Subtitles translating speech into another language |
 
-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
+## Picking an accessible caption track
 
 ```swift
 import AVFoundation
 
-let asset = AVURLAsset(url: videoURL)
-let group = try await asset.load(.mediaSelectionGroup(forMediaCharacteristic: .legible))
+@MainActor
+func makeCaptionedItem(for movieURL: URL) async throws -> AVPlayerItem {
+    let movie = AVURLAsset(url: movieURL)
+    let item = AVPlayerItem(asset: movie)
 
-if let group {
-    // Find the closed caption option
-    let ccOptions = AVMediaSelectionGroup.mediaSelectionOptions(
-        from: group.options,
-        with: .transcribesSpokenDialogForAccessibility
+    guard let legible = try await movie.loadMediaSelectionGroup(for: .legible) else {
+        return item
+    }
+    let sdhOptions = AVMediaSelectionGroup.mediaSelectionOptions(
+        from: legible.options,
+        withMediaCharacteristics: [.transcribesSpokenDialogForAccessibility]
     )
-
-    if let ccOption = ccOptions.first {
-        let playerItem = AVPlayerItem(asset: asset)
-        playerItem.select(ccOption, in: group)
+    if let sdh = sdhOptions.first {
+        item.select(sdh, in: legible)
     }
+    return item
 }
 ```
 
-### Audio Descriptions
+`AVPlayerItem` is a main-actor class. Its `select(_:in:)` is exempt only when
+the deployment target is iOS 16 or later, so the function is `@MainActor` to
+build for older targets too.
 
-```swift
-let adGroup = try await asset.load(.mediaSelectionGroup(forMediaCharacteristic: .audible))
+## Picking an audio description track
 
-if let adGroup {
-    let adOptions = AVMediaSelectionGroup.mediaSelectionOptions(
-        from: adGroup.options,
-        with: .describesVideoForAccessibility
-    )
+Same approach on the audible group:
 
-    if let adOption = adOptions.first {
-        playerItem.select(adOption, in: adGroup)
+```swift
+@MainActor
+func enableAudioDescription(on item: AVPlayerItem, source: AVAsset) async throws {
+    guard let audible = try await source.loadMediaSelectionGroup(for: .audible) else { return }
+    let described = AVMediaSelectionGroup.mediaSelectionOptions(
+        from: audible.options,
+        withMediaCharacteristics: [.describesVideoForAccessibility]
+    )
+    if let track = described.first {
+        item.select(track, in: audible)
     }
 }
 ```
 
-### System Accessibility Settings
+## Following the system 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.
+When a user turns on captions or audio descriptions in Settings >
+Accessibility > Subtitles & Captioning, `AVPlayer` picks matching tracks on its
+own. Select options by hand only when you build your own media-selection UI.
 
-Check user preferences:
+To read the caption preference yourself:
 
 ```swift
 import MediaAccessibility
 
-let captioningEnabled = MACaptionAppearanceIsDisplayedAutomatically(.user)
+let displayType = MACaptionAppearanceGetDisplayType(.user)
+let captionsShowByDefault = displayType == .alwaysOn || displayType == .automatic
 ```
 
-## SwiftUI VideoPlayer
+UIKit apps can also check `UIAccessibility.isClosedCaptioningEnabled` and
+observe `UIAccessibility.closedCaptioningStatusDidChangeNotification`.
 
-SwiftUI's `VideoPlayer` inherits AVPlayer's automatic accessibility track
-selection:
+## SwiftUI `VideoPlayer`
+
+`VideoPlayer` from AVKit wraps `AVPlayer`, so it gets the same automatic track
+selection.
 
 ```swift
 import AVKit
 import SwiftUI
 
-struct AccessibleVideoView: View {
-    let player: AVPlayer
+struct LessonPlayer: View {
+    let lessonPlayer: AVPlayer
+    let lessonTitle: String
 
     var body: some View {
-        VideoPlayer(player: player)
-            .accessibilityLabel("Training video")
-            .accessibilityHint("Double-tap to play or pause")
+        VideoPlayer(player: lessonPlayer)
+            .accessibilityLabel("Video: \(lessonTitle)")
+            .accessibilityHint("Plays or pauses the lesson")
     }
 }
 ```
 
-## Custom Player Controls
+## Custom player controls
 
-When building custom video controls, ensure:
+A custom transport bar has to provide what the system player gives you for
+free:
 
-- 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
+- play/pause, seek and volume are focusable and labelled;
+- current time and duration are spoken when focus reaches them;
+- a captions toggle exists and is labelled;
+- the scrubber reports the time position through `accessibilityValue`;
+- controls stay visible and reachable while captions are on screen.
 
 ```swift
-Button(action: toggleCaptions) {
-    Image(systemName: captionsEnabled ? "captions.bubble.fill" : "captions.bubble")
+struct CaptionsButton: View {
+    @Binding var captionsOn: Bool
+
+    var body: some View {
+        Button(action: { captionsOn.toggle() }) {
+            Image(systemName: "captions.bubble")
+                .symbolVariant(captionsOn ? .fill : .none)
+        }
+        .accessibilityLabel(captionsOn ? "Captions on" : "Captions off")
+        .accessibilityHint("Turns subtitles and captions on or off")
+    }
+}
+
+struct Scrubber: View {
+    @Binding var position: Double      // seconds
+    let duration: Double
+
+    var body: some View {
+        Slider(value: $position, in: 0...duration)
+            .accessibilityLabel("Playback position")
+            .accessibilityValue(
+                "\(Duration.seconds(position).formatted(.time(pattern: .minuteSecond))) of "
+                + "\(Duration.seconds(duration).formatted(.time(pattern: .minuteSecond)))"
+            )
+    }
 }
-.accessibilityLabel(captionsEnabled ? "Captions on" : "Captions off")
-.accessibilityHint("Toggles closed captions")
 ```

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

@@ -1,141 +1,205 @@
 # 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
+Back to [SKILL.md](../SKILL.md).
+
+App Store Connect lets a developer state which accessibility features an app
+supports, and the App Store shows those statements on the product page. A
+person can then judge, before installing, whether the app will work with the
+way they use their device.
+
+Apple's help pages (App Store Connect Help, section "Manage app
+accessibility"):
+
+- Overview:
+  https://developer.apple.com/help/app-store-connect/manage-app-accessibility/overview-of-accessibility-nutrition-labels
+- Managing the labels:
+  https://developer.apple.com/help/app-store-connect/manage-app-accessibility/manage-accessibility-nutrition-labels
+
+## The nine categories
+
+There are nine labels today. Each one below says what a user can expect when
+it is shown, and what the app has to do to earn it.
+
+1. **VoiceOver.** A blind user can find, understand and operate everything.
+   Needs: concise labels with values and traits, a sensible reading order,
+   descriptions or text equivalents for images and charts, custom controls
+   that behave like real ones.
+2. **Voice Control.** Everything can be done by speaking. Needs: labels a
+   person can pronounce, `accessibilityInputLabels` where the label is
+   unwieldy, and custom actions for anything hidden behind a gesture.
+3. **Larger Text.** Text can grow to 200% or more where the platform supports
+   it. Needs: Dynamic Type, or an in-app text size setting that does the same
+   job, without clipping or overlapping.
+4. **Dark Interface.** The screens used for common tasks can stay dark. Needs:
+   support for system Dark Mode or an equivalent in-app theme, and no white
+   flashes along the way.
+5. **Differentiate Without Color Alone.** No meaning is carried by color on
+   its own. Needs: a second cue such as a word, shape, icon, pattern or
+   position.
+6. **Sufficient Contrast.** Text, icons, controls and state markers are easy to
+   tell from their background. Needs: semantic colors, high-contrast variants,
+   handling for Reduce Transparency, checks in both light and dark
+   appearances.
+7. **Reduced Motion.** Motion that can cause discomfort can be switched off.
+   Needs: the Reduce Motion setting respected, with parallax, spinning,
+   scaling, depth effects and continuous animation replaced by fades or still
+   frames.
+8. **Captions.** Speech and meaningful sounds in video and audio are available
+   as text. Needs: captions, SDH, subtitles or transcripts, and respect for the
+   caption preferences set in the system.
+9. **Audio Descriptions.** What happens on screen in time-based media is also
+   narrated. Needs: an audio-description track, or narration that does the
+   same job, for videos, cut scenes and cues that are only visual.
+
+Facts about where the labels appear:
+
+- Devices running iOS 26, iPadOS 26, macOS 26, tvOS 26, visionOS 26 and
+  watchOS 26, or anything newer, display them.
+- App Store Connect only asks about labels that apply to the device type in
+  question.
+
+Watch the names. Older drafts and the Settings app use different words:
+
+| Say this (label) | Not this |
+|---|---|
+| Captions | Closed Captions / SDH |
+| Sufficient Contrast | Increase Contrast |
+| Reduced Motion | Reduce Motion (that is the setting, not the label) |
+
+## Rules for claiming a label
+
+- A label is claimed only if people can get through **every** common task in
+  the app with that feature.
+- Write the common tasks down per device type, run each one with the feature
+  on, and only then fill in App Store Connect.
+- Re-check the answers as the app changes. They describe the product; they
+  are not advertising.
+- If a label is intentionally misleading or harmful, App Review may contact
+  the developer to have it corrected.
+
+Two important features have no label of their own at the moment: Switch
+Control and Full Keyboard Access. They remain part of the job, and their
+guidance lives in [SKILL.md](../SKILL.md) and the
+[code patterns](a11y-patterns.md).
+
+## What passes and what fails
 
 ### 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.
+- Short, meaningful label on every control.
+- No control type or state in the label when VoiceOver already announces it.
+- Charts and informative images come with a description or a text version.
+- Purely decorative imagery is hidden.
+- Custom controls report their role, value and action, and sit in a sensible
+  place in the reading order.
+- Changes that matter are announced with the matching 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.
+- Each common task can be finished by voice with nothing else.
+- On-screen wording and the spoken name agree wherever that is practical.
+- Where a label is long, `accessibilityInputLabels` offers a short spoken
+  version.
+- Every interactive element shows up under both the names overlay and the
+  numbers overlay.
+- Anything that needs a swipe, a long press, a hover or is otherwise hidden
+  has a route by speech alone, normally a custom accessibility action.
 
 ### 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.
+- Where the platform supports this label, text reaches 200% of its default
+  size or more.
+- Core workflows show no clipped, colliding or badly cut-off text.
+- At accessibility sizes, layouts reflow, commonly from side-by-side to
+  stacked.
+- Icons and images that work like text either scale with it or have an
+  equivalent people can perceive.
 
 ### 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.
+- With dark appearance chosen in the system or in the app, common-task
+  screens remain dark.
+- No bright splash while loading, no light interstitials, no white modal
+  sheets.
+- Try the dark theme again with the contrast settings switched on.
 
 ### 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.
+- Chart series, selection, validation, status and game or team state all
+  have a cue besides color.
+- That cue can be a word, a symbol, a shape, an ordering, a pattern or a
+  direct label.
+- Run the important flows with a grayscale or color filter on; anything that
+  becomes ambiguous depends 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.
+- Body text usually needs a ratio of at least 4.5:1 with its background.
+- Custom controls and non-text indicators of state usually need at least 3:1.
+- Check the combinations: light and dark appearance, each with Increase
+  Contrast, Bold Text and Reduce Transparency.
+- When semantic system colors cannot cover a case, custom colors get their own
+  high-contrast variants.
 
 ### 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.
+- Under Reduce Motion, turn off or replace depth simulation, vortex and
+  spinning effects, scaling, parallax, and motion along several axes or at
+  several speeds.
+- Anything that keeps moving by itself, such as an auto-advancing carousel,
+  either stops or gives the user a control to stop it.
+- The replacement still communicates the same thing: a fade, a highlight or
+  an immediate change.
 
 ### 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`.
+- Dialogue in video, and sound effects needed to follow it, are captioned.
+- Captions keep time with the audio, are easy to read and name the speaker
+  when that is not obvious.
+- Where synced captions do not fit, audio-only dialogue comes with a
+  transcript.
+- In AVFoundation the tracks carry `.transcribesSpokenDialogForAccessibility`
+  and `.describesMusicAndSoundForAccessibility`
+  (details in [media accessibility](media-accessibility.md)).
 
 ### 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.
+- The narration covers on-screen text, scene changes, instructions, story
+  beats that are only visible, and any other important visual cue.
+- It is placed in natural gaps and never talks over dialogue people need.
+- In AVFoundation the description tracks carry
+  `.describesVideoForAccessibility`.
 
-## SwiftUI Audit Example
+## Auditing a SwiftUI screen
 
 ```swift
-struct ContentView: View {
-    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+struct RecipeHeroView: View {
     @Environment(\.dynamicTypeSize) private var typeSize
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @State private var isSaved = false
+    let recipe: Recipe
 
     var body: some View {
-        VStack {
-            Image("hero")
-                .accessibilityLabel("Mountain landscape at sunset")
-
-            Text("Welcome")
-                .font(.title)
-
-            Button("Get Started") { }
-                .accessibilityHint("Opens the onboarding flow")
+        let stack = typeSize.isAccessibilitySize
+            ? AnyLayout(VStackLayout(alignment: .leading))
+            : AnyLayout(HStackLayout(alignment: .top))
+
+        stack {
+            Image(recipe.photoName)
+                .resizable()
+                .scaledToFit()
+                .accessibilityLabel(recipe.photoDescription)     // VoiceOver
+            Text(recipe.title)
+                .font(.title)                                    // Larger Text
+            Button(isSaved ? "Saved" : "Save recipe") { isSaved.toggle() }
+                .accessibilityHint("Adds this recipe to your cookbook")
         }
-        .animation(reduceMotion ? nil : .spring(), value: showContent)
+        .scaleEffect(isSaved ? 1.02 : 1)
+        .animation(reduceMotion ? nil : .spring(), value: isSaved)  // Reduced Motion
     }
 }
 ```
 
-## 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`.
+Each commented line maps to one label's pass criteria, and the layout switch
+covers the "reflows at accessibility sizes" check.