Add accessibility checklist for native mobile experiences by janmaarten-a11y · Pull Request #41 · github/annotation-toolkit

janmaarten-a11y · 2026-04-30T03:15:00Z

Closes #36

Overview

This pull request adds a comprehensive accessibility checklist specifically for native mobile applications (iOS and Android) in the new file checklists/mobile-checklist.md. The checklist consolidates WCAG 2.2 requirements, W3C mobile guidance, and platform best practices into actionable items for designers and engineers working on native mobile experiences. It covers all major accessibility considerations, provides annotation guidance, and includes resources and testing recommendations.

This document provides a comprehensive checklist for accessibility considerations specific to native mobile experiences, including guidelines, best practices, and resources for iOS and Android applications.

Co-authored-by: Eric Bailey <ericwbailey@users.noreply.github.com>

Copilot

Pull request overview

Adds a new, mobile-specific accessibility checklist to complement the existing designer and engineering checklists, addressing mobile-native patterns and audit considerations requested in issue #36.

Changes:

Introduces checklists/mobile-checklist.md with an iOS/Android-focused accessibility checklist (WCAG 2.2 + WCAG2Mobile/WCAG2ICT guidance + platform best practices).
Includes annotation pointers, testing recommendations, and a curated set of resources for mobile accessibility work.

Show a summary per file

File	Description
checklists/mobile-checklist.md	Adds a comprehensive native mobile accessibility checklist covering key areas (color, hierarchy, gestures, platform behavior, navigation, etc.).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 1/1 changed files
Comments generated: 3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

joelamyman

@janmaarten-a11y as always, this is such a fantastic resource - super comprehensive and easy to follow!

I've left some minor comments, please feel free to use/dismiss them as you see necessary! If there are any questions, please let me know 😄

joelamyman · 2026-05-05T10:12:20Z

+- [ ] **Roles and traits are specified per platform**
+	- iOS uses traits (button, header, adjustable, selected). Android uses roles and state descriptions. Annotate both if you ship to both.
+- [ ] **Hints are used only for non-obvious interactions**
+	- Don't put critical info in hints. Users can disable them, and they're announced last.


This is an excellent point to raise as its something that feels like its missed quite often, so great to include it here!!

joelamyman · 2026-05-05T10:20:50Z

+- [ ] **Stock components use the platform's native accessibility behavior**
+	- When using a system component, toggle "Follow stock native pattern" in your Mobile Details annotation and link to the platform docs.
+- [ ] **Platform conventions are respected**
+	- Back navigation, modal dismissal, and primary action placement differ between iOS and Android. Don't force one platform's pattern onto the other.


This is a really important point for usability, so it's great to see it included here! 🙌

Updated language for clarity and added guidance on accessibility practices in mobile app design.

Added a checklist for mobile accessibility considerations.

@ericwbailey

Updated checklist items to include links for Smart Invert, color correction, VoiceOver, TalkBack, Reduce Motion, iOS Dynamic Type, and Android Font Size Scaling for better accessibility guidance. h/t @ericwbailey

janmaarten-a11y · 2026-05-05T20:50:36Z

Thanks all for the thorough and thoughtful review! 🙌 I've pushed the remaining updates addressing every open comment.

What changed in this round:

Single-bullet list cleanup — finished the audit Eric flagged on §2 Exercises. Converted the single-item "Annotations that can help" lists in §5, §7, §8, and §13 to inline sentences so screen reader users aren't told there's more list content when there isn't.
Intro restructure — split the per-interaction guidance and audit notes into two paragraphs, each with a short "why" explaining when you'd reach for that resource.
Decorative explainer — added a link to the W3C alt-text decision tree in §3 since deciding what's actually decorative is the hard part.
Reading order on framework-determined platforms — new item in §2 about favoring simple, predictable layouts since some frameworks (notably React Native) don't expose an API to override OS-determined reading order. Thanks @joelamyman for the prompt.
Label item expansion — broke §3's Label caption into three sub-bullets covering purpose, Voice Control / Voice Access programmatic association, and icon-only labels.
Buttons and links wording — adopted Joel's clearer phrasing about considering the action when applying a role.
Orientation completeness — added "all functionality and content must remain available across orientations" to §7.
Voice Control caption — unpacked the "drift apart" phrasing to call out both visual and programmatic relationships.
Errors expansion — §8's error item now covers text-based identification, fix suggestions where determinable, and screen reader announcement.
Reachable AND operable — §10 now makes it explicit that external keyboard support means the interaction must work, not just be focusable.
iOS/Android jargon links on first mention — per @ericwbailey's question. Linked VoiceOver, TalkBack, Voice Control, Voice Access, Reduce Motion, Switch Control, Switch Access, Smart Invert, color correction, Dynamic Type, and Android's Font Size Scaling on first mention. We can carry this pattern over to the designer and engineering checklists in a follow-up.

I also added links to this new doc from the repo README.md and the Mobile annotations tutorial.

What I didn't take:

@joelamyman's GOV.UK number input post — it's a great read but the nuance felt too deep for the format. Worth revisiting if we ever do a deeper forms guide.

Re-requesting review from @ericwbailey and @joelamyman. Thanks again for making this much sharper than where it started!

julianmka · 2026-04-30T12:05:19Z

+
+- [Check color contrast - Figma Docs](https://help.figma.com/hc/en-us/articles/360041003774-Apply-paints-with-the-color-picker#h_01JQF1T71AC72G6VDXN27B77V0)
+- [Web Color Contrast Checker - WebAIM](https://webaim.org/resources/contrastchecker/)
+- [Colour Contrast Analyzer for Mac and Windows - TPGi](https://www.tpgi.com/color-contrast-checker/)


Worth a mention that the Android Accessibility Scanner can detect contrast issues? It's not fool-proof, but it's decent.

julianmka · 2026-04-30T12:06:55Z

+
+- [ ] **Each screen has at most one Title**
+	- Not every screen needs a title, but if one is needed, only one is used. Titles live in the top app bar (Android) or navigation bar (iOS) and are announced on view transition. Note: in WCAG terms, [SC 2.4.2 Page Titled](https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html) applies to the application as a whole on native, but the per-screen title is still the right pattern for orientation.
+- [ ] **Headings are used sparingly and only when they help structure the screen**


If a screen doesn't have a title in the top bar, I always highly encourage that the screen have some kind of prominent heading at or near the top of content.

julianmka · 2026-05-06T01:39:40Z

+- [ ] **Hints are used only for non-obvious interactions**
+	- Don't put critical info in hints. Users can disable them, and they're announced last.
+- [ ] **Decorative elements are hidden from assistive tech**
+	- Mark with `accessibilityElementsHidden` (iOS) or `importantForAccessibility="no"` (Android).


Rather than accessibilityElementsHidden, I'd recommending citing .accessibilityHidden set to true, which is specific to iOS (SwiftUI specifically).

julianmka · 2026-05-06T01:41:31Z

+- [ ] **Decorative elements are hidden from assistive tech**
+	- Mark with `accessibilityElementsHidden` (iOS) or `importantForAccessibility="no"` (Android).
+- [ ] **Language of the app is set, and any sections in a different language are identified**
+	- On native, [SC 3.1.1 Language of Page](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html) applies to the application as a whole, not individual screens. For inline text in a different language, identify it programmatically per [SC 3.1.2 Language of Parts](https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html).


Consider adding a reference link for this, as it's kind of varsity-level. Appt.org has a good starting point that covers all major native mobile frameworks: https://appt.org/en/guidelines/wcag/success-criterion-3-1-2

julianmka · 2026-05-06T01:49:48Z

+### Resources
+
+- [Getting To The Bottom Of Minimum WCAG-Conformant Interactive Element Size - Smashing Magazine](https://www.smashingmagazine.com/2024/07/getting-bottom-minimum-wcag-conformant-interactive-element-size/)
+- [Apple HIG: Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons)


This link covers target size on a platform rather than component level: https://developer.apple.com/design/human-interface-guidelines/accessibility#Mobility

julianmka · 2026-05-06T02:04:36Z

+- [ ] **There are no focus traps**
+	- Modals, sheets, and overlays must let users dismiss and return focus to a logical place. Per [SC 2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html).
+- [ ] **Custom controls expose proper accessibility actions**
+	- A custom slider should respond to increment/decrement actions, not just drag.


"For example, a custom slider..."

julianmka · 2026-05-06T02:06:56Z

+- [ ] **Stock components use the platform's native accessibility behavior**
+	- When using a system component, toggle "Follow stock native pattern" in your Mobile Details annotation and link to the platform docs.
+- [ ] **Platform conventions are respected**
+	- Back navigation, modal dismissal, and primary action placement differ between iOS and Android. Don't force one platform's pattern onto the other.


Worth mentioning the VO scrub gesture here, that behaves similar to the back button? It can navigate backward, dismiss modals, and be assigned to collapse/hide custom components when it makes sense. If you're not using stock components, users will expect support of the scrub gesture and it has to be added manually.

julianmka · 2026-05-06T02:10:03Z

+- [ ] **Adjacent targets have enough spacing**
+	- Aim for at least 8 pt/dp between tappable elements to prevent mis-taps.
+- [ ] **Buttons and links are used appropriately**
+	- Buttons trigger actions. Links navigate. Don't style one as the other. When annotating, identify every element that performs an action when activated so the right role is applied.


It's less clearcut on mobile -- the general practice I teach and that most platform apps seem to follow is that anything that navigates you within an app, or that triggers a system function (e.g. initiating a phone call) is a button. Links are reserved for content that opens in the device browser, or possibly web views.

julianmka · 2026-05-06T02:11:40Z

+- [ ] **Automatic transitions are avoided or controllable**
+	- System-initiated screen, state, or content changes should be paused, slowed, or dismissable. Common offenders: onboarding carousels, auto-advancing tutorials. Per [SC 3.2.1 On Focus](https://www.w3.org/WAI/WCAG22/Understanding/on-focus.html) and [SC 3.2.2 On Input](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html).
+- [ ] **Opening external content is announced**
+	- "Opens in Safari", "Opens in browser", or "Opens in a new window" warnings prevent disorientation, especially when leaving an app for a web view.


Recommend striking the Safari example since iPhone users can customize their default browser (even if it is all just Safari/Webkit under the hood 🙃 )

julianmka · 2026-05-06T02:16:31Z

+
+## 13. Notifications and live updates
+
+- [ ] **Status changes are announced via Live Regions**


~~Live Regions~~ live accessibility announcements
(live regions aren't really a thing, although we can accomplish similar goals. Just different terms.)

joelamyman

Just completed another review, all of the changes look good to me - I caught a TPGi link that should be changed to Vispero after their recent rebranding, but that's it! 😄

joelamyman · 2026-05-06T10:09:26Z

+
+- [Check color contrast - Figma Docs](https://help.figma.com/hc/en-us/articles/360041003774-Apply-paints-with-the-color-picker#h_01JQF1T71AC72G6VDXN27B77V0)
+- [Web Color Contrast Checker - WebAIM](https://webaim.org/resources/contrastchecker/)
+- [Colour Contrast Analyzer for Mac and Windows - TPGi](https://www.tpgi.com/color-contrast-checker/)


Only just caught this, but as a heads up, TPGi are now Vispero - so I think this should be:

- [Colour Contrast Analyzer for Mac and Windows - Vispero](https://vispero.com/lp/color-contrast-checker/)

Initial commit

6b40e70

This document provides a comprehensive checklist for accessibility considerations specific to native mobile experiences, including guidelines, best practices, and resources for iOS and Android applications.

janmaarten-a11y requested review from alexislucio, ericwbailey and mattobee April 30, 2026 03:19

janmaarten-a11y mentioned this pull request Apr 30, 2026

[Feature request] Add a Mobile variant to the Checkpoints component #36

Open

janmaarten-a11y self-assigned this Apr 30, 2026

ericwbailey reviewed Apr 30, 2026

View reviewed changes

Apply suggestions from code review

498edf8

Co-authored-by: Eric Bailey <ericwbailey@users.noreply.github.com>

janmaarten-a11y requested a review from joelamyman April 30, 2026 21:24

janmaarten-a11y marked this pull request as ready for review April 30, 2026 21:25

janmaarten-a11y requested a review from a team as a code owner April 30, 2026 21:25

Copilot AI review requested due to automatic review settings April 30, 2026 21:25

Copilot started reviewing on behalf of janmaarten-a11y April 30, 2026 21:25 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Comment thread checklists/mobile-checklist.md Outdated

Comment thread checklists/mobile-checklist.md Outdated

Comment thread checklists/mobile-checklist.md

Apply suggestions from code review

7a4121c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

joelamyman reviewed May 5, 2026

View reviewed changes

janmaarten-a11y added 4 commits May 5, 2026 12:48

Apply suggestions from code review

6359f44

Updated language for clarity and added guidance on accessibility practices in mobile app design.

Add mobile accessibility checklist link to README

964c9ab

Added a checklist for mobile accessibility considerations.

Add platform feature links

e43f12c

Updated checklist items to include links for Smart Invert, color correction, VoiceOver, TalkBack, Reduce Motion, iOS Dynamic Type, and Android Font Size Scaling for better accessibility guidance. h/t @ericwbailey

Add Mobile Checklist to resources

8cf949e

janmaarten-a11y requested review from ericwbailey and joelamyman May 5, 2026 20:50

julianmka reviewed May 6, 2026

View reviewed changes

joelamyman requested changes May 6, 2026

View reviewed changes


		## 13. Notifications and live updates

		- [ ] Status changes are announced via Live Regions

Conversation

janmaarten-a11y commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joelamyman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janmaarten-a11y commented May 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joelamyman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

janmaarten-a11y commented Apr 30, 2026 •

edited

Loading