maui-accessibility

MAUI Accessibility

Use this skill to make MAUI UI understandable and operable through assistive technologies. Accessibility metadata should be added while building UI, not as a final cosmetic pass.

Workflow

1. Identify the user task and target controls.
2. Add accessible names with SemanticProperties.Description.
3. Add action guidance with SemanticProperties.Hint when the control's result is not obvious.
4. Add SemanticProperties.HeadingLevel for page and section headings.
5. Hide decorative or duplicate content from the accessibility tree.
6. Use SemanticScreenReader.Announce for important dynamic changes.
7. Move focus intentionally after navigation or validation when it helps the user.
8. Keep AutomationId for testing, but do not treat it as the accessible label.
9. Verify with platform screen readers when possible.

Common Patterns

Icon-only button

<ImageButton
    AutomationId="save-button"
    Source="save.png"
    SemanticProperties.Description="Save"
    SemanticProperties.Hint="Saves the current form" />

Heading

<Label
    Text="Account settings"
    SemanticProperties.HeadingLevel="Level1"
    Style="{StaticResource TitleStyle}" />

Decorative image

<Image
    Source="card_background.png"
    AutomationProperties.IsInAccessibleTree="False" />

Dynamic announcement

SemanticScreenReader.Announce("Profile saved");

Accessibility Checklist

• Icon-only controls have descriptions and, when useful, hints.
• Page and major section headings have heading levels.
• Decorative images and duplicated labels are hidden from the accessibility tree.
• Dynamic validation, save, and navigation outcomes are announced when important.
• Touch targets are large enough and not crowded.
• Color is not the only way information is conveyed.
• AutomationId values exist for test automation but are not used as a substitute for accessible names.

Platform Notes

• Android TalkBack, iOS VoiceOver, macOS VoiceOver, and Windows Narrator differ in how aggressively they read hints and grouped content; verify on the target platform for critical flows.
• For validation errors, move semantic focus to the summary or first invalid field and announce the error.
• For CollectionView rows, ensure the row exposes a meaningful label instead of reading every decorative child.