Eight .NET MAUI accessibility problems that are easy to miss until you run the app
A developer's hands-on testing surfaced eight .NET MAUI accessibility problems that XAML alone does not reveal, covering screen reader names, headings, font scaling, and contrast. Each issue comes with a concrete fix or test step, which makes this a practical checklist before shipping a MAUI app.
Key points
- Do not rely on AutomationId for screen readers; add a human-readable name with SemanticProperties.Description.
- Mark real headings with SemanticProperties.HeadingLevel so screen reader users can jump between them.
- On Android, adding ConfigChanges.FontScale avoids recreation but does not re-apply fonts; test font size changes mid-flow.
- On iOS, use Microsoft.Maui.Controls 10.0.100 or later and set MauiVersion explicitly, since the template may resolve an older version.
- Wrap long pages in a ScrollView and test at 200% font scale on your smallest supported device.
- Check template text colours against WCAG 1.4.3 and test both light and dark themes.
This article collects findings from a developer who tested .NET MAUI apps on Android emulators, iOS simulators and physical phones. The problems are the kind that only appear at runtime: a button with only an AutomationId gets read aloud as a raw developer identifier, headings are not announced unless marked, and on Android a font size change can recreate the activity and drop the user back to the first page.
The author also covers iOS text that did not resize until Microsoft.Maui.Controls 10.0.100, controls pushed off screen at 200% font scale, template text colours that fail WCAG contrast, and a sample app that passes contrast checks in dark mode but fails in light mode. The suggested fixes include SemanticProperties.Description, SemanticProperties.HeadingLevel, wrapping long pages in a ScrollView and pinning MauiVersion. The original post has the XAML samples and the full test notes.
Real-world use
- A team adding accessibility compliance to an existing enterprise .NET MAUI app.
- A healthcare or banking app that must support large text settings for older users.
- A pre-release QA pass on a MAUI app before testing with real screen reader users.
Why it matters
Most of these problems never appear in XAML and only show up on a device with TalkBack, large text or a theme switch. Running these checks before release prevents users from losing their place or hitting unreachable controls.