Announcing the Compose Accessibility Techniques for Android™ Open Source Project

CVS Health® is releasing a new open-source project, Compose Accessibility Techniques for Android, which demonstrates accessibility programming techniques for the Android Jetpack™ Compose UI framework using good and bad examples that can be tested with TalkBack, Switch Access, and other assistive technologies on Android.

The GitHub repository and Android Studio project include working code demonstrating 34 accessibility coding topics, with examples of both accessible and inaccessible code. They also include documentation for developers (in Markdown files) explaining how to write accessible code in Compose, plus abstract code snippets. This project also demonstrates how Compose jUnit UI tests can validate accessibility semantics through automated tests and documentation.

This is an iterative project which will grow and improve as new techniques are added and old techniques updated. We’d love to collaborate with other accessibility people to build this into an excellent training resource for developers, designers, and testers!

Accessibility Technique Topic Groups

The Compose Accessibility Techniques app that this project can build organizes these 34 accessibility coding topics into three categories:

• Informative Content; for example, text alternatives and heading semantics
• Interactive Behaviors; for example, interactive control labels, keyboard types and options, and custom focus indicators
• Specific Component Types; for example, accordions, radio button groups, and text field input controls

The documentation Markdown files are grouped similarly.

Compose Accessibility Techniques app Home screen, with Specific Component Types topic expanded

Accessibility Technique Topic Resources

Each accessibility technique topic provides four types of learning resources:

• The app experience itself
• Topic documentation, including explanation and code snippets
• Working code samples
• Automated accessibility tests

For example, if you want to learn about accessible interactive Switch controls in Jetpack Compose, you can:

• Experience accessible and inaccessible Switch controls in the running Android app.

1. Open the Android app.
2. Tap Specific Component Types.
3. Open the Switch controls screen.
4. Follow the on-screen directions and use different assistive technologies to experience how users of those tools interact with accessible and inaccessible Switch controls.

• Read documentation of the coding techniques involved:

1. Open Compose Accessibility Techniques — Switch Controls.
2. Alternatively, open the project in Android Studio and view the file SwitchControls.md.

• Examine the app source code.

1. Open the project in Android Studio and view the file SwitchControls.kt.
2. Review the automated test code.
3. Open the project in Android Studio and view the file SwitchControlsTests.kt.
4. Also view the overall documentation for automated testing in AutomatedComposeAccessibilityTesting.md.

Switch controls screen

App Accessibility

The Compose Accessibility Techniques for Android app itself is accessible to TalkBack screen reader users, Switch Access users, and keyboard users, excepting the specific bad (or problematic) examples.

Both Light and Dark Themes are supported with sufficient text contrast ratios in each mode. And the app properly supports different device orientations, font sizes, and other Android accessibility settings.

Using any of these assistive technologies or accessibility settings, test the good and bad examples shown on the topic screens to observe the impact of accessible and inaccessible coding on the user experience.

Heading semantics accessibility technique screen with good and bad examples. TalkBack is announcing the good example heading and that it is a semantic heading.

GitHub Repository Structure

The GitHub repository is located at https://github.com/cvs-health/android-compose-accessibility-techniques. To stay informed of project updates and new releases, give the repository a Star.

The Compose Accessibility Techniques for Android GitHub repository home page

Key locations in the GitHub repository project are:

• The project /doc directory contains the markdown documentation files and can be accessed directly on GitHub to see rich HTML renderings of the Markdown documentation.
• The project /app/src/main directory contains the app source code.
• The project /app/src/androidTest directory contains the app automated testing source code.

Please Contribute!

This project can help Android Jetpack Compose developers learn how to write accessible code; however, there is room for it to expand and it may need improvements. Please consider contributing a technique that interests you but that is not yet implemented. Also, if you find problems or have suggestions, please create a new Issue in the GitHub repository.

Frequently Asked Questions (FAQ)

Why did we build Compose Accessibility Techniques for Android?

CVS Health created this project in order to:

• Provide in-depth guidance to developers about how to create accessible native Android apps using Jetpack Compose.
  
  Specifically, we built this project to provide comprehensive resources that include full working code examples for Compose accessibility programming techniques, in addition to documentation with code snippets.
• Assist developers, designers, and testers in understanding the impact of accessible and inaccessible code by clearly demonstrating good and bad practices in a working app.
  
  This approach also allows testers to understand how stock Material Design 3 Jetpack Compose components behave with proper accessibility remediation.
• Demonstrate how to use Compose jUnit UI tests to create automated accessibility tests that preserve product quality over time.

Who are the target audiences for this open-source project and app?

Developers are the main target audience. The project’s goal is to teach them how and why to implement accessibility in Jetpack Compose apps.

Designers are also an important audience for this project. They can use the project’s app to experience the impact on users of not designing and coding for accessibility. They can also learn some of the specifics of Android accessibility, as it is quite distinct from web and iOS accessibility.

Accessibility/QA Testers are another important audience for this project. They can learn the expected behaviors of correctly implemented Compose controls with the TalkBack screen reader and other Android assistive technologies by interacting with the live good examples in the app. They can also see bad examples of common inaccessible coding practices.

How do I download the project and test the app?

To download the project:

• In the Code tab of the GitHub repository, find the Code button and expand it.

The GitHub repository Code tab is shown with the Code button expanded to allow cloning the repository, opening with GitHub Desktop, or downloading a ZIP archive.

• Select to clone or download the project files to your local computer.
• Open the downloaded Android Studio project to see the source code or build the project.

Compose Accessibility Techniques project open in Android Studio

• Run the app on an Android device to test the good and bad accessibility examples.

Compose Accessibility Techniques for Android app icon

What are the documentation Markdown (.md) files?

Each accessibility technique topic screen has accompanying documentation written in Markdown. This documentation explains to developers of Jetpack Compose apps what code they need to implement that aspect of accessibility. Also included are appropriate abstract code snippets that complement both the explanation and the app’s working code.

The documentation also notes how the accessibility technique topic relates to the relevant Web Content Accessibility Guidelines (WCAG) success criteria that these techniques support. This discussion allows readers to begin to learn which technical accessibility guidelines are related to their work.

Developers, designers, and testers can read the documentation files directly from the GitHub repository to quickly understand what is required without needing to open Android Studio or view the technique demo in the app. Knowledge of Markdown is not needed to read these files, because GitHub renders Markdown into rich HTML automatically.

GitHub display of Markdown documentation for Text Alternatives

What is the complete accessibility topic list?

The Compose Accessibility Techniques for Android project contains the following topic screens, sorted by their respective topic group.

Informative Content:

• Text alternatives
• Accessibility traversal order
• Content grouping
• Content group replacement
• Heading semantics
• List semantics
• Adaptive layouts
• Dark and Light themes
• Screen and pane titles

Interactive Behaviors:

• Interactive control labels
• UX change announcements
• Keyboard types and options
• Keyboard actions
• Keyboard focus order
• Custom focus indicators
• Custom click labels
• Custom state descriptions
• Custom accessibility actions

Specific Component Types:

• Accordion controls
• Autofill controls
• Checkbox controls
• Dropdown menus
• Exposed dropdown menus
• Links inline with text
• ListItem layouts
• ModalBottomSheet layouts
• NavigationBar layouts
• Pop-up messages
• RadioButton groups
• Slider and RangeSlider controls
• Stand-alone links
• Switch controls
• Tab rows
• TextField controls

What if I need to know about accessibility in the Android View UI framework rather than Jetpack Compose?

For information about accessibility coding in the Android View UI framework, see the earlier CVS Health project View Accessibility Techniques for Android, which is also located on GitHub. Its documentation and app structure closely resemble those of Compose Accessibility Techniques for Android.

Also, some Compose-View interop techniques are demonstrated in Compose Accessibility Techniques for Android. For example, see Links Inline with Text.

Who is the creator and maintainer of the project?

CVS Health — through its accessibility engineers, including Robert Henley — created this project. Robert has a decade of Android development experience and holds a Master of Science in Human Factors in Information Design and a Certified Professional in Web Accessibility (CPWA) credential from the International Association of Accessibility Professionals (IAAP). Robert also has significant experience testing the accessibility of native mobile apps and assisting designers and developers in implementing Android accessibility.

How can I contribute?

To contribute to the project, visit the Contributing page and sign the Contributors License Agreement. Fork the repository and create a pull request with your proposed contributions.

How do I report issues or make suggestions?

If you find bugs or issues in the app or have recommendations for future improvements, please submit a new issue under the Issues tab in the GitHub repository. Thank you for the feedback!

Let Us Know What You Think!

Leave a comment below with your feedback after testing the project or the app. How are you planning to use this project at work? Would you like to contribute but have questions? We’d love to hear your feedback!

© 2024 CVS Health and/or one of its affiliates. All rights reserved.

Android and Android Jetpack are trademarks of Google LLC. The Compose Accessibility Techniques for Android Open Source Project is an independent project and has not been authorized, endorsed, or sponsored by Google LLC.

All trademarks and registered trademarks appearing in the article are the property of their respective owners.