maui-accessibility

name

maui-accessibility

description

Make .NET MAUI apps accessible with semantic properties, screen reader labels/hints, heading levels, focus, announcements, AutomationProperties, touch targets, and platform checks. USE FOR: accessibility audits, WCAG UI fixes, TalkBack/VoiceOver/Narrator behavior, SemanticProperties.Description/Hint/HeadingLevel, SemanticScreenReader.Announce, SetSemanticFocus, avoiding redundant Label metadata, hiding decorative content with IsInAccessibleTree=false, and CollectionView row semantics. DO NOT USE FOR: general layout, UI automation only, or performance tuning.

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.

MAUI-Specific Best Practices

• Label/Text redundancy: Do NOT add SemanticProperties.Description to a Label when its Text property already serves as the accessible name. Only add it when the visible text is absent or insufficient.
• Announcements: Call SemanticScreenReader.Announce for important outcomes (save success, validation summary) but NOT for every state change. Provide guidance on avoiding over-announcing by batching related errors.
• CollectionView rows: Ensure each row exposes a meaningful composite label rather than reading every child view separately. Use SemanticProperties on the container or a specific child, not all children.
• Multiple validation errors: Announce a summary count ("2 errors") after the user submits, not a separate announcement per field.

Anti-Patterns

• Do not rely on placeholder text as the only field label.
• Do not use AutomationId as the accessible name.
• Do not hide real interactive content from the accessibility tree to make screen reader output shorter.
• Do not announce every small UI update; reserve announcements for meaningful state changes.