rudironsoni 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
@* Use semantic HTML elements for structure *@
<nav aria-label="Main navigation">
<ul>
<li><a href="/products">Products</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
<main>
<h1>Product Catalog</h1>
@* Image with alt text *@
<img src="hero.png" alt="Product showcase displaying three featured items" />
@* Decorative image hidden from accessibility tree *@
<img src="divider.svg" alt="" role="presentation" />
@* Button with accessible name from content *@
<button @onclick="AddToCart">Add to Cart</button>
@* Icon button requires aria-label *@
<button @onclick="ToggleFavorite" aria-label="Add to favorites">
<span class="icon-heart" aria-hidden="true"></span>
</button>
</main>
```text
### Keyboard Event Handling
```razor
<div role="listbox"
tabindex="0"
aria-label="Product list"
aria-activedescendant="@_activeId"
@onkeydown="HandleKeyDown"
@onkeydown:preventDefault>
@foreach (var product in Products)
{
<div id="@($"product-{product.Id}")"
role="option"
aria-selected="@(product.Id == SelectedId)"
@onclick="() => Select(product)">
@product.Name
</div>
}
</div>
@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 *@
<div aria-live="polite" aria-atomic="true">
@if (_statusMessage is not null)
{
<p>@_statusMessage</p>
}
</div>
@* Assertive: interrupts current speech (use sparingly) *@
<div aria-live="assertive" role="alert">
@if (_errorMessage is not null)
{
<p>@_errorMessage</p>
}
</div>
```text
### Form Accessibility
```razor
<EditForm Model="@_model"
<DataAnnotationsValidator />
<div>
<label for="product-name">Product name</label>
<InputText id="product-name"
@bind-Value="_model.Name"
aria-describedby="name-error"
aria-invalid="@(_nameInvalid ? "true" : null)" />
<ValidationMessage For="() => _model.Name" id="name-error" />
</div>
<div>
<label for="quantity">Quantity</label>
<InputNumber id="quantity"
@bind-Value="_model.Quantity"
aria-describedby="quantity-help"
min="1" max="100" />
<span id="quantity-help">Enter a value between 1 and 100</span>
</div>
<button type="submit">Submit Order</button>
</EditForm>
```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
<!-- Description: primary screen reader announcement -->
<Image Source="product.png"
SemanticProperties.Description="Product photo showing a blue widget" />
<!-- Hint: additional context about an action -->
<Button Text="Add to Cart"
SemanticProperties.Hint="Adds the current product to your shopping cart" />
<!-- HeadingLevel: enables heading-based navigation -->
<Label Text="Order Summary"
SemanticProperties.HeadingLevel="Level1" />
<Label Text="Items"
SemanticProperties.HeadingLevel="Level2" />
```text
**Key APIs:**
- `SemanticProperties.Description` -- short text the screen reader announces (equivalent to `accessibilityLabel` on iOS,
`contentDescription` on Android)
- `SemanticProperties.Hint` -- additional purpose context (equivalent to `accessibilityHint` on iOS)
- `SemanticProperties.HeadingLevel` -- marks headings (Level1 through Level9); Android and iOS only support a single
heading level, Windows supports all 9
**Platform warning:** Do not set `SemanticProperties.Description` on a `Label` -- it overrides the `Text` property for
screen readers, creating a mismatch between visual and spoken text. Do not set `SemanticProperties.Description` on
`Entry` or `Editor` on Android -- use `Placeholder` or `SemanticProperties.Hint` instead, because Description conflicts
with TalkBack actions.
### Legacy AutomationProperties
`AutomationProperties` are the older Xamarin.Forms API, superseded by `SemanticProperties` in MAUI. Use
`SemanticProperties` for new code.
| Legacy API | Replacement |
| -------------------------------- | ----------------------------------------------------------- |
| `AutomationProperties.Name` | `SemanticProperties.Description` |
| `AutomationProperties.HelpText` | `SemanticProperties.Hint` |
| `AutomationProperties.LabeledBy` | Bind `SemanticProperties.Description` to the label's `Text` |
`AutomationProperties.IsInAccessibleTree` and `AutomationProperties.ExcludedWithChildren` remain useful for controlling
accessibility tree inclusion.
### Programmatic Focus and Announcements
```csharp
// Move screen reader focus to a specific element
myLabel.SetSemanticFocus();
// Announce text to the screen reader without moving focus
SemanticScreenReader.Default.Announce("Item added to cart successfully.");
```text
### Accessible Custom Controls
When building custom controls, ensure accessibility metadata is set:
```csharp
public class RatingControl : ContentView
{
private int _rating;
public int Rating
{
get => _rating;
set
{
_rating = value;
SemanticProperties.SetDescription(this,
$"Rating: {value} out of 5 stars");
SemanticScreenReader.Default.Announce(
$"Rating changed to {value} stars");
}
}
}
```text
For MAUI project structure, MVVM patterns, and platform services, see [skill:dotnet-maui-development].
---
## WinUI Accessibility (In-Depth)
WinUI 3 / Windows App SDK builds on the Microsoft UI Automation framework. Built-in controls include automation support
by default. Custom controls need automation peers.
### AutomationProperties
```xml
<!-- Name: primary accessible name for screen readers -->
<Image Source="ms-appx:///Assets/product.png"
AutomationProperties.Name="Product photo showing a blue widget" />
<!-- HelpText: supplementary description -->
<Button Content="Add to Cart"
AutomationProperties.HelpText="Adds the current product to your shopping cart" />
<!-- LabeledBy: associates a label with a control -->
<TextBlock x:Name="QuantityLabel" Text="Quantity:" />
<NumberBox AutomationProperties.LabeledBy="{x:Bind QuantityLabel}"
Value="{x:Bind ViewModel.Quantity, Mode=TwoWay}" />
<!-- Hide decorative elements from accessibility tree -->
<Image Source="ms-appx:///Assets/divider.png"
AutomationProperties.AccessibilityView="Raw" />
```text
### Custom Automation Peers
For custom controls, implement an `AutomationPeer` to expose the control to UI Automation clients:
```csharp
// Custom control
public sealed class StarRating : Control
{
public int Value
{
get => (int)GetValue(ValueProperty);
set => SetValue(ValueProperty, value);
}
public static readonly DependencyProperty ValueProperty =
DependencyProperty.Register(nameof(Value), typeof(int),
typeof(StarRating), new PropertyMetadata(0, OnValueChanged));
private static void OnValueChanged(DependencyObject d,
DependencyPropertyChangedEventArgs e)
{
if (FrameworkElementAutomationPeer
.FromElement((StarRating)d) is StarRatingAutomationPeer peer)
{
peer.RaiseValueChanged((int)e.OldValue, (int)e.NewValue);
}
}
protected override AutomationPeer OnCreateAutomationPeer()
=> new StarRatingAutomationPeer(this);
}
// Automation peer (using Microsoft.UI.Xaml.Automation.Provider)
public sealed class StarRatingAutomationPeer
: FrameworkElementAutomationPeer, IRangeValueProvider
{
private StarRating Owner => (StarRating)base.Owner;
public StarRatingAutomationPeer(StarRating owner) : base(owner) { }
protected override string GetClassNameCore() => nameof(StarRating);
protected override string GetNameCore()
=> $"Rating: {Owner.Value} out of 5 stars";
protected override AutomationControlType GetAutomationControlTypeCore()
=> AutomationControlType.Slider;
// IRangeValueProvider
public double Value => Owner.Value;
public double Minimum => 0;
public double Maximum => 5;
public double SmallChange => 1;
public double LargeChange => 1;
public bool IsReadOnly => false;
public void SetValue(double value)
=> Owner.Value = (int)Math.Clamp(value, Minimum, Maximum);
public void RaiseValueChanged(int oldValue, int newValue)
{
RaisePropertyChangedEvent(
RangeValuePatternIdentifiers.ValueProperty,
(double)oldValue, (double)newValue);
}
}
```text
### Keyboard Accessibility in WinUI
WinUI XAML controls provide built-in keyboard support. Ensure custom controls follow the same patterns:
```xml
<!-- TabIndex controls navigation order -->
<TextBox Header="First name" TabIndex="1" />
<TextBox Header="Last name" TabIndex="2" />
<Button Content="Submit" TabIndex="3" />
<!-- AccessKey provides keyboard shortcuts (Alt + key) -->
<Button Content="Save" AccessKey="S" />
<Button Content="Delete" AccessKey="D" />
```text
For WinUI project setup, XAML patterns, and Windows integration, see [skill:dotnet-winui].
---
## WPF Accessibility (Brief)
WPF on .NET 8+ uses the same UI Automation framework as WinUI. The APIs are nearly identical with namespace differences.
- `AutomationProperties.Name`, `AutomationProperties.HelpText`, `AutomationProperties.LabeledBy` work the same as in
WinUI
- Custom controls override `OnCreateAutomationPeer()` and return a `FrameworkElementAutomationPeer` subclass
- WPF Fluent theme (.NET 9+) includes high-contrast support automatically
- Use `AutomationProperties.LiveSetting` for live region announcements
```xml
<!-- WPF accessibility follows the same pattern as WinUI -->
<Image Source="product.png"
AutomationProperties.Name="Product photo" />
<TextBlock x:Name="StatusLabel"
AutomationProperties.LiveSetting="Polite"
Text="{Binding StatusText}" />
```text
For WPF development patterns on .NET 8+, see [skill:dotnet-wpf-modern].
---
## Uno Platform Accessibility (Brief)
Uno Platform follows UWP/WinUI `AutomationProperties` patterns since its API surface is WinUI-compatible.
- `AutomationProperties.Name`, `AutomationProperties.HelpText`, `AutomationProperties.LabeledBy` work cross-platform
- Custom `AutomationPeer` implementations follow the WinUI pattern
- On WebAssembly, Uno maps `AutomationProperties` to HTML ARIA attributes automatically
- Platform-specific behavior may vary -- test on each target (Windows, iOS, Android, WASM)
For Uno Platform development patterns, see [skill:dotnet-uno-platform]. For per-target deployment and testing, see
[skill:dotnet-uno-targets].
---
## TUI Accessibility (Brief)
Terminal UI frameworks have inherent accessibility limitations. Screen reader support depends on the terminal emulator
and operating system.
**Terminal.Gui (v2):**
- Screen readers can read terminal text content via the terminal emulator's accessibility support
- No programmatic accessibility API equivalent to ARIA or AutomationProperties
- Logical tab order follows the `TabIndex` property on views
- High contrast is managed by terminal color themes, not the app
**Spectre.Console:**
- Output-only library -- screen readers read terminal text buffer directly
- Use plain text fallbacks for complex visual elements (tables, trees) when accessibility is critical
- `AnsiConsole.Profile.Capabilities` can detect terminal features but not screen reader presence
**Honest constraint:** TUI apps cannot programmatically control screen reader behavior. Terminal emulators provide
varying levels of accessibility support. For applications where accessibility is a hard requirement, consider a GUI
framework (Blazor, MAUI, WinUI) instead.
For Terminal.Gui patterns, see [skill:dotnet-terminal-gui]. For Spectre.Console patterns, see
[skill:dotnet-spectre-console].
---
## Accessibility Testing Tools
### Per-Platform Testing
| Platform | Primary Tool | Secondary Tools |
| ------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Windows | [Accessibility Insights for Windows](https://accessibilityinsights.io/) | Narrator (Win+Ctrl+Enter), Inspect.exe (Windows SDK) |
| Web (Blazor) | [axe-core](https://github.com/dequelabs/axe-core) / axe DevTools | Lighthouse (Chrome), WAVE, NVDA, VoiceOver (macOS) |
| Android | [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570) | TalkBack, Android Studio Layout Inspector |
| iOS / macOS | Accessibility Inspector (Xcode) | VoiceOver (built-in), XCUITest accessibility assertions |
### Automated Testing Integration
```csharp
// Blazor: integrate axe-core with Playwright for automated accessibility testing
// Requires: Deque.AxeCore.Playwright NuGet package
// Install: dotnet add package Deque.AxeCore.Playwright
var axeResults = await new Deque.AxeCore.Playwright.AxeBuilder(page)
.AnalyzeAsync();
// Check for violations
Assert.Empty(axeResults.Violations);
// WinUI/WPF: use Accessibility Insights for Windows CLI in CI pipelines
// Requires: AccessibilityInsights.CLI (available via Microsoft Store or direct download)
```text
### Manual Testing Checklist
1. **Keyboard-only navigation** -- tab through entire app without mouse; verify all functionality is reachable
2. **Screen reader walkthrough** -- enable Narrator/VoiceOver/TalkBack and navigate the full workflow
3. **High contrast** -- enable system high-contrast theme and verify all content remains visible
4. **Zoom/scaling** -- increase text size to 200% and verify layout does not break or clip content
5. **Color contrast** -- verify all text and interactive elements meet WCAG AA ratios (4.5:1 for text, 3:1 for large
text and UI components)
---
## WCAG Reference
This skill references the
[Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) as the global
accessibility standard. WCAG 2.1 is the current baseline; WCAG 2.2 adds additional criteria for mobile and cognitive
accessibility.
**Four principles (POUR):**
1. **Perceivable** -- information must be presentable in ways all users can perceive
2. **Operable** -- UI components must be operable by all users
3. **Understandable** -- information and UI operation must be understandable
4. **Robust** -- content must be robust enough to work with assistive technologies
**Conformance levels:** A (minimum), AA (recommended target for most apps), AAA (enhanced). Most legal requirements and
industry standards target WCAG 2.1 Level AA.
**Note:** This skill provides technical implementation guidance. It does not constitute legal advice regarding
accessibility compliance requirements, which vary by jurisdiction and application type.
---
## Agent Gotchas
1. **Do not set `SemanticProperties.Description` on MAUI `Label` controls.** It overrides the `Text` property for screen
readers, causing a mismatch between visual and spoken content. Labels are already accessible via their `Text`
property.
2. **Do not set `SemanticProperties.Description` on MAUI `Entry`/`Editor` on Android.** Use `Placeholder` or
`SemanticProperties.Hint` instead -- `Description` conflicts with TalkBack actions on these controls.
3. **Do not use `AutomationProperties.Name` or `AutomationProperties.HelpText` for new MAUI code.** Use
`SemanticProperties` instead (the MAUI-native API). `AutomationProperties.IsInAccessibleTree` and
`ExcludedWithChildren` remain valid for controlling accessibility tree inclusion.
4. **Do not omit `aria-label` on icon-only Blazor buttons.** Buttons without visible text content are invisible to
screen readers unless `aria-label` or `aria-labelledby` is set.
5. **Do not use `aria-live="assertive"` for routine status updates.** Assertive interrupts the screen reader
immediately. Use `aria-live="polite"` for non-critical updates; reserve assertive for errors and time-critical
alerts.
6. **Do not assume TUI apps are accessible by default.** Terminal screen reader support varies dramatically by emulator
and OS. Always provide alternative output formats for critical accessibility scenarios.
7. **Do not hardcode colors without verifying contrast ratios.** Use tools (Accessibility Insights, Lighthouse) to
verify WCAG AA compliance. System high-contrast themes must also be tested.
8. **Do not forget `AccessKey` on frequently used WinUI/WPF buttons.** Access keys (Alt+key shortcuts) are essential for
keyboard-dependent users and are trivial to add.
---
## Prerequisites
- .NET 8.0+ (baseline for all frameworks)
- Framework-specific SDKs: MAUI workload, Windows App SDK (WinUI), Blazor project template
- Testing tools: Accessibility Insights (Windows), axe-core (web), Xcode Accessibility Inspector (macOS/iOS)
- Screen readers for manual testing: Narrator (Windows), VoiceOver (macOS/iOS), TalkBack (Android), NVDA (Windows, free)
---
## Code Navigation (Serena MCP)
**Primary approach:** Use Serena symbol operations for efficient code navigation:
1. **Find definitions**: `serena_find_symbol` instead of text search
2. **Understand structure**: `serena_get_symbols_overview` for file organization
3. **Track references**: `serena_find_referencing_symbols` for impact analysis
4. **Precise edits**: `serena_replace_symbol_body` for clean modifications
**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine
**Example workflow:**
```text
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"
# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
```
## References
- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/)
- [MAUI Accessibility (SemanticProperties)](https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/accessibility)
- [WinUI Accessibility Overview](https://learn.microsoft.com/en-us/windows/apps/design/accessibility/accessibility-overview)
- [Blazor Accessibility](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/accessibility)
- [UI Automation Overview](https://learn.microsoft.com/en-us/windows/desktop/WinAuto/uiauto-uiautomationoverview)
- [Accessibility Insights](https://accessibilityinsights.io/)
- [axe-core (Deque)](https://github.com/dequelabs/axe-core)