跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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:

APIPurpose
AutomationProperties.* attached propsNames, descriptions, roles, item status
Focusable / IsTabStop / TabIndexKeyboard traversal
Focus pseudoclasses (:focus, :focus-visible, :focus-within)Visible focus indication
KeyBindings, HotKey, KeyGestureShortcuts
RequestedThemeVariant, platform settings (TopLevel.PlatformSettings (11.x), visual.GetPlatformSettings() (12.0+))High-contrast / dark mode / reduced motion
AccessKey (_File)Mnemonic underline shortcuts
ToolTip.TipHover 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.PlaceholderText is accessible to screen readers.
  • (12.0+) TopLevel.PlatformSettings is removed. Use visual.GetPlatformSettings() (VisualExtensions). In 11.x use TopLevel.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:

PropertyWhenExample
AutomationProperties.NameAlways for icon-only / image-only / unlabeled controls"Search"
AutomationProperties.HelpTextLong-form explanation"Searches across all projects"
AutomationProperties.AcceleratorKeyDisplay the keyboard shortcut"Ctrl+K"
AutomationProperties.AccessibilityViewContent / Control / Raw — control visibility to ATRaw for purely decorative
AutomationProperties.IsRequiredForFormRequired form fieldsTrue
AutomationProperties.LabeledByWhen a TextBlock labels another control{Binding ElementName=EmailLabel}
AutomationProperties.LiveSettingPolite/Assertive live regionsPolite for toasts
AutomationProperties.ItemStatusDynamic state (e.g., "Saving…")"3 of 5 selected"
AutomationProperties.AutomationIdStable 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>
ModeEffect
Continue (default)Tab traverses normally
LocalTab cycles within the container
CycleCycles within and stops
OnceContainer as a whole gets one tab stop
NoneSkipped

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

ElementMin ratioTool
Body text on background4.5 : 1WCAG AA
Large text (≥18px / ≥14px bold)3 : 1WCAG AA
UI components (icon, focus ring, border)3 : 1WCAG 2.2
Disabled textexempt (but make it clearly disabled)—

Validate every brush pair light and dark. Common pitfalls:

  • TextMutedBrush ov
阅读完整来源 ↗