DEV Community: Fanny Demey

Best practices to build accessible apps with Jetpack Compose

Fanny Demey — Mon, 02 Aug 2021 07:10:59 +0000

Hello!
Here you are! You have finally decided to take a look at what it takes to make your android application accessible for people with visual impairment. First, that's great news ! You'll see that it's a rewarding path that you are about to take.

Today I'm going to share with you a list of best practices to make your app accessible specifically for people who are blind. I will show you how to do that with Jetpack Compose.

How does Talkback work ?

Talkback is the screen reader on android used by blind or low vision users.

Here are several gestures that you can perform anywhere on the screen, that allows you to navigate through each elements:

➡️: swipe to the right to go to next element

⬅️: swipe to the left to go to previous element

↕️: swipe up and down on the screen or swipe down and up, will open a menu. In this menu you can configure swipe up / swipe down gesture, for example: Navigation between headers, speech rate, read letter by letter (useful to read a password for example).

⬇️ or ⬆️: swipe up or down allows you to perform an action that you configured with the previous gesture.

👆: single tap on an element on the screen will give the focus to this element.

👆👆: double tap to activate an element for example a button.

When an element is focused, Talkback will give user informations about it. For example:

its content
its value: for example for an Edit text.
Its type: "Button" "Edit box", "Tab", "List: 9 of 11 items".
Its state: "Selected" for a tab for example.
The action you can perform with it: "activate", "toggle", etc...

Best practices list

1. Add content description to images

Let's take for example a shopping app. In the following screen, we have an image showing a black t-shirt. If we do nothing, blind users would not know what this element is unless they perform 8 swipes to the right, to reach its label "T-shirt with cut-outs tied". So we should add a description to this image. (and all the other images on this screen)

Here is how to do that with Jetpack Compose.

Image( painter = rememberCoilPainter(product.url),
       contentDescription = product.contentDescription)

The good news with Jetpack Compose is that contentDescription is mandatory!

2. Hide decorative images

When an element is purely decorative and doesn't bring any additional information to the user (for example a background, an image to illustrate a text that doesn't add any meaningful information to it), you can hide it so that Talkback will not give the focus on this element.

Image( painter = painterResource(R.drawable.background),
       contentDescription = null)

3. Improve element’s description

In some situations the way that Talkback will read the element content will not be user friendly. Specifically in situations when we don't say something out-loud the same way that it's written.

For example: the daily rate for a car rental: $16/day

We will never say out loud: "Dollar sixteen slash day", but if we do nothing in our app, Talkback will. That's not a very nice user experience.

By overriding the text attribute of our Text composable using the Modifier.semantics property, we are able to improve the information read by Talkback.

@Composable
fun DailyRate(rate: Int){
   Text(text = “$rate/day”,
        modifier = Modifier.semantics {
            text = AnnotatedString(“$rate dollars per day”)
        }
   )
}

4. Group elements together

In some situations, it can really improve the user experience to group element together. Imagine a screen with lots of elements on it. Imagine now that you have to go through every single element by swiping right. It's exhausting.

For example on this pet sitter profile screen. We can group together information like "no pets, home, car owner" to be focused and read all together. We can perform that by setting mergeDescendants to true in the Modifier.semantics properties of the main row.

Row (modifier = Modifier.semantics(mergeDescendants = true){}){
   Column {
       Icon(painter = painterResource(R.drawable.ic_pets),
           contentDescription = null)
       Text(text = stringResource(R.string.no_pet))
   }
   Column {
       Icon(painter = painterResource(R.drawable.ic_car),
           contentDescription = null)
       Text(text = stringResource(R.string.car_owner))
   }
   Column(/*...*/)
}

5. Change reading order

Sometimes, it makes sense to influence the reading order of the element on the screen to improve the user experience and sometimes avoid having a feature completely inaccessible because the element is unreachable.
For example every time you design something on the z-index, let's say with a floating action button like the "Compose" button in gmail. If you do nothing, the focus to this button will be given after going through all the elements of the emails list behind (if the list is not infinite...).

There is no way to fix that with Jetpack Compose yet 😔... Here is an issue about that: A11y - Need a way to change manually focus order. Please comment or star the issue if you also think that it's important for the users.

To fix that without Jetpack Compose, you can use android:accessibilityTraversalBefore and android:accessibilityTraversalAfter properties to specify the element before and after the FloatingActionButton.

<com.google.android.material.floatingactionbutton.FloatingActionButton
   android:id="@+id/fabButton"  
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:src="@drawable/ic_pencil"
   android:contentDescription="@string/create_new_email"
   android:layout_gravity="bottom|right"
   android:accessibilityTraversalBefore="@id/mailList"
   android:accessibilityTraversalAfter="@id/profilePicture"
   />

6. Facilitate navigation with headings

On the web, screen reader users are used to navigate quickly between headings (<h1>, <h2>, <h3>...). It gives them a quick overview of the content and help them to be more efficient.
Starting from Talkback 9.1, it's now also possible to do that in android apps, as long as the developer specifies it.

A good example to set up headings is when you have sections in a list. Like here in this settings screen:

To specify that sections of that list are headings, we have to add heading() inside the Modifier.semantics property.

@Composable
private fun Section(text: String) {
     Text(text = text,
       modifier = Modifier.semantics { heading() }
   )
}

7. Disable element and describe element state

Last situation I want to illustrate is the following: you have a list of items, and a switch button on each row of the list.

If we do nothing Talkback will behave on each row like this:

Focus the entire row and say "Profile button"
Focus on the switch button: "On - Switch - Double tap to toggle"

This can be exhausting to go through a long list of configurable rows if Talkback stops twice per row.

The original composable will probably looks like this:

var checked by remember { mutableStateOf(true) }

Row{
   Text(text = "Profile details")
   Switch(checked = checked,
          onCheckedChange = { checked = !checked }
   )
}

A better user experience, could be something like this on each row :

Focus the entire row and say "Profile button - ON - Double tap to toggle"

We will do that in two step :

Disable the focus on the Switch button
Add toggle behaviour to the entire row

Let's go.

1) Disable the focus on the Switch button

We can do that by adding the Modifier.clearAndSetSemantics with nothing inside. This way talkback will ignore it.

var checked by remember { mutableStateOf(true) }

Row{
   Text(text = "Profile details")
   Switch(checked = checked,
          onCheckedChange = { checked = !checked },
          modifier = Modifier.clearAndSetSemantics {  }

   )
}

Although using clearAndSetSemantics{} is the usual way to ask Talkback to ignore an element, keep in mind that in general when semantics properties can be changed by setting another default parameter of a composable, that should be preferred over using the lower level semantics modifier. In this situation, we can for example set null to onCheckChange callback, and the switch button will be ignored by Talkback too.

var checked by remember { mutableStateOf(true) }

Row{
   Text(text = "Profile details")
   Switch(checked = checked,
          onCheckedChange = null
   )
}

2) Add toggle behaviour to the entire row

We add a toggleable Modifier to the row and perform in it the same action than on the switch.
We add in the semantics Modifier the stateDescription properties to configure what Talkback should say regarding the switch state.

var checked by remember { mutableStateOf(true) }

Row(modifier = Modifier
        .toggleable(checked) { checked = !checked }
        .semantics {  stateDescription = 
                       if(checked) "ON" else "OFF" }
){
   Text(text = "Profile details")
   Switch(checked = checked,
                   onCheckedChange = null

   )
}

That's it

That's it for my list of best practices to make your app usable for blind users.
You can also check the Compose documentation for accessibility here : Jetpack Compose - Accessibility Documentation

Of course accessibility is not only about blind people, so I really encourage you to learn more about that. Here is where you can start : Mozilla website - what is accessibility.

I hope you enjoyed this article. Don't hesitate to reach out to me on Twitter if you have any questions : @FannyDemey

Best practice to build accessible apps with SwiftUI

Fanny Demey — Wed, 07 Apr 2021 18:16:23 +0000

Created: Apr 7, 2021 2:25 PM

Last year I had the opportunity to learn SwiftUI development and specifically to work on making views more accessible. At that time, I set up for the team a list of best practices. Today, I've decided to share those with you.

How VoiceOver works

First let's see how VoiceOver works. VoiceOver is the screen reader used on iOS by users with low vision or who are blind. Here are several gestures that you can perform anywhere on the screen, that allows you to navigate through visual elements :
➡️ swipe to the right to go to next element

⬅️ swipe to the left to go to previous element

⬇️ ⬆️ swipe top to bottom or bottom to top allows you to do an action that you can configure with the rotor (see below)

🔂 drawing a circle with 2 fingers will open what is called the "Rotor". It allows you to configure swipe action top <-> bottom, for example : Navigation between headers or containers.

👆 single tap on an item to read an element.

👆👆 double tap to activate an element for example a button.

When an element is focused, VoiceOver will give user information about it. Basically VoiceOver read 4 properties for each element :

Label : for exemple the text of the element "Today"
Value : "Wednesday 8th of July" (it can give more information related to the Label. It's not mandatory, but can be useful for EditText for example).
Trait : "Button" or "Static text" or "Heading" or "Container" or "Adjustable"
Hint : To give a hint to the user about the action that can be performed on this element. for example "swipe top or bottom to change the value of this element" (not mandatory also)

Those 4 properties are pronounced in this order.

How I test accessibility

One good practice I applied to make my application usable for people with visual impairment was testing 2 different use cases :

Use VoiceOver and validate that the user experience is good 🔊
Test my application with different font size in accessibility parameters 🔎 (that can be done easily with the Accessibility Inspector. You can find it in XCode menu ⇒ Open Developer Tool ⇒ Accessibility inspector)

Of course, there are other use cases to make an app accessible, and visual impairment is not the only thing you should care about.

Use case 1 : using VoiceOver 🔊

Here are some test I perform to test user experience with VoiceOver :

User can easily go from an element to another, and the order of element is logical
User can identify the goal of an element thanks to a good combination of label / value / trait / hint
VoiceOver does not focus on decorative elements such as image background.
Some elements are grouped to facilitate comprehension and navigation (for example : an icon and its label)
If using modal view, make sure that the content underneath is not accessible through VoiceOver

Use case 2 : change the font size 🔎

Here are some test I perform for this use case :

Texts scale when changing for a larger font in accessibility settings
User can still see all the content
Nothing overlaps

Best practice list

When my test fails, most of the time I use a solution from the following list :

1/ Make the font scalable

If you have trouble having your font scaling up with accessibility settings, you should probably take a look at this tutorial : https://www.hackingwithswift.com/quick-start/swiftui/how-to-use-dynamic-type-with-a-custom-font

2/ Change the reading order with voiceOver

In some situations I had to tell VoiceOver which element to focus on before another one.

HStack {
    buttons().accessibility(sortPriority: 1)
    toggle().accessibility(sortPriority: 2)
}.accessibilityElement(children: .contain)

In this example, toggle will have focus before buttons when the user navigate between elements with VoiceOver.

3/Combine elements together

To prevent users from navigating through every single piece of elements when it's not needed, I group elements together and set a specific label for this group.

HStack{
    Button(....)
    Text(.....)
}.accessibilityElement(children: .combine)
.accessibility(label: Text("Title"))

Example :

4/ Change the trait type

In some situation, I wanted had to add or remove a trait :

Text(title)
  .accessibility(addTraits: .isHeader)
  .accessibility(removeTraits: .isStaticText)

5/ Disable visibility of an element

A good practice in accessibility is to hide decorative elements such as background images.

HStack(){
    //... 
}.background(
        Image(I.home_nav_background)
            .accessibility(hidden: true)
)

6/ Add a more explicit label

For example, in my app I displayed a time in this format HH:mm. To make it more understandable with VoiceOver, I had to override the label of the Text (overwise VoiceOver was saying something like "HH colon mm")

Text(hour)
.accessibility(label: Text(hour.toSpelloutAccessibleTime(format : "HH:mm")))

7/ Adapt the design when the font becomes larger

It can be useful t to adapt design when the font become larger. Here is how I've done it.

@SwiftUI.Environment(\\.sizeCategory) var sizeCategory: ContentSizeCategory

// Then you can simply use greater than and less than comparator to change property values for example
HStack{
    // 
}.frame(height: sizeCategory > .extraLarge  ? 100 : 40)

Conclusion

That's it for the best practices I've tried to apply when I was developing in SwiftUI last year. The Swift API has probably evolved by now, so my best advice for SwiftUI beginner like I was (and that I actually still are as I am an android developer) is to learn from Hacking with swift website. There is a series of articles about accessibility : https://www.hackingwithswift.com/books/ios-swiftui/accessibility-introduction

If you are not familiar with accessibility and the usage of VoiceOver, I also advise you to try VoiceOver on a real device. You can have a look to this video to learn more about how to use VoiceOver on your iPhone

I Hope my personal best practice will help you. Don't hesitate to reach out on Twitter : @FannyDemey