Users of accessibility services, such as screen readers, rely on text labels to interact with user interfaces.
Screen readers announce the text label along with information about the type or state of the element. As a result, it isn't necessary for app developers to include information about type or state within the labels. For example:
- When TalkBack announces a clickable
Buttonelement, it appends the word "button" to the text label provided by the developer. If the developer includes "button" in the text label (such as "Save button"), TalkBack might speak the word "button" twice ("Save button button"). - If an interface has a
CheckBoxelement, the screen reader determines whether the element is checked and announces "checked" or "not checked" along with the text label provided by the developer. If the developer includes "checked" or "not checked" in the text label, the user might hear this information twice.
Assistive technologies often define their own set of gestures or interaction behaviors that are tailored to their users' needs. App-provided accessibility labels depend on the assistive technology used and should not provide specific interaction instructions, which might be incorrect. For example:
- TalkBack includes its own interaction instructions, “Double tap to select,” to describe clickable UI elements. If these instructions are included within the app-provided accessibility labels, TalkBack might speak these interaction instructions twice. If provided by the app, those same instructions wouldn’t be appropriate for a Switch Access user.
Implementation
Standard elements
When you provide text labels for standard user interface elements provided by the Android SDK, Android Support Library, or Android Design Support Library, use a brief localized string that describes what the element does or represents.
A well-implemented user interface doesn't add element type or state descriptions to values of android:contentDescription, android:text, or android:hint attributes.
Custom views
When creating user interface elements with custom views, extend the most relevant View subclass as is relevant to your use case. This allows a custom view's implementation to inherit as much platform-standard accessibility interaction behavior as possible, and in many cases proper representation of the view's type and state are managed on your app's behalf.
An app may modify how a custom view appears to accessibility services, including how it represents its type or state, by using AccessibilityDelegate or View#onInitializeAccessibilityNodeInfo. Using this approach requires the view to directly manage its own AccessibilityNodeInfo representation.
For custom views with complex information hierarchies or those capable of performing multiple actions, ExploreByTouchHelper can make it simple to represent virtual view hierarchies to Android’s accessibility services.
Standard elements
When you provide text labels for standard user interface elements provided by the Jetpack Compose Standard Library, use a brief localized string that describes what the element does or represents.
A well-implemented user interface doesn't include element type or state descriptions in content descriptions or Modifiers.semantics#text attributes.
An app may modify how custom low-level composables appear to accessibility services, including how it represents its type or state, by using Modifier.semantics or Modifier.semantics#role.
Design
See the Material Design accessibility guidelines for more guidance on writing effective labels for accessibility purposes.
Testing
To manually identify user interface elements that are labeled with their type or state:
- Turn on TalkBack.
- Open the app.
- Move accessibility focus to the item to be evaluated.
- Listen to TalkBack’s spoken description of the focused item. Check if the item's type or state is included in this description more than once.
Android's automated testing tools can detect some instances of user interface elements labeled with their type, state, or interaction instructions. Consider using Accessibility Scanner for Android for manual testing of your app on-device. For automated tests, turn on accessibility checking in Espresso and Robolectric.