--- name: dotnet-accessibility description: >- Implements accessible .NET UI. SemanticProperties, ARIA, AutomationPeer, testing per platform. --- # dotnet-accessibility Cross-platform accessibility patterns for .NET UI frameworks: semantic markup, keyboard navigation, focus management, color contrast, and screen reader integration. In-depth coverage for Blazor (HTML ARIA), MAUI (SemanticProperties), and WinUI (AutomationProperties / UI Automation). Brief guidance with cross-references for WPF, Uno Platform, and TUI frameworks. ## Scope - Cross-platform accessibility principles (semantic markup, keyboard nav, focus, contrast) - Blazor accessibility (HTML ARIA attributes, screen reader patterns) - MAUI accessibility (SemanticProperties, platform-specific setup) - WinUI accessibility (AutomationProperties, UI Automation, AutomationPeer) - WPF, Uno Platform, and TUI accessibility guidance with cross-references ## Out of scope - Framework project setup -- see individual framework skills - Legal compliance advice (references WCAG but not legal guidance) - UI framework selection -- see [skill:dotnet-ui-chooser] Cross-references: [skill:dotnet-blazor-patterns] for Blazor hosting and render modes, [skill:dotnet-blazor-components] for Blazor component lifecycle, [skill:dotnet-maui-development] for MAUI patterns, [skill:dotnet-winui] for WinUI 3 patterns, [skill:dotnet-wpf-modern] for WPF on .NET 8+, [skill:dotnet-uno-platform] for Uno Platform patterns, [skill:dotnet-terminal-gui] for Terminal.Gui, [skill:dotnet-spectre-console] for Spectre.Console, [skill:dotnet-ui-chooser] for framework selection. --- ## Cross-Platform Principles These principles apply across all .NET UI frameworks. Framework-specific implementations follow in subsequent sections. ### Semantic Markup Provide meaningful names and descriptions for all interactive and informational elements. Screen readers rely on semantic metadata -- not visual appearance -- to convey UI structure. - Every interactive control must have an accessible name (text label, ARIA label, or automation property) - Images and icons must have text alternatives describing their purpose - Decorative elements should be hidden from the accessibility tree - Group related controls logically so screen readers announce them in context ### Keyboard Navigation All functionality must be operable via keyboard alone. Users who cannot use a mouse, pointer, or touch depend entirely on keyboard interaction. - Maintain a logical tab order that follows the visual reading flow - Provide visible focus indicators on all interactive elements - Support standard keyboard patterns: Tab/Shift+Tab for navigation, Enter/Space for activation, Escape to dismiss, arrow keys within composite controls - Avoid keyboard traps -- users must be able to navigate away from every control ### Focus Management Programmatic focus management ensures screen readers announce context changes correctly. - Move focus to newly revealed content (dialogs, expanded panels, inline notifications) - Return focus to the triggering element when dismissing overlays - Avoid stealing focus unexpectedly during background updates - Set initial focus on the primary action when a page or dialog loads ### Color Contrast Ensure text and interactive elements meet WCAG contrast ratios. | Element Type | Minimum Ratio (WCAG AA) | Enhanced Ratio (WCAG AAA) | | ----------------------------------- | ----------------------- | ------------------------- | | Normal text (< 18pt) | 4.5:1 | 7:1 | | Large text (>= 18pt or 14pt bold) | 3:1 | 4.5:1 | | UI components and graphical objects | 3:1 | 3:1 | - Do not rely on color alone to convey information (use icons, patterns, or text labels as supplements) - Support high-contrast themes and system color overrides - Test with color blindness simulation tools --- ## Blazor Accessibility (In-Depth) Blazor renders HTML, so standard web accessibility patterns apply. Use native HTML semantics and ARIA attributes to build accessible Blazor apps. ### Semantic HTML and ARIA ````razor @* Use semantic HTML elements for structure *@

Product Catalog

@* Image with alt text *@ Product showcase displaying three featured items

@* Decorative image hidden from accessibility tree *@

@* Button with accessible name from content *@ @* Icon button requires aria-label *@

```text ### Keyboard Event Handling ```razor @code { private string _activeId = ""; private void HandleKeyDown(KeyboardEventArgs e) { switch (e.Key) { case "ArrowDown": MoveSelection(1); break; case "ArrowUp": MoveSelection(-1); break; case "Enter": case " ": ConfirmSelection(); break; } } } ```text ### Live Regions Announce dynamic content changes to screen readers without moving focus: ```razor @* Polite: announced after current speech finishes *@

@if (_statusMessage is not null) {

@_statusMessage

}

@* Assertive: interrupts current speech (use sparingly) *@

@if (_errorMessage is not null) {

@_errorMessage

}

```text ### Form Accessibility ```razor

Product name

Quantity Enter a value between 1 and 100

```text For Blazor hosting models and render mode configuration, see [skill:dotnet-blazor-patterns]. For component lifecycle and EditForm patterns, see [skill:dotnet-blazor-components]. --- ## MAUI Accessibility (In-Depth) MAUI provides the `SemanticProperties` attached properties as the recommended accessibility API. These map to native platform accessibility APIs (VoiceOver on iOS/macOS, TalkBack on Android, Narrator on Windows). ### SemanticProperties ```xml

dotnet-accessibility

Install this skill

Comments