I’m going to be honest — the first time I used VoiceOver on macOS, I felt overwhelmed and felt like there was quite the learning curve. But a lot of that was due to me not having taken the time to think about screen readers in an environment away from touch screen, and I had many assumptions about that being “the way” to navigate using a screen reader.

Humble Beginnings

No touch screen it is. On desktop, the keyboard is going to be our main form of input.

To turn on VoiceOver, use ⌘ (command) + F5, or ⌘ + triple-click Touch ID. Do the same to turn it off again.

At the core of VoiceOver on macOS, you have what’s called the VoiceOver modifier. By default, it’s set to ⌃⌥ (control + option) or ⇪ (Caps Lock).

Like you’d use control, option, command etc. on their own or in combinations for keyboard shortcuts, you use the VoiceOver modifier together with other keys, like arrows, to navigate. Just like keyboard shortcuts!

You’ll often see “VoiceOver modifier” be referred to simply as “VO”. “VO right arrow”, then, may refer to using your VoiceOver modifier keys together with right arrow.

Where on touch screens, we use a single-finger right swipe to navigate to an item on the right, on macOS we’d do that with VO + right arrow.

To navigate to an item on the left, use VO + left arrow.

Hierarchy

On touch screen devices, you’re likely used to a flat navigation style. This is the default. There is also an option for grouped navigation, which navigates between groups (I think this translates to navigating by container), then requires a two-finger swipe right to “enter” the group.

A two-finger swipe left exits the group.

On macOS, the grouping behavior by default is similar to grouped. What that means in practice is you’ll have to enter and exit groups, like scroll views by default.

This is also why it is important to label your scoll views! The Messages app’s detail view is labeled “Conversations”, for example.

To enter a group, use VO + ⇧ (shift) + down arrow. Exiting a group? VO + ⇧ + up arrow. But you guessed that.

Activating elements like a button is done using VO + space.

What’s Next

This should allow you to get started using VoiceOver on macOS. But there’s more! Way more. Rotors and Commands are just two of them.

Furthermore, VoiceOver Utility is your one-shop-stop to set up VoiceOver to your liking, from the Voice used, to the Caption Panel showing, to the Braille Panel, to setting up VoiceOver to use with a trackpad.

Go and try it out — I’d love to hear how you get on!

Everything is Accessibility

Before we look into how we can approach working on accessibility, I want to look at what constitutes accessibility. And what does not.

The bad thing: that’s not a straightforward question to answer. The good thing: the fact it’s not straightforward to answer is actually a good problem to have.

When thinking of assistive technology like screen readers or braille input and output, I assume it’s straightforward we’re talking about ‘accessibility’.

When we talk about voice assistants like Siri, or dark mode, or haptics (which in SwiftUI are now a broader “sensory feedback” type that extends beyond devices with a haptic engine), or even App Intents that expose app information to the system… are those accessibility?

Some might say yes to all of them, or a hesitant yes. Or perhaps “no” to some. And that’s fair — there’s no right answer here, I believe. But in essence, it does all impact the eventual accessibility of your product for a wide(r) range of users.

Supporting these kinds of functionality makes better products for everyone.

And yes — supporting all of this is a lot of work. But we don’t have to do it all in one go. We can start with dark mode and sensory feedback. Labels and traits to improve the VoiceOver experience. And then we can expand on that in the future to improve the experience for Voice Control users, building on top of the labels and traits we implemented for VoiceOver.

Reasoning about Assistive Technology

“This all sounds great!”, you might think. “But now what?”

I’ve heard this a lot. And it’s a fair question. Especially in accessibility, I’ve come to the realization that part of what makes it difficult to support is that a lot of people don’t have a clear picture of what accessibility entails. Or, said another way, “don’t know what they don’t know”.

This means there’s a barrier to overcome. Let’s look at some ways that make it easier to overcome said barrier.

Navigating by Voice (Voice Control)

Using Voice Control, we can navigate a device by voice. Users with motor difficulties might rely on this assistive technology, but beyond that — it can help us get a sense of certain¹ labels within our product.

Seeing some of these labels might already help us get a first insight into issues. If any of the labels don’t make sense, or would be hard to read out loud, that would be an indication we can improve things.

Another thing that’s interesting here is it only showing the first word within a label. For example, in the second image, there’s a “Feels Like” within a segmented control, but its label is shown as “Feels”. This makes it easier to activate an item, but at the same time makes it feel less natural.

Alas, we can see a bunch of labels, giving us a visual overview of accessibility pertaining Voice Control in our app. This includes some unexpected ones that are likely bugs — like the “Currently” label on the current temperature in the detail view. This is not an interactive element, and thus should not be exposed to Voice Control. Similar to “Chart” at the top of the temperature chart, which is also non-interactive.

All in all, it is a great way to get an initial feeling for an assistive technology where navigating is likely to feel quite natural — it does not require learning special gestures, for example.

This document describes how to use Voice Control on iOS.
This document describes how to use Voice Control on macOS.

Hover Text (macOS)

Hover Text allows you to show a large window of the selected element — which goes beyond direct text elements.

Not only is this a great non-intrusive way to get a better idea of accessibility, it’ll also come in handy when you’re on a video call and a certain element is quite hard to read for the person on the other end.

So that’s Hover Text. You can quite quickly navigate an application and get an idea of its labels beyond interactive-only elements (like with Voice Control).

The first image showing hover text over a button — with an expected label. The second image showing a… not so great label. Additionally, this can likely be hidden as an accessibility element, as it doesn’t convey information to VoiceOver users — it’s decorative.

You can enable Hover Text on macOS in System Settings > Accessibility > Hover Text. You can change its activation modifier if you wish.

Caption Panel

Using VoiceOver, the caption panel is a neat way to visualize its output. Useful to verify what you think VoiceOver might have said, or if you want to test it without requiring headphones or having the device’s speaker on.

On iOS, turn this on or off from Settings > Accessibility > VoiceOver, where you’ll find a switch near the bottom of the screen.

On macOS, open VoiceOver Utility > Visuals > Show caption panel. Additionally, you can enable the Braille Panel in the same place.

Bonus: Screen Curtain

Alright, this last one might not really be making accessibility more accessible like the others. But it does make accessibility more tangible in the context of a screen reader.

Most users of screen readers are blind users or users with low vision.

For the former group… you don’t actually require the screen to be on. And that’s Screen Curtain. There for three reasons: one is privacy — no screen output means others can’t see what you’re doing. The second is efficiency — no pixels to power and spend battery charge on.

And, third: it’s a great way to “not cheat” whilst using VoiceOver. It’s likely you’ll still use visual cues to navigate the screen using VoiceOver, especially to get out of situations where you feel stuck. But with Screen Curtain, that becomes impossible. A “hardcore” way to understand your app’s accessibility and how to navigate it.

This document describes how to turn Screen Curtain on and off.

Closing Thoughts

Accessibility has a steep learning curve, but I hope these tools give you a better idea where you can start. As well as a way to encourage others to get an introduction to accessibility without having to dive deep into assistive technologies. Let me know how you get on!

I stand by this! Things like labels, traits and values get you most of the way there for Voice Control. We optimize for Voice Control (and Full Keyboard Access) using input labels, and then we can further optimize Full Keyboard Access verifying our keyboard support.

But with this great power comes great responsibility…

A while ago, I was building a component to allow users to participate in a survey, and it was an example where I ran into issues trying to optimize for both VoiceOver and Voice Control, because the two systems lean on each other.

Building a survey component

Based on certain conditions, we’d show a cell that would show a title, a description, and two buttons: one to launch the survey, and another to dismiss the survey cell. Simplified code as follows:

VStack {
    VStack {
        title
        description
    }
    surveyButton
}
.overlay(alignment: .topTrailing) {
    dismissButton
}

With the component looking something like this¹:

Initially, all elements were their own elements. The title, description, and two buttons were separate.

The accessibility tree looked like this:

Dismiss, button
>
We'd love your feedback
>
What do you think of Save for Later?
>
Take Survey, button

Let’s make sure the dismiss button is navigated to last using .accessibilitySortPriority:

dismissButton
    // To make sure assistive technologies navigate to the dismiss button
    // within this view last, essentially ignoring the heuristic of this
    // being the "first" element in the view.
    .accessibilitySortPriority(-1)

Then, I combined the title and description into one label. A VoiceOver user would be unlikely to “skip” the description at any point “on their way” to the button anyway, and the title and description together gave a better idea of what button the user would interact with next.

VStack {
    VStack {
        title
        description
    }
    .accessibilityElement(children: .combine)
    // outer VStack stuff...
}

So far so good — a reminder that Voice Control only exposes elements that are buttons, so this would affect VoiceOver but not Voice Control.

Optimizing for VoiceOver

To make a further improvement, I wanted to expose the two buttons as actions, making “take survey” the default action and “dismiss” a secondary one. In that way, we wouldn’t have to deal with modifying the sort order to make sure the survey button would preceed the (visually preceding) dismiss button.

Additionally, it would collapse the more complex cell into one element for the user to interact with.

VStack {
    VStack {
        title
        description
    }
    surveyButton
}
.overlay(alignment: .topTrailing) {
    dismissButton
}
.accessibilityElement(children: .combine)

Talking about “with great power comes great responsibility”… the .accessibilityElement(children: .combine) is technically all we need here, but restricts optimizations.

In this example, it does two major things:

• It groups the Text children to form its label, like we did with the same code on the inner VStack previously.
• It exposes the Button children as accessibility actions.

Great..? Well, I’m not entirely sure what users that use VoiceOver would prefer, but I was planning to schedule a user interview to find out.

… planning to schedule?

Well, yes. As after making this change, it dawned on me this might make Voice Control interaction awkward.

Voice Control

In VoiceOver, this could be spoken as “We’d love your feedback, What do you think of Save for Later?, button, actions available”. It would indicate that the text is a button that can be interacted with, and that the button has (other) actions.

But for Voice Control, we now have a… challenge. How can we interact with either button, now that we have just one element?

Technically, the whole element is a button. So we could try to activate something that way? But what would that something be and do?

Well, Voice Control will generate an event… in the center of the view. Which in our case is just some text. Not the dismiss button, not the survey button.

Well, that’s awkward.

Now, technically the user could in this case say “show actions for [element]”, for which we can at least optimize the [element], which is now that long label:

VStack {
    // element details
}
.overlay(alignment: .topTrailing) {
    dismissButton
}
.accessibilityElement(children: .combine)
.accessibilityInputLabels(["Take survey"])

Now the user can at least say “show actions for take survey”, and they would then be able to either take the survey or dismiss it.

Unfortunately, the only way to visually indicate there are actions for an element is to use “show numbers”. And only on iOS² does it indicate a “double arrow”… which as far as I know is undocumented. In other words, a user would somehow need to be using “show numbers” (and not “show labels”) and know what this double arrow represents.

But that leaves us with “Take survey” as a “ghost” action. Despite being the most prominent option, it now doesn’t actually do anything.

I can see a world where “Take survey” would result in actually showing the two underlying actions, but that comes with its own array of problems, so perhaps it’s not that great of an idea in practice.

And so with that, I decided to revert to the version that does combine title and description, but otherwise leaves the component alone. Perhaps not the “perfect” solution for VoiceOver, but a decent one that then also allows for a great Voice Control experience.

VStack {
    VStack {
        title
        description
    }
    .accessibilityElement(children: .combine)
    surveyButton
}
.overlay(alignment: .topTrailing) {
    dismissButton
        // To make sure assistive technologies navigate to the dismiss button
        // within this view last, essentially ignoring the heuristic of this
        // being the "first" element in the view.
        .accessibilitySortPriority(-1)
}

Closing thoughts

It’d be great if we can see some additional affordances in Voice Control that make it a bit easier to work with — especially as a user. Documented indications for actions that work across platforms, for example.

But for now, we’ll have to make do with some limitations, especially when trying to optimize for multiple assistive technologies.

_{Thanks so much to Swaan for proofreading!}

There are two sessions that give a great introduction to the new framework, and I recommend checking them out:

• Meet Swift Testing
• Go further with Swift Testing

Introduction

Where with XCTest, we’d need setting up an XCTestCase subclass:

import XCTest

class MyTests: XCTestCase {
    func testFiltering() {
        // test here
    }
}

Using Swift Testing requires barely any set up at all. At it’s simplest, we can do the following:

import Testing

@Test func filtering() {
    // test here
}

And where with XCTest, we had a whole range of XCTAssert* functions, Swift Testing has one “assert” to rule them all: #expect is built using the power of macros, and is nice:

@Test func filtering() {
    let input = [1, 3, 2]
    let expected = [1, 2, 3]

    #expect(input.sorted() == expected)
}

If we’d have forgotten to call .sorted(), we’d get failure output:

@Test func filtering() {
    let input = [1, 3, 2]
    let expected = [1, 2, 3]

    #expect(input == expected)
    // Expectation failed: (input → [1, 3, 2]) == (expected → [1, 2, 3])
}

… which also works nicely with things that wouldn’t get rich diagnostics in XCTest, like .contains:

@Test func filtering() {
    let input = [1, 3, 2]

    #expect(input.contains(5))
    // Expectation failed: (input → [1, 3, 2]).contains(5)
}

Beyond the basics

Swift Testing supports parameterized testing, allowing us to pass multiple parameters to test at once, where before we’d need to define either individual test functions or loop over a sequence. What’s particularly neat about it is that Xcode makes it so you can see exactly which parameter input may have failed, and allows you to rerun that one input separately.

@Test(arguments: [1, 2, 3, 4])
func filtering(expected: Int) {
    let input = [1, 3, 2]

    #expect(input.contains(expected))
    // Expectation failed: (input → [1, 3, 2]).contains(expected → 4)
}

Which show up in the Test inspector as such:

How do I..?

Some parts you might be familiar with in XCTest have different names under Swift Testing, which may require a bit to get used to. Here’s some:

let result = try XCTUnwrap(myOptional)

// becomes

let result = try #require(myOptional)

XCTFail("You shall not pass")

// becomes

Issue.record("You shall not pass")

XCTAssertTrue(
    true, 
    file: #file, // StaticString
    line: #line // UInt
)

// becomes

#expect(
    true,
    sourceLocation: SourceLocation(
        fileID: #fileID, // String
        filePath: #filePath, // String
        line: #line, // Int
        column: #column // Int
    )
)

XCTAssertEqual(1.0, 1.0, accuracy: 0.1)

// becomes... tricky. Apple recommends to use `isApproximatelyEqual()` from
// its `swift-numerics` package.

Grouping tests

You can group tests with tags, part of the trait system of Swift Testing. You can do so across package boundaries, which makes it so you’ll probably want to create a package to define said tags, which you’d do like this:

extension Tag {
    @Tag static var subscriptions: Self
}

To apply this to a test or test suite, use

@Test(.tags(.subscriptions))

or in a group of tests

@Suite(.tags(.subscriptions))
struct Filtering {
    @Test func filter() {}
}

Tags show up in the test inspector, similar to what we saw before with parameterized tests. They can be run from there, or inspected to see if a change you made may have impacted related tests.

I don’t / can’t use Xcode 16 yet!

… bummer. That means you’ll have to wait to start using Swift Testing, although if you have the time, you could use Xcode 16 to start converting tests, and still merge them into your Xcode 15-branch like so:

#if compiler(>=6.0)
import Testing

@Test func filter() {}
#endif

… which may or may not be useful for your project. You can otherwise keep things in a separate branch.

Closing thoughts

Only having scratched the surface, it’s fun to write tests with Swift Testing. I’d recommend you try it out and see how it can clean up some of your tests, perhaps starting with those taking multiple arguments.

I’d recommend taking a look at the documentation on migrating a test from XCTest, which mentions a bunch of great comparisons between the two frameworks that’ll help get you started.

Let me know how you get on!

Not in the loop on Assistive Access? Beyond Apple’s announcement earlier this year, there’s an awesome WWDC session on Assistive Technology by none other than Allen Whearry.

⚠️ Note that Assistive Access is currently still beta software, and may have bugs that I therefore won’t judge too harshly. ⚠️

Setup

It’s interesting that the initial setup of Assistive Access is a little different than the setup for subsequent changes; the initial setup is, however, nicely guiding you and introducing certain concepts and gotchas, which is nice.

For example, you can set up the “appearance” in Assistive Access to be row-based or grid-based.

After this, we can start setting up apps.

First Party Apps

There are a few first-party apps that have been optimized for Assistive Access, by means of having fewer features and a bigger, bolder user interface. Unfortunately, this is not available for any third party apps… yet.

We can see that Calls has setup options to enable or disable certain functionalities. Note also that this “Calls” app actually combines features from both the “Phone” and “FaceTime” apps in one app — neat!

3rd Party Apps

For third party apps, I was delighted to see that, whereas they are not optimized, we can still set them up specifically for Assistive Access. For example by settings its language, and allowing access to things like Camera, Contacts, Live Activities, etc. — depending on what the app supports, of course.

Wrapping up the Setup

After setting up the apps, there’s some more screens in the initial setup, sharing some “things to know” about things that are unavailable in Assistive Access mode, like notifications, software updates and more. There’s also an explanation on how you exit Assistive Access (triple-clicking the home button; I assume this is triple-clicking the side button for devices without a home button).

… and with that, we’ve set up Assistive Access — now let’s explore it!

Assistive Access Experience

Enabling Assistive Access can be done through the Accessibility settings, or the Accessibility Shortcut after adding it there. It does not seem to work via Siri (just yet).

General

Requiring an “admin” password to enter and exit Assistive Access means users can’t accidentally exit the mode. Using the grid appearance, all we see is our apps in large tiles; no time, battery level, connectivity etc. It also seems like non-default app icons are not shown if set up.

First Party (Optimized) Apps

Messages

Optimized apps see a similar layout to the grid appearance set, creating a similar experience to the “home screen”. Like Messages here, for example.

From there, we can enter a conversation and participate in it using, for example, the emoji keyboard.

Camera

The Camera app is even cleaner and simpler than its (non-Assistive Access) counterpart. A view finder, and a “Take Photo” button. Easy as that.

Non-optimized Apps

Looking at non-optimized apps… we immediately get a sense of just how large the gap in experience is between optimized apps and those that are not. Non-optimized apps only get a “Back” button that is not context-aware, but instead always goes back to the home screen.

What’s also interesting is that iPhone-only apps run in Assistive Access mode on iPad (which admittedly is quite an edge case) seem to “emulate” an iPad environment of sorts — and that iPad emulation may lead to UI bugs and crashes.

Final Thoughts

It can be seen that this mode is still under construction as there have been many improvements during the beta cycle, like supporting dark mode, tweaking how app settings can be changed, and more. It’s got a ways to go, but I’m beyond exited by this new assistive technology and what it can do.

Furthermore, I am so proud of all the people that have worked, and are working, on this new assistive technology. You know who you are; you rock!

And now we patiently wait for some more APIs to optimize third party apps..!

_{Thanks so much to James Sherlock for proofreading!}

Hover Text

Hover Text is a macOS feature that lets you view text at larger sizes, typically using a modifier key and hovering over the text or element (hence the name). What’s neat about it, is that is will show you the accessibility label of any element, not just text, including in the iOS simulator. Meaning Hover Text can be a rather quick and frictionless way to get an idea of elements not having an accessibility label, or having an awkward one. You can find Hover Text under System Settings (or System Preferences if you’re not yet running macOS 13 Ventura) > Accessibility > Zoom > Hover Text.

And this is what Hover Text looks like in practice, here as seen in the simulator.

A neat start, but let’s take a look at macOS VoiceOver next…

macOS VoiceOver?! I’ve never used that!

Using macOS VoiceOver to test your iOS app on the simulator is a bit of a power user trick. If you build apps for iOS, there’s a chance you’re not familiar with VoiceOver on macOS — I wasn’t until joining the macOS Accessibility team at Apple. There’s a steep learning curve, which people familiar with iOS VoiceOver will probably know.

System Settings > Accessibility > VoiceOver > Open VoiceOver Training… is a good place to start, but let’s go over an even quicker quickstart.

macOS VoiceOver quickstart

To turn on VoiceOver on macOS, given a keyboard with Touch ID, hold ⌘, then triple-press the Touch ID button. You can also ask Siri to turn it on or off.

Then, as you can imagine, VoiceOver navigation is going to be quite different from iOS. No touch screen, but a keyboard to interact with things. Oh, the possibilities!

The first thing to know is there’s the so called “VoiceOver modifier” keys. By default that’ll be either Caps Lock or ⌃+⌥. I’ve gotten used to the latter. To navigate, hold your modifier key(s), and use the arrow keys. That’s like a right (or left) swipe on iOS, and honestly, you’re starting to get off to the races. Try it out!

Activating things like buttons is done with the modifiers keys and the space bar.

That concludes our quickstart for now, let’s get back to the (fun and) profit.

(Fun and) profit

Macs with Apple’s M-chips can run iOS apps on the Mac — which is practically the same thing the simulator does, and how Catalyst apps work. And so we can leverage this with the Simulator app, simply by navigating our macOS VoiceOver cursor… to our iOS app!

You can already tell the… awkward bits that come with this, underlining the importance of treating iOS devices as the source of truth in all cases. I have no idea why the VoiceOver cursor is off — it normally works okay, but apparently not in the simplest of demo applications. Rest assured, things work. We can activate the button, and we can verify VoiceOver labels and elements.

Voice Control also works, but the element position is out of whack there too, by the looks of it.

What’s neat about this, is that it gives us a little more options than with the Accessibility Inspector, although as you can see, either are going to have some tricky things to work around. Some things that the simulator can’t do, but using VoiceOver on macOS can, is to navigate and inspect AXCustomContent, for example, or to perform the “Zorro gesture”, or maybe more commonly known as the “accessibility escape” by telling Voice Control to “go back”.

An AXCustomContent example

Alright, let me also give an example using custom content, as that is something that you can’t verify with the accessibility inspector. It also requires a tiny bit more macOS VoiceOver magic. Let’s take a look first:

You might have been able to read along with the caption panel, but to show the entries for custom content, use your VoiceOver modifier keys, plus ⌘, plus /. You can then navigate through them using just arrow the up and down arrow keys, without any modifiers.

These menu-style actions are what are the equivalent of iOS Rotors. And so as you might imagine, this only scratches the surface of the capabilities of just rotors on macOS. Ah, the power of macOS VoiceOver… perhaps that’ll leave you wanting to explore it further. (Pro tip: the hints will help you gradually explore more options and actions as you come across them, like custom actions and custom content.)

With great power…

Making use of the tools we have to help ourselves is something I really like exploring. Sometimes things don’t work out, other times we take away these (little) things that can help our workflows and more. I’ve been using these tricks to drastically improve my testing workflows… and to have a lot of fun!

Whilst these tricks are a niche way of testing your iOS apps for accessibility, I feel they are great to know about and add to your toolbelt. But beware, as like (unfortunately) is also true for the accessibility inspector, only an actual iOS device is going to give you the exact experience your user has.

macOS is, as we know, quite different from iOS, and looking at the aforementioned iOS on Mac and Catalyst and how they work, they will change certain behaviors compared to on iOS. A major example is navigation: whilst on iOS we have a (mostly) flat structure, macOS knows a rich, hierarchical structure. What does that mean, you might wonder? Well, containers like table and collection views are to be drilled into. Where on iOS you’ll navigate a table view cell by cell (unless you have a (custom) rotor), on macOS you’ll be drilling into it using the VoiceOver keys plus down arrow (to enter), and up arrow (to exit).

So: always test on actual iOS devices, too, and take those as your source of truth.

And oh yeah… I’ve just been reminded how lucky we are that the iOS screen recording automatically includes Voice Control and VoiceOver sounds… which is not true for macOS. Guess I’ll add that to the pile of Feedbacks to file as a result of writing this.

I’d love to hear from you if you’ve tried this out!

Special thanks to Chris Wu, Nathan Tannar and Rob Whitaker for their proofreading and feedback!

Not that I’m speaking from experience… why’d you ask?

These things happen. And arguably, it’s OK for them to happen. Yes, there’s a miriad of things we do — conciously or not — to prevent these things from happening. In the end, however, it’s because of bugs, of issues, of changes, that we programmers are, well, programmers. We’d not be needed otherwise, I’d argue.

Fixing

One of my favorite things in programming is being able to write a piece of software that is well-defined — as well as moulding a thought, requirement, or project to become well-defined.

It’s then, with that knowledge, we can work in a structured way. We can define logic that can be tested. Well tested. With test code that not only becomes as important as the code we ship, but also as understandable, as readable.

The magic moment kicks in when an issue or (other) edge case is found — as it eventually always will, even though our software was so well-defined. We’re humans after all, and we do seem to make mistakes.

I digress… but now we can write a new test — with our now known failing input — and have that test fail. Of course. But this is great! We have a newly defined input with a certain unexpected output. We use our newfound knowledge to fix the bug, et voilà, the test passes. What a wonderful feeling.

A perfect scenario, one might argue, but one that isn’t always as straightforward. Not as straightforward to write that (as) testable code. Not as straightforward to understand the underlying issue and apply a fix. Not as straightforward to find that issue or unexpected output in the first place.

We could see the code and the accompanying test that fixes the issue as some form of “pure” documentation: you can’t argue, by reading the fix and the test, that the issue isn’t fixed. And you can logically reason about it. (Of course, this isn’t exactly true. We could introduce a new issue with our fix, of course, especially when dealing with more complex challenges. Nor should we expect anyone to take a fix — however trivial — for granted, or to understand said fix in exactly the ways our mind does).

Documentation

While our code is a form of documentation, we’re all humans, and we all think differently. Have a different perspective.

When it comes to documentation, different things work (better) for different people. There’s no one way to document things. One might prefer video content over documentation that is written. Examples can make something tangible. That oh-so-understandable code does not hold up when someone unfamiliar with code is looking into things. Or your future self, not having used that programming language in a while.

Having things documented in multiple forms can help keep things able to be picked up by different people, at their own speed, in their own way. And having that kind of track record of how we work will help us keep a better understanding of our software (this, of course, applies to much more than just fixing issues, like processes, decisions, and proposals).

Documentation, too, can help finding issues, non-expected outputs, and bugs, too. We certainly don’t always have a well-defined bug report, failing input, or other tangible information to guide us in the correct — or even a — direction. And so we should be extra careful in tracing our steps, documenting our findings, and understanding our path from an issue being flagged to understanding (and, I hope, fixing!) it.

Patching

… or, not. It just seems to happen that we’ll not always find the underlying issue, understand what’s responsible for that crash, or get the time to investigate something not criticial enough at that point in time.

What I’ve seen happen in this case, from time to time, is that rather than fixing the issue, we patch it. Whilst you could argue that patching something would also fix it, what I mean with patching is the fact of preventing the issue at hand without having a full understanding of why it happens in the first place.

For example, if we’re unexpectedly returning nil given some unknown input, we can default to returning, say, an empty string ””. If we know that sometimes we index into an array but go out of bounds, we can return early if we determine we would go out of bounds.

As we can see, however, these examples don’t fix the issue. They dodge it, move around it, ignore it. It’s that I see as a patch. And, alongside it, as something that could, down the line, cause undefined behavior — as in, it can cause us to evaluate code at a later point with input we don’t expect. Luckily for us, we have (among others) assertions to help us there.

Patching issues isn’t something objectively bad. Sometimes we deal with a complex piece of code and we’ll have to make do with what we do know. Add that extra piece of logging to help catch that gnarly input causes us problems. Write a workaround because an API that’s not in our hands causes issues.

It’s in those cases that proper documentation (and potential follow-up steps) is written. That means, first of all, to know and understand the difference between a patch and a fix. And the ideal goal of that documentation would be, as I’d argue the ideal goal of any documentation would be, is for anyone else (within reason, like others within the company, or other people in the team) to be able to go through it, learn from it, and figure out next steps.

Oh and as it turns out, doing that isn’t easy. Isn’t straightforward. Takes time, energy, experience and communication. But we can all try and learn.

Conclusion

Working on projects, we’ll all at some point have to deal with bugs, unexpected behavior, and other issues. They will all be of different magnitude and size, and we’ll have to approach them accordingly.

Whereas in cases we can be confident of a fix, and document it, in other cases fixing something isn’t straightforward, or (in the short term) feasable at all. It’s then that we may be patching issues, and making sure there’s a shared understanding of what has (not been) done, as well as providing documentation on the process and next steps, is a crucial step that should not be neglected.

Whilst possible, it was far from straightforward. In this post, I want to talk about matching the built-in behavior, by supporting the Large Content Viewer as well as the magical (as you will see later) .tabBar trait.

You can find the code from this blog post on GitHub.

Large Content Viewer

To start off, let’s take a look at what our custom tab bar looks like, and how we’ve built it.

What we’re looking at is a blank, plain UIViewController that contains a UIStackView. That stack view has four buttons added as arranged subviews.

Grand. So these are buttons, which we can tap and react on. Now, we want to make sure we can long-press these to show the large content viewer; something that comes out-of-the-box with UITabBarController. To do so, we first set the font size to one of the accessibility sizes; it will not appear otherwise.

To do so, navigate to the debug bar at the top of the debug area in Xcode, activate “Environment Overrides”, enable “Text” and set the Dynamic Type to something in the Accessibility category.

Alternatively, you can do the same in the Accessibility Inspector’s “settings” tab.

Alright, so… here we go! Long press on a button…

… and observe nothing happens. What gives?

Not All Buttons Are Created Equal

Now, Apple recommends to always prefer elements that can grow to smaller or bigger sizes. In many cases, that’s what you want — and you will not need to add support for the large content viewer, as the elements themselves grow.

But as you can imagine, this becomes tricky in certain scenarios, and a tab bar is one of them. Growing the tab bar means we’re taking up more and more screen real estate, meaning we have less space to show the rest of our app.

Hence why we want to support the Large Content Viewer for these buttons in our case.

To do so, we use the showsLargeContentViewer API that is available on UIView.

button.showsLargeContentViewer = true

Alternatively, we can also set a largeContentTitle to go alongside the viewer, indicating the title of our tab/button.

button.largeContentTitle = NSLocalizedString(
    "Camera", 
    comment: "The title describing the `Camera` tab."
)

Build and run the app and…

Oh no, it still does not work?!

Documentation to the Rescue, Kind of

showsLargeContentViewer’s documentation mentions:

For this property to take effect, the view must have a UILargeContentViewerInteraction.

… yet neither largeContentTitle nor largeContentImage’s documentation do. OK, so let’s add the interaction:

bar.addInteraction(UILargeContentViewerInteraction())

Tada!

One More Thing…

Now, there’s one more thing we can do to improve this. The largeContentImage is picked up by the UIButton’s image, but it may not really grow to take up the space in the large content viewer. Even though that’s quite a big part of why we have this in the first place. Make sure that if you need this and enable it, you may want to “preserve vector data” so that the image doesn’t get blurry when scaled up.

button.scalesLargeContentImage = true

All of the above is also neatly summed up and touched upon by Sommer Panage in the WWDC video Large Content Viewer - Ensuring Readability for Everyone.

The Tab Bar Trait

The other part of making a custom tab bar accessible, is making sure it is seen as a tab bar by assistive technologies like VoiceOver. If you’re unsure what that feels like, try out a standard tab bar in an app by navigating through it with VoiceOver; it’ll add a bunch of great information, like which tab you’re on, and that we’re dealing with a tab bar in the first place — as well as making a container element for it so it’s easier to navigate to.

Whilst in theory this seemed straightforward in my head — add a trait to those buttons — it wasn’t as easy as I’d hoped.

First of all, you don’t add a trait to the buttons themselves; instead you add a trait to the parent view — the “tab bar” if you wish. Which feels… weird. It’s certainly not something common in terms of assigning traits.

Anyway. So the documentation further mentions that

If an accessibility element has this trait, return false for isAccessibilityElement.

When I read this, on top of the unusual way of adding a trait to the parent view, a visualization of my brain would’ve been this:

Anyhow, I tried doing what the documentation said:

tabBar.accessibilityTraits.insert(.tabBar)
tabBar.isAccessibilityElement = false

… and ran the app.

Womp womp. Nothing tab bar related, even though that is what we’d expect given the documentation. Even the spoken output that is supposed to mimic VoiceOver just speaks “Camera, button”.

So, this was not… completely unexpected? I was (still) confused about how this was supposed to work in the first place. Or as I described it in the pull request once I Sommer finally found out what was going on:

The documentation says that this is how you set up a custom tab bar. You set the parent element to have the .tabBar trait, and then you set isAccessibilityElement on said parent to false. Which makes like, zero sense. The API “contract” is to not listen to anything that has isAccessibilityElement = false in terms of accessibility. Yet here it does mean something and has a side effect.

But so apart from that, things still did not seem to work. Which was like half expected, as per what I just noted. The inspector says “no bueno”, not adding the internal “tab” trait. So no idea how to debug this or look into it.

Turns out, it does actually work… only on device. Even if inspecting the device with Accessibility Inspector, it’ll still pretend that things don’t work (read: no tab trait), yet VoiceOver reads everything correctly.

sigh time to write a blog post and file a bunch of radars on this.

… seems like it all “worked” after all. Thanks (again) to Sommer (and someone at Apple) for helping me stay sane here.

Now the only thing you’d have left to do is to insert or remove the .selected trait of the “active” tab bar item.

Conclusion

Phew. Though there are a bunch of gotchas when it comes to making a custom tab bar accessible, it is certainly possible. The good thing is that it all works for the end user. The not so great thing is that implementing it isn’t straightforward, and the usual tools like the Accessibility Inspector will give you wrong information.

Hopefully this post has been helpful if you have a custom tab bar in your app that you want to make accessible!

Let me know your thoughts on this post, and if you have any questions, I’d love to help!

You can find the code from this blog post on GitHub.

… and there’s some smarts built into the system to support those cases where you’re limited on space and can’t really show a larger font.

• Getting Started With Accessibility: VoiceOver
• Improving Accessibility: VoiceOver
• Verifying VoiceOver: Accessibility Inspector
• Improving Accessibility: Voice Control
• Getting Started With Accessibility: Dynamic Type (this post)

Introduction

The typography documentation in Apple’s Human Interface Guidelines gives you a good idea of the thought process behind typography as a whole, and Dynamic Type specifically, with another page giving more accessibility-specific information on how to deal with text.

The good news about Dynamic Type is that it almost comes out of the box. The bad news is the almost.

To make sure Dynamic Type is supported by your elements, verify that the adjustsFontForContentSizeCategory property for your element is set to true:

let label = UILabel()
label.font = .preferredFont(forTextStyle: .body)
label.numberOfLines = 0
label.adjustsFontForContentSizeCategory = true

Make note of a few things:

• We use the preferredFont(forTextStyle:) API that provides a system font. If you’re using custom fonts, you’ll have to make sure you are properly supporting Dynamic Type using UIFontMetrics.
• We set the label’s numberOfLines property to zero. While this is not a strict requirement, you can image that with a larger font, more number of lines may be used to properly layout your text.
• Elements automatically adjust their content size when the preferred content size changes.

Testing and Making Improvements

With this setup for your elements, you’ll be able to take a look at your app as a whole with a different Dynamic Text size; either by changing the system-wide text size (Settings > Accessibility > Display & Text Size > Larger Text Size), or on a per-app basis (with iOS 15): Settings > Accessibility > Per-App Settings > Add App > Larger Text.

You’ll probably note certain places in your app where, because of either the use of a much smaller (or much larger) font, certain layouts either break or become a little awkward.

While it’s challenging to keep all layouts optimal regardless of the user’s text size, one useful API is isAccessibilityCategory, which allows you to query if an accessibility text size is being used. With that information, you may consider switching your layout from something horizontal to something vertical, giving you more space to gracefully handle the larger text size.

Large Content Viewer

Unfortunately, certain elements are built in such a way that they are not expected to increase beyond a certain size. Examples are tab bar items, segmented controls and things like overlays.

To solve this, Apple introduced the Large Content Viewer, in, I think, iOS 11. In iOS 13, an API was introduced, too, enabling us to adopt the large content viewer for custom controls. The Large Content Viewer is shown based on the Dynamic Type settings: when using an accessibility text size, elements that can’t grow in size are expected to show it; the previously mentioned tab bar items and segmented control work out of the box.

Note that at the time of writing this, Large Content Viewer is unfortunately not supported in SwiftUI; you’ll have to implement it for custom controls using UIKit.

Conclusion

Supporting Dynamic Type may seem to require only few changes, yet in reality most apps won’t come with a great experience for it just like that.

Luckily, there are APIs that let us customize our layouts based on text size, allowing us to improve that experience for smaller and larger text sizes.

Let me know your thoughts on this post, and if you have any questions, I’d love to help!

• Getting Started With Accessibility: VoiceOver
• Improving Accessibility: VoiceOver
• Verifying VoiceOver: Accessibility Inspector
• Improving Accessibility: Voice Control
• Getting Started With Accessibility: Dynamic Type (this post)

Whereas VoiceOver is a screen reader, reading what’s on the screen, Voice Control lets users navigate their devices by voice.

In this post, we’ll look at Voice Control, how it works, and how you can make improvements to your app to make the Voice Control experience even better.

• Getting Started With Accessibility: VoiceOver
• Improving Accessibility: VoiceOver
• Verifying VoiceOver: Accessibility Inspector
• Improving Accessibility: Voice Control (this post)
• Getting Started With Accessibility: Dynamic Type

Introduction

Apple announced Voice Control for iOS and macOS at WWDC in 2019; the video below gives a great understanding of what Voice Control can do.

This is so cool! As you may have noticed, Voice Control definitely builds on top of accessibility labels to activate certain controls, like share buttons and more.

While macOS lacks some functionality in Voice Control compared to iOS, where we can show labels for elements, proper Voice Control-friendly labels are crucial for a great Voice Control experience on iOS.

Voice Control on iOS

Take a look at how to use Voice Control on iOS:

You’ll notice that commands like “Go back” or “Swipe left” are something we can make work as expected with the existing accessibility APIs that are also leveraged by VoiceOver.

And even more so than with VoiceOver, having succinct labels to use makes or breaks your Voice Control experience. Consider the following example:

Tap Outdoor Walk 2.13km today
// vs
Tap Outdoor Walk
// When there are multiple elements with the same name, iOS will overlay
// numbers for the matching elements.
Tap 2

Furthermore, you may want to provide multiple labels that can trigger Voice Control. Imagine a settings button in your app is indicated with a cog. You can make sure users can activate it with all of the following:

Tap Settings
Tap Cog
Tap Preferences
Tap Prefs
Tap Gear

To do so (and also improving your app for Full Keyboard Access’s Find), look no further than accessibilityUserInputLabels:

Use this property when the accessibilityLabel isn’t appropriate for dictated or typed input. For example, an element that contains additional descriptive information in its accessibilityLabel can return a more concise label. The primary label is first in the array, optionally followed by alternative labels in descending order of importance.

For the aforementioned settings button, we can do the following:

settingsButton.accessibilityUserInputLabels = [
    NSLocalizedString("Settings", comment: ""),
    NSLocalizedString("Preferences", comment: ""),
    NSLocalizedString("Prefs", comment: ""),
    NSLocalizedString("Gear", comment: ""),
    NSLocalizedString("Cog", comment: "")
]

Et voilà; any of these inputs will now be supported to either speak (with Voice Control) or to find the element (with Full Keyboard Access).

Further Reading

Kristina Fox wrote a great blog post on Voice Control back in 2019, which I’d highly encourage you to check out. It gives a great example on how to make those small tweaks to make Voice Control easier to use, and gives a great overview of the idea with example images, too!

Conclusion

Supporting VoiceOver lays groundwork for other assistive technologies, like Voice Control. With limited changes, we can build upon our accessibility work to branch out to other assistive technologies and make our apps even more accessible.

Let me know your thoughts on this post, and if you have any questions, I’d love to help!

• Getting Started With Accessibility: VoiceOver
• Improving Accessibility: VoiceOver
• Verifying VoiceOver: Accessibility Inspector
• Improving Accessibility: Voice Control (this post)
• Getting Started With Accessibility: Dynamic Type