OpenParable
Skip to content
← Back to skills

Maui Accessibility

Design
maui-accessibility

Maui 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  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.