Maui Accessibility
Designmaui-accessibilityMaui Accessibility is an Agent Skill for design published in the dotnet/maui-labs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/dotnet/maui-labs/blob/HEAD/plugins/dotnet-maui-app/skills/maui-accessibility/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/maui-accessibility, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
- Identify the user task and target controls.
- Add accessible names with
SemanticProperties.Description. - Add action guidance with
SemanticProperties.Hintwhen the control's result is not obvious. - Add
SemanticProperties.HeadingLevelfor page and section headings. - Hide decorative or duplicate content from the accessibility tree.
- Use
SemanticScreenReader.Announcefor important dynamic changes. - Move focus intentionally after navigation or validation when it helps the user.
- Keep
AutomationIdfor testing, but do not treat it as the accessible label. - 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.
AutomationIdvalues 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.Descriptionto aLabelwhen itsTextproperty already serves as the accessible name. Only add it when the visible text is absent or insufficient. - Announcements: Call
SemanticScreenReader.Announcefor 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
SemanticPropertieson 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
AutomationIdas 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.