Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-accessibility

@79bb4bf
Run it yourself

Guide for making .NET MAUI apps accessible — screen reader support via SemanticProperties, heading levels, AutomationProperties visibility control, programmatic focus and announcements, and platform-specific gotchas for TalkBack, VoiceOver, and Narrator. USE FOR: "add accessibility", "screen reader support", "SemanticProperties", "AutomationProperties", "TalkBack", "VoiceOver", "Narrator", "accessible MAUI", "heading levels", "semantic description", "announce to screen reader", "accessibility audit". DO NOT USE FOR: general UI layout (use maui-collectionview or maui-shell-navigation), animations (use maui-animations), or gestures (use maui-gestures).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-accessibility

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈170 tokens for metadata: the name and description. ≈798 when used: this file. ≈614 more on demand in 1 file.

Description uses 8.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈679 characters, or 8.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

.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.
  2. Buttons/Controls: Ensure icon-only buttons have Description. Text buttons generally don't need it.
  3. Entries/Editors: Use Placeholder for context. Add Hint only if extra instruction is needed. Avoid Description (Android breakage).
  4. Labels: Do not add Description — let Text speak for itself. Add HeadingLevel to section headers.
  5. Headings: Mark page title as Level1, section titles as Level2, etc.
  6. Grouping: Avoid Description on layout containers (iOS breakage). Use ExcludedWithChildren to hide decorative groups.
  7. Dynamic content: Call SemanticScreenReader.Announce for status changes. Use SetSemanticFocus after navigation or error display.
  8. Tab order: Set TabIndex on interactive controls for logical order.
  9. Test: Run TalkBack (Android), VoiceOver (iOS/Mac), and Narrator (Windows) to verify reading order and actions.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The analyzed skill contains only documentation, code references, and best practices for .NET MAUI accessibility implementation. No malicious patterns, external dependencies, or security risks were identified.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-accessibility