davidortinau/maui-skills/maui-accessibility

.NET MAUI Accessibility

Critical Platform Gotchas

1. Don't set Description on Label

Setting SemanticProperties.Description on a Label overrides the Text property for screen readers. The label may be read twice or behave unexpectedly.

<!-- ❌ Stops Text from being read naturally -->
<Label Text="Welcome"
       SemanticProperties.Description="Welcome" />
 
<!-- ✅ Screen reader reads Text automatically -->
<Label Text="Welcome" />

2. Android Entry/Editor: Description breaks TalkBack actions

On Android, setting SemanticProperties.Description on Entry or Editor causes TalkBack to lose "double tap to edit" action hints.

<!-- ❌ Breaks TalkBack on Android -->
<Entry SemanticProperties.Description="Email address" />
 
<!-- ✅ Use Placeholder for context instead -->
<Entry Placeholder="Email address" />

3. iOS: Description on parent hides children

On iOS/VoiceOver, setting SemanticProperties.Description on a layout makes the entire container a single accessible element — child elements become unreachable.

<!-- ❌ Children invisible to VoiceOver -->
<HorizontalStackLayout SemanticProperties.Description="User info">
    <Label Text="Name:" />
    <Label Text="Alice" />
</HorizontalStackLayout>
 
<!-- ✅ Let children be individually focusable -->
<HorizontalStackLayout>
    <Label Text="Name:" />
    <Label Text="Alice" />
</HorizontalStackLayout>

4. Hint conflicts with Entry.Placeholder on Android

On Android, SemanticProperties.Hint and Entry.Placeholder map to the same Android attribute (contentDescription / hint). Setting both causes one to override the other. Choose one.

5. HeadingLevel platform differences

• Windows (Narrator): Supports all 9 heading levels (Level1–Level9).
• Android (TalkBack) / iOS (VoiceOver): Only distinguish "heading" vs

"not heading". All levels are treated identically.

Use heading levels for semantic correctness — just know the hierarchy only renders on Windows.

Accessibility Checklist

When auditing or retrofitting a page:

1. Images: Add SemanticProperties.Description to meaningful images.

Set AutomationProperties.IsInAccessibleTree="false" on decorative ones.

1. Buttons/Controls: Ensure icon-only buttons have Description.

Text buttons generally don't need it.

1. Entries/Editors: Use Placeholder for context. Add Hint only if

extra instruction is needed. Avoid `Description` (Android breakage).

1. Labels: Do not add Description — let Text speak for itself.

Add HeadingLevel to section headers.

1. Headings: Mark page title as Level1, section titles as Level2, etc.
2. Grouping: Avoid Description on layout containers (iOS breakage).

Use ExcludedWithChildren to hide decorative groups.

1. Dynamic content: Call SemanticScreenReader.Announce for status

changes. Use SetSemanticFocus after navigation or error display.

1. Tab order: Set TabIndex on interactive controls for logical order.
2. Test: Run TalkBack (Android), VoiceOver (iOS/Mac), and Narrator

(Windows) to verify reading order and actions.