Swan's Quest, Chapter 1: Voices in the dark

Highlight

Chapter 1 of Swan’s Quest lets developers use VoiceOver and AccessibilityHints in Swift Playgrounds to add readable labels to torch graphics in caves, turning invisible levels into navigable programming challenges.

Core Content

Swan’s Quest is a four-chapter Swift Playgrounds challenge from WWDC 2020. The first chapter puts the player into a dark cave: the character can’t see the way and can’t move unless you use VoiceOver to find the torches on the screen and add meaningful labels to them. (00:41)

This setting turns accessibility issues into a playable task. Without labels, VoiceOver can only read information like “Torch two, graphic” with little context; the speaker compared this experience to a string of unnamed buttons in an app, and users can only hear “button, button, button.” (09:13)

The solution path given by Apple is very straightforward: first learn the basic navigation of VoiceOver, and then use the Accessibility APIs in the Swift Playgrounds content SDK.Graphic、Button、Sprite、Labelare inherited fromBaseGraphic, these elements can be passedaccessibilityHintsExposed to VoiceOver and other accessibility services. (11:48)

The final challenge falls on the code. You need to replace unclear torch names with descriptive onesaccessibilityLabel. When VoiceOver stops on a torch, what it reads tells the player the location, danger, or clue so the character has enough information to get through the cave to meet the Swan. (13:09)

Detailed Content

Make Playgrounds graphics accessible

(12:21) Swift Playgrounds content SDKGraphic、Button、SpriteandLabelare inherited fromBaseGraphic。BaseGraphicOptionalaccessibilityHints, which is the entry point for handing over screen elements to VoiceOver.

//  Graphic.swift

open class BaseGraphic: InternalGraphic {

    public var accessibilityHints: AccessibilityHints?

    // ...
}

Key points:

• BaseGraphicis the common foundation for these screen elements, so the same set of accessibility tips can cover multiple types of content. -accessibilityHintsIt is an optional attribute and only needs to be set on elements that need to be exposed to auxiliary services.
• The talk explicitly says that setting this property will make screen elements readable by VoiceOver and visible to other accessibility services.

Define whether VoiceOver stays and what to read

（12:32）AccessibilityHintsAt least two pieces of information are required.makeAccessibilityElementDetermines whether the VoiceOver cursor stops on this element;accessibilityLabelIs the text spoken when VoiceOver is paused.

//  AccessibilityHints.swift

public struct AccessibilityHints: Codable {

   /// Indicates a graphic should be treated as a UIAccessibilityElement by VoiceOver.
   public var makeAccessibilityElement: Bool = false

   /// Label spoken by VoiceOver for the accessible graphic (a localized character name).
   public var accessibilityLabel: String?

   // ...

}

Key points:

• makeAccessibilityElementset totrueOnly then will VoiceOver treat the graphic as a stayable element. -accessibilityLabelIt should be written for users to listen to, not for developers to debug; the torch in the cave needs to describe its location and meaning.
• The structure isCodable, which is consistent with how playground book content can be packaged, downloaded, and inspected for use.

Bind prompts to specific graphics

(12:45) The speech uses a button graphic example to illustrate the process: Create firstAccessibilityHints, create againGraphic, and finally assign the prompt to the graphic.

// Make an Accessible Graphic

import SPCCore
import SPCAccessibility

let hints = AccessibilityHints(makeAccessibilityElement: true,
                               accessibilityLabel: "Activate button to start the party")

let graphic = Graphic(name: "Let's get it Started")
graphic.accessibilityHints = hints

Key points:

• SPCCoresupplyGraphicetc. Content SDK type. -SPCAccessibilitysupplyAccessibilityHints。
• AccessibilityHints(makeAccessibilityElement: true, accessibilityLabel: ...)Complete the focus exposure and read text settings at the same time. -graphic.accessibilityHints = hintsis the action that actually puts this shape into the VoiceOver path.

Fall abstract examples into caves torch

(13:51) The actual task of Chapter 1 is to write labels for the torch in the cave. Labels are not decorative copywriting. They directly determine whether players can understand their current location in a dark scene.

// activate torch1 and torch2

cave.torch1.accessibilityHints = AccessibilityHints(makeAccessibilityElement: true,
        accessibilityLabel: "Torch next to a stairwell, where dripping water can be heard.")
cave.torch2.accessibilityHints = AccessibilityHints(makeAccessibilityElement: true,
        accessibilityLabel: "Right before the edge of the platform—be careful!")

Key points:

• cave.torch1andcave.torch2It is a specific graphic object in the level.
• Both torches are setmakeAccessibilityElement: true, so VoiceOver can pause one by one.
• The first label describes the stairs and the sound of dripping water, giving the player a clue to the location.
• The second label indicates the edge of the platform, giving players risk of action.
• This code corresponds to the requirements at the end of the speech: check the labels with your ears and change useless names into descriptive content.

Core Takeaways

• Make a VoiceOver-first level: Let players turn off visual cues and navigate only through VoiceOver tags. Why it’s worth doing: Session directly turns the dark cave into an accessible training ground, and players must rely on descriptive tags to advance. How to start: Put the keyGraphicObject settingsaccessibilityHints, then useaccessibilityLabelDescribe locations, hazards, and objectives.

• Do a one-minute deletion test for custom controls: After opening the app, use VoiceOver only to browse the first screen, and record all elements that only read “button”, “graphic” or file name. Why it’s worth doing: Speakers say unnamed buttons will turn users off in the first minute. How to get started: Start with the most common processes and add executable or understandable labels to every button, image, and custom graphic.

• Turn Swift Playgrounds book into remixable teaching materials: Provide a downloadable starting point for each exercise page, allowing learners to directly view the usage of the content SDK after opening it. Why it’s worth doing: Swan’s Quest and templates are both downloadable from the Developer app, allowing developers to take them apart and see how Apple builds the challenge. How to start: Prepare a minimal playground book and put it into one page.GraphicandAccessibilityHintstask.

• Tag sounds and environmental cues: Don’t just write the name of the object, but the information the player needs to make a decision. Why it’s worth doing: The dripping sounds, stairs, and platform edges in the cave example all help the player understand the space. How to get started: Have a corresponding VoiceOver copy for every key visual clue in your design.

• Make accessibility checks a publishing step: Before publishing Playgrounds content, turn on VoiceOver on your iPad or Mac and complete the challenge. Why it’s worth doing: The session first teaches turning on VoiceOver and basic gestures, and then requires it to be used to complete the level. How to get started: Turn on VoiceOver with Accessibility Shortcut or Command-F5, and step through the focus order and tab content.

Related Sessions

• App accessibility for Switch Control — Describes how Switch Control reuses accessibility information and reduces operating costs with focus order, custom actions, and grouping.
• Make your app visually accessible — Check whether the interface is suitable for users with more visual abilities from color, text, animation and visual settings.
• Create a seamless speech experience in your apps — Explain the boundaries between AVSpeechSynthesizer, VoiceOver announcement, and assistive technology voice settings.
• VoiceOver efficiency with custom rotors — An in-depth look at the navigation efficiency and custom rotors of VoiceOver users in complex interfaces.
• Accessibility design for Mac Catalyst — Complete accessibility details like keyboard, mouse, grouping, and inspection tools when bringing iPad apps to Mac Catalyst.