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 scal

SKILL.md

GitHub

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, PlatformSettings 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.


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

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:

  • TextMutedBrush over SurfaceBrush often fails — use Slate 600+ on light, Slate 400+ on dark.
  • Accent text on white usually needs Blue 600+, not Blue 500.
  • Disabled buttons at 50% opacity may fail 3:1 against accent.

Don't Convey by Color Alone

Bad: Status as a single colored dot. Good: Color + icon + text:

<StackPanel Orientation="Horizontal" Spacing="6">
  <Ellipse Width="8" Height="8"
           Fill="{DynamicResource SuccessBrush}"
           AutomationProperties.AccessibilityView="Raw"/>
  <PathIcon Data="{StaticResource CheckGeometry}" Width="14" Height="14"
            Foreground="{DynamicResource SuccessBrush}"
            AutomationProperties.AccessibilityView="Raw"/>
  <TextBlock Text="Active" Foreground="{DynamicResource TextPrimaryBrush}"/>
</StackPanel>

Forms — Accessible Validation

<StackPanel Spacing="4">
  <TextBlock x:Name="LblEmail" Text="Email"/>
  <TextBox Text="{Binding Email}"
           AutomationProperties.LabeledBy="{Binding ElementName=LblEmail}"
           AutomationProperties.IsRequiredForForm="True"/>
  <TextBlock Text="{Binding EmailError}"
             IsVisible="{Binding HasEmailError}"
             Foreground="{DynamicResource DangerBrush}"
             AutomationProperties.LiveSetting="Polite"/>
</StackPanel>

Move focus to first invalid field on submit:

if (!IsValid && firstInvalid is Control c) c.Focus(NavigationMethod.Tab);

Screen Reader Live Regions (Toasts)

<TextBlock x:Name="StatusLine"
           Text="{Binding Status}"
           AutomationProperties.LiveSetting="Polite"
           AutomationProperties.Name="Status"/>

Polite waits until idle; Assertive interrupts. Use Assertive only for errors and important blocks.


Dynamic Text Scaling

Avoid fixed FontSize literals in views — drive everything from your FontSize* resources. Bind a global scale factor when needed:

<TextBlock FontSize="{Binding FontSize, Source={x:Static app:UserPrefs.Instance},
                              Converter={StaticResource ScaleConverter}}"/>

Avoid:

  • Fixed Height on text containers — text gets clipped at 200% scale.
  • MaxLines="1" without TextTrimming="CharacterEllipsis" and a tooltip.

Test at 100%, 150%, 200% OS DPI scaling.


High-Contrast Mode

Windows high-contrast: FluentTheme adapts most colors. For custom controls:

<Style Selector="Border.card">
  <Setter Property="BorderBrush" Value="{DynamicResource SystemControlForegroundBaseHighBrush}"/>
  <Setter Property="BorderThickness" Value="1"/>
</Style>

Or supply a third theme dictionary keyed HighContrast (Avalonia respects custom variants when registered).


Touch Targets

Even on desktop, touch users exist (Surface, tablet, kiosk). Min visible size or padded hit-area: 36×36 px (desktop), 44×44 px (touch/mobile).

Expand hit area without enlarging visual:

<Button Padding="10" MinWidth="36" MinHeight="36">
  <PathIcon Data="…" Width="16" Height="16"/>
</Button>

Keep ≥8 px between adjacent tap targets.


Reduced Motion

See avalonia-pro-max/motion — every animation must have a zero-duration fallback.


Testing

  • Tab through every screen — can you reach and operate every control?
  • Activate Windows Narrator / macOS VoiceOver / Orca — read each major screen.
  • Run the app at OS DPI 200%.
  • Toggle high contrast.
  • Use the Avalonia DevTools Visual Tree → look for unnamed actionable controls.
  • For UI tests, set AutomationProperties.AutomationId on every control under test.

Common Mistakes

  • Icon-only button without AutomationProperties.Name — invisible to screen readers.
  • Removed focus ring "for cleanliness" — keyboard users are blocked.
  • TextBlock used as a clickable header — not focusable, no role; use Button.ghost instead.
  • Color-only error indication — colorblind users miss it.
  • MaxLines truncation without tooltip — text scaled to 200% gets clipped silently.
  • KeyBinding on Window only — won't fire if focus is in a TextBox that swallows the key. Use RoutedCommand or also bind on the TextBox.
  • Different shortcuts on Win vs macOS not provided — provide both Ctrl+ and Cmd+.
  • AutomationProperties.AccessibilityView="Raw" on a meaningful control — hides it entirely.
  • Missing AutomationProperties.LabeledBy between visible label and input.