Skip to content

[Feature] Implement AutomationProperties.HeadingLevel for accessibilityΒ #22443

@mtmattei

Description

@mtmattei

f#XXXX### What would you like to be added? πŸ’‘

Feature Request

Summary

Implement AutomationProperties.HeadingLevel attached property to support screen reader heading navigation.

Current Behavior

Using AutomationProperties.HeadingLevel produces a build warning and has no effect:

warning Uno0001: Microsoft.UI.Xaml.Automation.AutomationProperties.SetHeadingLevel(
    Microsoft.UI.Xaml.DependencyObject,
    Microsoft.UI.Xaml.Automation.Peers.AutomationHeadingLevel
) is not implemented in Uno

Expected Behavior

HeadingLevel should mark elements as headings (Level1 through Level9) so screen readers can:

  • Announce elements as headings
  • Allow users to navigate by heading level (a core screen reader feature)

XAML Example

<TextBlock Text="My Tasks"
           Style="{StaticResource HeadlineLarge}"
           AutomationProperties.HeadingLevel="Level1" />

<TextBlock Text="Active Tasks"
           Style="{StaticResource TitleMedium}"
           AutomationProperties.HeadingLevel="Level2" />

Platform Mapping

Platform Native API
iOS UIAccessibilityTraits.header
Android AccessibilityNodeInfo.setHeading(true) (API 28+) or AccessibilityNodeInfoCompat
WASM role="heading" + aria-level="N"
macOS/Catalyst NSAccessibility.Role.heading
Skia/Desktop Platform-specific accessibility APIs

Why This Matters

  • WCAG 2.1 Success Criterion 1.3.1 (Info and Relationships) requires heading structure
  • WCAG 2.1 Success Criterion 2.4.6 (Headings and Labels) recommends descriptive headings
  • Screen reader users rely on heading navigation to understand page structure
  • This is a basic accessibility requirement for production apps

WinUI Reference

Additional Context

Discovered while building an Uno Platform app following WinUI accessibility best practices. Happy to contribute a PR if guidance is provided on the implementation approach.

Why is this needed? πŸ€”

Essential for making Uno Platform apps accessible to screen reader users who navigate by heading structure. This is a fundamental accessibility feature that all major platforms support natively.

Renderer 🎨

  • Skia
  • Native

For which platforms πŸ“±πŸ’»πŸ–₯️

All platforms 🌍

Anything else we need to know? πŸ’¬

This is related to #XXXX (AutomationProperties.HelpText) - both are core AutomationProperties features needed for accessible apps.

Metadata

Metadata

Assignees

No one assigned

    Labels

    difficulty/tbdCategorizes an issue for which the difficulty level needs to be defined.kind/enhancementNew feature or requesttriage/untriagedIndicates an issue requires triaging or verification

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions