avalonia-pro-max/accessibility
Use when adding or auditing accessibility in an Avalonia app — AutomationProperties, focus order, keyboard navigation, contrast, screen reader (Narrator/NVDA/VoiceOver/Orca) support, dynamic text scaling, reduced motion. Maps WCAG 2.2 AA to Avalonia APIs.
linuxdevel · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add linuxdevel/Avalonia-skills --skill avalonia-pro-max/accessibility技能说明
name: avalonia-pro-max/accessibility description: Use when adding or auditing accessibility in an Avalonia app — AutomationProperties, focus order, keyboard navigation, contrast, screen reader (Narrator/NVDA/VoiceOver/Orca) support, dynamic text scaling, reduced motion. Maps WCAG 2.2 AA to Avalonia APIs.
Accessibility in Avalonia
Avalonia exposes accessibility through:
| API | Purpose |
|---|---|
AutomationProperties.* attached props | Names, descriptions, roles, item status |
Focusable / IsTabStop / TabIndex | Keyboard traversal |
Focus pseudoclasses (:focus, :focus-visible, :focus-within) | Visible focus indication |
KeyBindings, HotKey, KeyGesture | Shortcuts |
RequestedThemeVariant, platform settings (TopLevel.PlatformSettings (11.x), visual.GetPlatformSettings() (12.0+)) | High-contrast / dark mode / reduced motion |
AccessKey (_File) | Mnemonic underline shortcuts |
ToolTip.Tip | Hover and screen-reader hints |
Targets: WCAG 2.2 AA, plus Windows UI Automation, macOS NSAccessibility, Linux AT-SPI.
Version notes:
- (12.0+) Linux AT-SPI2 accessibility backend (Orca). In 11.x there is no AT-SPI2 backend, so Linux screen-reader support is not available.
- (12.0+) Validation errors are exposed through automation, and
TextBox.PlaceholderTextis accessible to screen readers. - (12.0+)
TopLevel.PlatformSettingsis removed. Usevisual.GetPlatformSettings()(VisualExtensions). In 11.x useTopLevel.GetTopLevel(this)?.PlatformSettings.
AutomationProperties (Required)
<Button Command="{Binding DeleteCommand}"
AutomationProperties.Name="Delete project"
AutomationProperties.HelpText="Permanently removes the current project and all its files">
<PathIcon Data="{StaticResource TrashIconGeometry}"/>
</Button>
Common properties:
| Property | When | Example |
|---|---|---|
AutomationProperties.Name | Always for icon-only / image-only / unlabeled controls | "Search" |
AutomationProperties.HelpText | Long-form explanation | "Searches across all projects" |
AutomationProperties.AcceleratorKey | Display the keyboard shortcut | "Ctrl+K" |
AutomationProperties.AccessibilityView | Content / Control / Raw — control visibility to AT | Raw for purely decorative |
AutomationProperties.IsRequiredForForm | Required form fields | True |
AutomationProperties.LabeledBy | When a TextBlock labels another control | {Binding ElementName=EmailLabel} |
AutomationProperties.LiveSetting | Polite/Assertive live regions | Polite for toasts |
AutomationProperties.ItemStatus | Dynamic state (e.g., "Saving…") | "3 of 5 selected" |
AutomationProperties.AutomationId | Stable test id (for UI tests, also used by AT) | "login.submit" |
Hide decorative elements
<PathIcon Data="{StaticResource ChevronGeometry}"
AutomationProperties.AccessibilityView="Raw"/>
Label association
<TextBlock x:Name="EmailLabel" Text="Email"/>
<TextBox AutomationProperties.LabeledBy="{Binding ElementName=EmailLabel}"/>
Focus Indication (Never Remove)
FluentTheme ships a focus ring. If you replace a ControlTheme, re-add it:
<Style Selector="Button:focus-visible /template/ ContentPresenter">
<Setter Property="BorderBrush" Value="{DynamicResource AccentBrush}"/>
<Setter Property="BorderThickness" Value="2"/>
</Style>
:focus-visible activates only when focus arrived from keyboard — preferred over :focus so mouse clicks don't show the ring. Always provide some visible cue on :focus too in case :focus-visible is not detected.
Minimum: 2px ring, contrast ≥3:1 against the surface.
Keyboard Navigation
Tab order
- Tab order follows logical tree by default.
- Override via
TabIndex="N"(lower = earlier). IsTabStop="False"on labels and decorative containers.- Group containers: set
KeyboardNavigation.TabNavigation="Local"on a panel to scope Tab within it.
Modes
<StackPanel KeyboardNavigation.TabNavigation="Cycle"
KeyboardNavigation.DirectionalNavigation="Contained">
…
</StackPanel>
| Mode | Effect |
|---|---|
Continue (default) | Tab traverses normally |
Local | Tab cycles within the container |
Cycle | Cycles within and stops |
Once | Container as a whole gets one tab stop |
None | Skipped |
Focus Traversal API (12.0+)
Avalonia 12 adds a Focus Traversal API: public IFocusManager (FindNextElement, TryMoveFocus, FindFirstFocusableElement, replacing KeyboardNavigationHandler.GetNext), cancellable focus changes, and FocusChangedEventArgs on GotFocus/LostFocus (replaces GotFocusEventArgs). Use it for programmatic focus moves (e.g. after closing a dialog or on a validation failure) instead of walking the visual tree. In 11.x use KeyboardNavigationHandler and GotFocusEventArgs.
Arrow-key navigation
Set KeyboardNavigation.DirectionalNavigation for Lists/grids to allow arrow keys.
Mnemonics
<MenuItem Header="_File"/> <!-- Alt+F -->
<Button Content="_Save" Command="{Binding SaveCommand}"/>
Shortcuts
<Window>
<Window.KeyBindings>
<KeyBinding Gesture="Ctrl+S" Command="{Binding SaveCommand}"/>
<KeyBinding Gesture="Ctrl+K" Command="{Binding OpenSearchCommand}"/>
<KeyBinding Gesture="Cmd+S" Command="{Binding SaveCommand}"/> <!-- macOS -->
</Window.KeyBindings>
</Window>
Also expose as HotKey on a Button:
<Button Content="Save" HotKey="Ctrl+S" Command="{Binding SaveCommand}"/>
Color Contrast
| Element | Min ratio | Tool |
|---|---|---|
| Body text on background | 4.5 : 1 | WCAG AA |
| Large text (≥18px / ≥14px bold) | 3 : 1 | WCAG AA |
| UI components (icon, focus ring, border) | 3 : 1 | WCAG 2.2 |
| Disabled text | exempt (but make it clearly disabled) | — |
Validate every brush pair light and dark. Common pitfalls:
TextMutedBrushov