Menú
Building accessible .NET UI. SemanticProperties, ARIA, AutomationPeer, testing tools per platform.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Guidelines for writing TUnit tests in .NET, including setup, assertions, async testing, and best practices. Use when writing unit tests with TUnit framework, setting up TUnit in a .NET project, or migrating from other test frameworks to TUnit.
Hosted services, background jobs, outbox patterns, and graceful shutdown handling for ASP.NET Core applications. Includes patterns for reliable job processing, distributed systems, and lifecycle management. Use when implementing background processing in ASP.NET Core applications, handling outbox patterns for reliable message delivery, or managing graceful service shutdown.
Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, versioning, naming conventions, parameter ordering, and return types for NuGet packages and distributed systems. Use when designing public APIs for NuGet packages or libraries, making changes to existing public APIs, planning wire format changes for distributed systems, or reviewing pull requests for breaking changes.
Write modern, high-performance C# code using records, pattern matching, value objects, async/await, Span<T>/Memory<T>, and best-practice API design patterns. Emphasizes functional-style programming with C# 12+ features. Use when writing new C# code or refactoring existing code, designing public APIs for libraries or services, optimizing performance-critical code paths, or building async/await-heavy applications.
Choosing the right concurrency abstraction in .NET - from async/await for I/O to Channels for producer/consumer to Akka.NET for stateful entity management. Covers both high-level abstractions and low-level synchronization primitives. Use when deciding how to handle concurrent operations in .NET, evaluating whether to use async/await, Channels, or Akka.NET, or managing state across multiple concurrent entities.
Design .NET types for performance. Covers struct vs class decision matrix, sealed by default, readonly structs, ref struct and Span/Memory selection, FrozenDictionary, ValueTask, and collection return types. Use when designing new types and APIs, reviewing code for performance issues, choosing between class, struct, and record, or working with collections and enumerables.
| name | dotnet-accessibility |
| description | Building accessible .NET UI. SemanticProperties, ARIA, AutomationPeer, testing tools per platform. |
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 boundary: This skill owns cross-cutting accessibility principles and per-framework accessibility APIs. Framework-specific development patterns (project setup, MVVM, routing, deployment) are owned by the respective framework skills.
Out of scope: Framework project setup -- see individual framework skills. Legal compliance advice -- this skill references WCAG standards but does not provide 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.
These principles apply across all .NET UI frameworks. Framework-specific implementations follow in subsequent sections.
Provide meaningful names and descriptions for all interactive and informational elements. Screen readers rely on semantic metadata -- not visual appearance -- to convey UI structure.
All functionality must be operable via keyboard alone. Users who cannot use a mouse, pointer, or touch depend entirely on keyboard interaction.
Programmatic focus management ensures screen readers announce context changes correctly.
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 |
Blazor renders HTML, so standard web accessibility patterns apply. Use native HTML semantics and ARIA attributes to build accessible Blazor apps.
@* 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>
<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;
}
}
}
Announce dynamic content changes to screen readers without moving focus:
@* 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>
<EditForm Model="@_model" OnValidSubmit="HandleSubmit">
<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>
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 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).
<!-- 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" />
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 9Platform 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.
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.
// 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.");
When building custom controls, ensure accessibility metadata is set:
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");
}
}
}
For MAUI project structure, MVVM patterns, and platform services, see [skill:dotnet-maui-development].
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.
<!-- 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" />
For custom controls, implement an AutomationPeer to expose the control to UI Automation clients:
// 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);
}
}
WinUI XAML controls provide built-in keyboard support. Ensure custom controls follow the same patterns:
<!-- 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" />
For WinUI project setup, XAML patterns, and Windows integration, see [skill:dotnet-winui].
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 WinUIOnCreateAutomationPeer() and return a FrameworkElementAutomationPeer subclassAutomationProperties.LiveSetting for live region announcements<!-- 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}" />
For WPF development patterns on .NET 8+, see [skill:dotnet-wpf-modern].
Uno Platform follows UWP/WinUI AutomationProperties patterns since its API surface is WinUI-compatible.
AutomationProperties.Name, AutomationProperties.HelpText, AutomationProperties.LabeledBy work cross-platformAutomationPeer implementations follow the WinUI patternAutomationProperties to HTML ARIA attributes automaticallyFor Uno Platform development patterns, see [skill:dotnet-uno-platform]. For per-target deployment and testing, see [skill:dotnet-uno-targets].
Terminal UI frameworks have inherent accessibility limitations. Screen reader support depends on the terminal emulator and operating system.
Terminal.Gui (v2):
TabIndex property on viewsSpectre.Console:
AnsiConsole.Profile.Capabilities can detect terminal features but not screen reader presenceHonest 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].
| Platform | Primary Tool | Secondary Tools |
|---|---|---|
| Windows | Accessibility Insights for Windows | Narrator (Win+Ctrl+Enter), Inspect.exe (Windows SDK) |
| Web (Blazor) | axe-core / axe DevTools | Lighthouse (Chrome), WAVE, NVDA, VoiceOver (macOS) |
| Android | Accessibility Scanner | TalkBack, Android Studio Layout Inspector |
| iOS / macOS | Accessibility Inspector (Xcode) | VoiceOver (built-in), XCUITest accessibility assertions |
// 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)
This skill references the Web Content Accessibility 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):
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.
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.SemanticProperties.Description on MAUI Entry/Editor on Android. Use Placeholder or SemanticProperties.Hint instead -- Description conflicts with TalkBack actions on these controls.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.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.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.AccessKey on frequently used WinUI/WPF buttons. Access keys (Alt+key shortcuts) are essential for keyboard-dependent users and are trivial to add.