Avalonia Pro Max/review Checklist

Avalonia UI Pre-Delivery Checklist

Run this before merging UI work or cutting a release. Each item maps back to a sub-skill if it fails.

How to Use

1. Open every screen at default window size and at compact (640 px wide) and wide (1600+ px).
2. Toggle RequestedThemeVariant between Light and Dark.
3. Tab through every screen with the keyboard only.
4. Run a screen reader on the main flows (Narrator on Win, VoiceOver on macOS).
5. Profile a session with Avalonia DevTools (F12) for layout/render issues.
6. Tick each box. If anything fails → fix → re-run from the top.

---

Design Tokens & Theming → design-system

• [ ] No hard-coded color hex values in any view (all via DynamicResource)
• [ ] No magic spacing numbers — every Margin/Padding references the spacing scale
• [ ] No magic font sizes — every FontSize references the type scale
• [ ] Both Light and Dark theme dictionaries provided for every semantic brush
• [ ] App responds correctly when OS theme changes at runtime
• [ ] One accent color, used consistently
• [ ] Text/background pairs verified ≥4.5:1 in both themes
• [ ] Disabled states use a token, not arbitrary opacity

Theme Library → themes

• [ ] Exactly one base theme imported (no Fluent + Material conflict)
• [ ] Theme NuGets at supported version for the Avalonia version in use
• [ ] No app code depends on internal theme NuGet brush keys (only via own semantic tokens)
• [ ] Custom title bar / SukiWindow / chrome behaves on Win, macOS, Linux

Component Quality → components

• [ ] All buttons use shared classes (primary / secondary / ghost / danger / icon)
• [ ] Icon-only buttons have ≥36×36 hit area (desktop) or 44×44 (touch)
• [ ] Cards use the shared Border.card style — no per-view ad-hoc cards
• [ ] Forms have visible labels (not placeholder-only)
• [ ] Form errors render inline, not only in a top banner
• [ ] Destructive actions confirmed via dialog or use danger class
• [ ] Empty states show icon + headline + description + CTA
• [ ] Loading states use skeleton or progress indicator (not spinner alone for >1s)
• [ ] Toasts auto-dismiss in 3–5s and are not focus-stealing
• [ ] No "click here" — link/button labels describe their action

Motion → motion

• [ ] Hover/press feedback ≤150 ms
• [ ] Page transitions 200–300 ms with easing
• [ ] No Width / Height / Margin animation
• [ ] All Transitions declarations have explicit Easing
• [ ] Exit animations ~70% of enter duration
• [ ] At most 2–3 concurrent animations per visible screen
• [ ] Reduced-motion path tested (durations → zero)
• [ ] Looping animations used sparingly and only on small elements

Accessibility → accessibility

• [ ] Every icon-only button has AutomationProperties.Name
• [ ] Every form input is associated with a LabeledBy or visible `` label
• [ ] Required fields marked with AutomationProperties.IsRequiredForForm
• [ ] Tab order matches visual reading order
• [ ] Focus ring visible (not removed) on every interactive element
• [ ] No information conveyed by color alone (icon/text always paired)
• [ ] Live regions (AutomationProperties.LiveSetting) on toast / status updates
• [ ] Screen reader reads each main screen meaningfully
• [ ] Verified at OS DPI 100/150/200%
• [ ] Verified in Windows High Contrast (or platform equivalent)
• [ ] All keyboard shortcuts present on macOS as Cmd and Windows as Ctrl
• [ ] No MaxLines truncation without tooltip access to full text

Layout & Responsive → layout-patterns

• [ ] No fixed-pixel layout that breaks at 800-px window width
• [ ] Long-form text capped with MaxWidth (~720 px reading width)
• [ ] Long lists use VirtualizingStackPanel / ItemsRepeater
• [ ] Single vertical scroll per view (no nested scroll regions)
• [ ] MinWidth/MinHeight on Window set to a reasonable floor (e.g., 800×600)
• [ ] Sidebar collapses or overlays on compact widths
• [ ] Right panel hidden on compact widths
• [ ] Page padding scales (24+ desktop / 16 compact)
• [ ] Cards reflow (UniformGrid columns / WrapPanel) at narrow widths

Icons & Imagery → icons-imagery

• [ ] Single icon family across the app
• [ ] Icon sizes from the size scale token, never magic numbers
• [ ] Icons square (Width == Height)
• [ ] Icon Foreground/StrokeBrush bound to a semantic token
• [ ] No emoji used as a structural icon
• [ ] Brand logo is the official asset, correct proportions
• [ ] App icons supplied at all required sizes (Win ICO, macOS ICNS, Linux PNG set)
• [ ] PNG raster images compressed
• [ ] Network images loaded asynchronously with placeholder

Performance

• [ ] CompiledBindings enabled (default in Avalonia 11+)
• [ ] No INotifyPropertyChanged storms — verify with Avalonia DevTools
• [ ] No allocation in Render() overrides
• [ ] Lists ≥100 items virtualized
• [ ] Images >256 px load via async loader and dispose properly
• [ ] Scroll stays at 60 fps on a mid-tier machine
• [ ] First-window-shown < 1s after launch (cold start)
• [ ] No console warnings (avalonia: WARN ...) in release build

Platform Parity

• [ ] Built and tested on Windows
• [ ] Built and tested on macOS
• [ ] Built and tested on Linux (X11 and Wayland if applicable)
• [ ] Tested on Avalonia.Mobile (Android/iOS) if app targets mobile
• [ ] Tested on WASM (browser) if app targets web
• [ ] Title bar/menu behavior correct per platform (macOS app-menu, Windows custom chrome)
• [ ] File dialogs use IStorageProvider (cross-platform) — not WinForms OpenFileDialog
• [ ] Fonts render correctly on all platforms (variable fonts work; fallbacks provided)
• [ ] Keyboard shortcuts match platform conventions (Cmd on macOS)

Final Polish

• [ ] No XAML warnings in build output
• [ ] App.axaml Styles ordered: theme → tokens → app styles
• [ ] Unused styles / resources removed
• [ ] All x:Name declarations are intentional and used
• [ ] Localization-ready: no English strings hard-coded if app is multi-language (use Resx/Avalonia.Localization)
• [ ] Designer-mode preview works (d:DesignWidth/d:DesignHeight valid)
• [ ] No MessageBox.Show left in production code (use IDialogService / FluentAvalonia ContentDialog)

---

Sign-off Template

✅ Visual Quality (tokens, themes, theme-variant tested both modes)
✅ Component Quality (shared styles, no ad-hoc)
✅ Motion (timing, easing, reduced-motion path)
✅ Accessibility (a11y props, keyboard, contrast, screen reader)
✅ Layout & Responsive (compact / wide tested)
✅ Icons & Imagery (single family, semantic colors)
✅ Performance (60 fps scroll, virtualized lists)
✅ Platform Parity (Win/macOS/Linux at minimum)
✅ Final Polish (no warnings, no leftover strings)

Reviewer: ____________  Date: ____________

If any item is ❌, link the relevant sub-skill in the PR review and request changes.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: linuxdevel
• Source: linuxdevel/Avalonia-skills
• License: MIT

Install and usage instructions live in the source repository linked above.