# 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. - **Type:** Skill - **Install:** `agentstack add skill-linuxdevel-avalonia-skills-accessibility` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [linuxdevel](https://agentstack.voostack.com/s/linuxdevel) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [linuxdevel](https://github.com/linuxdevel) - **Source:** https://github.com/linuxdevel/Avalonia-skills/tree/main/skills/avalonia/avalonia-pro-max/accessibility ## Install ```sh agentstack add skill-linuxdevel-avalonia-skills-accessibility ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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) ```xml ``` 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 ```xml ``` ### Label association ```xml ``` --- ## Focus Indication (Never Remove) FluentTheme ships a focus ring. If you replace a ControlTheme, re-add it: ```xml ``` `: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 ```xml … ``` | 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 ```xml ``` ### Shortcuts ```xml ``` Also expose as `HotKey` on a Button: ```xml ``` --- ## 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: ```xml ``` --- ## Forms — Accessible Validation ```xml ``` Move focus to first invalid field on submit: ```csharp if (!IsValid && firstInvalid is Control c) c.Focus(NavigationMethod.Tab); ``` --- ## Screen Reader Live Regions (Toasts) ```xml ``` `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: ```xml ``` 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: ```xml ``` 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: ```xml ``` 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. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [linuxdevel](https://github.com/linuxdevel) - **Source:** [linuxdevel/Avalonia-skills](https://github.com/linuxdevel/Avalonia-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-linuxdevel-avalonia-skills-accessibility - Seller: https://agentstack.voostack.com/s/linuxdevel - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.