wpfui Documentation

Technical Documentation: lepoco/wpfui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

WPF UI

Created with ❤ in Poland by Leszek Pomianowski and wonderful open-source community.
WPF UI provides the Fluent experience in your known and loved WPF framework. Intuitive design, themes, navigation and new immersive controls. All natively and effortlessly. Library changes the base elements like Page, ToggleButton or List, and also includes additional controls like Navigation, NumberBox, Dialog or Snackbar.

Deliver humanitarian aid directly to Ukraine
https://bank.gov.ua/en/about/humanitarian-aid-to-ukraine

Support Copy Chapter

To ensure you receive the expert guidance you need, we offer a variety of support plans designed to meet the diverse needs of our community. Whether you are looking to modernize your WPF applications or need assistance with our other libraries, our tailored support solutions are here to help. From priority email support to 24/7 dedicated assistance, we provide flexible plans to suit your project requirements.

Take a look at the lepo.co support plans
Sponsor WPF UI on GitHub

Getting started Copy Chapter

For a starter guide see our documentation.

WPF UI Gallery is a free application available in the Microsoft Store, with which you can test all functionalities.
https://apps.microsoft.com/store/detail/wpf-ui/9N9LKV8R9VGM?cid=windows-lp-hero

winget install 'WPF UI'

WPF UI is delivered via NuGet package manager. You can find the package here:
https://www.nuget.org/packages/wpf-ui/

Visual Studio
The plugin for Visual Studio 2022 let you easily create new projects using WPF UI.
https://marketplace.visualstudio.com/items?itemName=lepo.wpf-ui

Screenshots Copy Chapter

Works with Visual Studio Designer Copy Chapter

Custom Tray icon and menu in pure WPF Copy Chapter

Custom Windows 11 SnapLayout available for TitleBar Copy Chapter

Development Copy Chapter

If you want to propose a new functionality or submit a bugfix, create a Pull Request for the branch main.

How to use? Copy Chapter

First, your application needs to load custom styles, add in the MyApp\App.xaml file:

<Application
  ...
  xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
  <Application.Resources>
    <ResourceDictionary>
      <ResourceDictionary.MergedDictionaries>
        <ui:ThemesDictionary Theme="Light" />
        <ui:ControlsDictionary />
      </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
  </Application.Resources>
</Application>

If your application does not have MyApp\App.xaml file, use ApplicationThemeManager.Apply(frameworkElement) to apply/update the theme resource in the frameworkElement.

public partial class MainWindow
{
    public MainWindow()
    {
        InitializeComponent();
        ApplicationThemeManager.Apply(this);
    }
}

Now you can create fantastic apps, e.g. with one button:

<ui:FluentWindow
  ...
  xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
  <StackPanel>
      <ui:TitleBar Title="WPF UI"/>
      <ui:Card Margin="8">
          <ui:Button Content="Hello World" Icon="{ui:SymbolIcon Fluent24}" />
      </ui:Card>
  </StackPanel>
</ui:FluentWindow>

Microsoft Property Copy Chapter

Design of the interface, choice of colors and the appearance of the controls were inspired by projects made by Microsoft for Windows 11.
The Wpf.Ui.Gallery app includes icons from Microsoft WinUI 3 Gallery app. They are used here as an example of creating tools for Microsoft systems.

Segoe Fluent Icons Copy Chapter

WPF UI uses Fluent System Icons. Although this font was also created by Microsoft, it does not contain all the icons for Windows 11. If you need the missing icons, add Segoe Fluent Icons to your application.
According to the EULA of Segoe Fluent Icons we cannot ship a copy of it with this dll. Segoe Fluent Icons is installed by default on Windows 11, but if you want these icons in an application for Windows 10 and below, you must manually add the font to your application's resources.
https://docs.microsoft.com/en-us/windows/apps/design/style/segoe-fluent-icons-font
https://docs.microsoft.com/en-us/windows/apps/design/downloads/#fonts

In the app dictionaries, you can add an alternate path to the font

<FontFamily x:Key="SegoeFluentIcons">pack://application:,,,/;component/Fonts/#Segoe Fluent Icons</FontFamily>

Code of Conduct Copy Chapter

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community.

License Copy Chapter

WPF UI is free and open source software licensed under MIT License. You can use it in private and commercial projects.
Keep in mind that you must include a copy of the license in your project.

Overview (`docs/architecture/README.md`) Copy Section

WPF UI - Architecture Documentation

Overview Copy Chapter

WPF UI is an open-source library that implements the Microsoft Fluent Design System for Windows Presentation Foundation (WPF) applications. It provides 77+ custom controls, a full theming system with light/dark/high-contrast modes, Win32 interop for modern window chrome effects (Mica, Acrylic, Tabbed backdrops), navigation services, and icon support through the Fluent System Icons font family.

The library enables thousands of developers to modernize legacy WPF applications with contemporary Windows 11 visual styles without migrating to WinUI 3 or MAUI.

Table of Contents Copy Chapter

Architecture Views Copy Section

Software Design Documents (SDD) Copy Section

Cross-Cutting Concerns Copy Section

Architecture Decision Records (ADRs) Copy Section

Other Copy Section

Quick Architecture Summary Copy Chapter

WPF UI is organized as a set of layered NuGet packages built from a single solution:

• Wpf.Ui.Abstractions -- Zero-dependency contract interfaces (INavigationViewPageProvider, INavigationAware, INavigableView<T>). Targets .NET and .NET Standard 2.0/2.1 for maximum portability.
• Wpf.Ui -- Core library with 77+ controls, the theming engine, Win32 interop, services, converters, animations, and icon support. This is the primary NuGet package (WPF-UI).
• Wpf.Ui.DependencyInjection -- Microsoft.Extensions.DependencyInjection integration for type-based page resolution.
• Wpf.Ui.Tray -- System tray icon support via Shell32 P/Invoke.
• Wpf.Ui.SyntaxHighlight -- Syntax-highlighted code display control.
• Wpf.Ui.ToastNotifications -- Toast notification support (stub, not yet implemented).
• Wpf.Ui.FlaUI -- FlaUI automation element wrappers for integration testing.
• Wpf.Ui.FontMapper -- Build-time tool that generates SymbolRegular/SymbolFilled enums from Fluent System Icons font data.
• Wpf.Ui.Gallery -- Comprehensive demo application showcasing all controls.
• Wpf.Ui.Extension -- Visual Studio 2022 extension with project templates.

Key Architectural Concerns Copy Section

1. Control Architecture -- Folder-per-control pattern with paired .cs + .xaml files. Controls extend standard WPF base classes and implement capability interfaces (IAppearanceControl, IIconControl).
2. Theming System -- Runtime resource dictionary swapping managed by ApplicationThemeManager. Accent colors derived from system settings via WinRT UISettings or DWM registry.
3. Win32 Interop -- Three-layer architecture: CsWin32 source-generated P/Invoke, managed wrappers (UnsafeNativeMethods), and high-level utilities. Enables DWM backdrop effects, custom window chrome, and system theme detection.

Technology Stack Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Repository Structure Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Overview (`docs/templates/README.md`) Copy Section

This folder contains the source code for website themes used by docfx.exe.

Overview (`src/Wpf.Ui.Abstractions/README.md`) Copy Section

Wpf.Ui.Abstractions

Common interfaces and contracts for Wpf.Ui. Used to decouple core library features and enable extensibility.

Included types Copy Chapter

Wpf.Ui.Abstractions.INavigationViewPageProvider
Wpf.Ui.Abstractions.NavigationViewPageProviderExtensions
Wpf.Ui.Abstractions.Controls.INavigableView
Wpf.Ui.Abstractions.Controls.INavigationAware
Wpf.Ui.Abstractions.Controls.NavigationAware

Documentation can be found at https://wpfui.lepo.co/. We also have a tutorial over there for newcomers.

Overview (`src/Wpf.Ui.DependencyInjection/README.md`) Copy Section

Wpf.Ui.DependencyInjection

DI implementation for Wpf.Ui. Used to decouple core library features and enable extensibility.

Included types Copy Chapter

Wpf.Ui.DependencyInjection.DependencyInjectionNavigationViewPageProvider

Documentation can be found at https://wpfui.lepo.co/. We also have a tutorial over there for newcomers.

Overview (`src/Wpf.Ui.FlaUI/README.md`) Copy Section

Wpf.Ui.FlaUI

FlaUI automation helpers for Wpf.Ui. Provides test utilities for interacting with WPF controls in automated UI tests.

Included types Copy Chapter

Wpf.Ui.FlaUI.AutoSuggestBox

Docs: https://wpfui.lepo.co/

Overview (`src/Wpf.Ui.SyntaxHighlight/README.md`) Copy Section

Wpf.Ui.SyntaxHighlight

Syntax highlighting controls and utilities for Wpf.Ui. Enables code formatting and display in WPF applications.

Included types Copy Chapter

Wpf.Ui.SyntaxHighlight.Highlighter
Wpf.Ui.SyntaxHighlight.Controls.CodeBlock
Wpf.Ui.SyntaxHighlight.Markup.SyntaxHighlightDictionary

Docs: https://wpfui.lepo.co/

Overview (`src/Wpf.Ui.ToastNotifications/README.md`) Copy Section

Wpf.Ui.ToastNotifications

Toast notification support for Wpf.Ui. Provides a simple API for displaying toast messages in WPF applications.

Included types Copy Chapter

Wpf.Ui.ToastNotifications.Toast

Docs: https://wpfui.lepo.co/

Overview (`src/Wpf.Ui.Tray/README.md`) Copy Section

Wpf.Ui.Tray

System tray integration for Wpf.Ui. Provides services and controls for tray icons in WPF applications.

Included types Copy Chapter

Wpf.Ui.Tray.NotifyIconService
Wpf.Ui.Tray.INotifyIconService
Wpf.Ui.Tray.Controls.NotifyIcon
Wpf.Ui.Tray.TrayManager
Wpf.Ui.Tray.TrayHandler
Wpf.Ui.Tray.TrayData
Wpf.Ui.Tray.RoutedNotifyIconEvent
Wpf.Ui.Tray.INotifyIcon
Wpf.Ui.Tray.Hicon
Wpf.Ui.Tray.NotifyIconEventHandler

Docs: https://wpfui.lepo.co/

Overview (`src/Wpf.Ui/README.md`) Copy Section

WPF UI

WPF UI provides the Fluent experience in your known and loved WPF framework. Intuitive design, themes, navigation and new immersive controls. All natively and effortlessly. Library changes the base elements like Page, ToggleButton or List, and also includes additional controls like Navigation, NumberBox, Dialog or Snackbar.

Documentation can be found at https://wpfui.lepo.co/. We also have a tutorial over there for newcomers.

WPF UI Gallery is a free application available in the Microsoft Store, with which you can test all functionalities.
https://apps.microsoft.com/store/detail/wpf-ui/9N9LKV8R9VGM?cid=windows-lp-hero

winget install 'WPF UI'

Visual Studio
The plugin for Visual Studio 2022 let you easily create new projects using WPF UI.
https://marketplace.visualstudio.com/items?itemName=lepo.wpf-ui

Support plans Copy Chapter

To ensure you receive the expert guidance you need, we offer a variety of support plans designed to meet the diverse needs of our community. Whether you are looking to modernize your WPF applications or need assistance with our other libraries, our tailored support solutions are here to help. From priority email support to 24/7 dedicated assistance, we provide flexible plans to suit your project requirements.

Take a look at the lepo.co support plans

Help us keep working on this project Copy Chapter

Support the development of WPF UI and other innovative projects by becoming a sponsor on GitHub! Your monthly or one-time contributions help us continue to deliver high-quality, open-source solutions that empower developers worldwide.

Sponsor WPF UI on GitHub

Overview (`docs/architecture/appendix/diagrams/README.md`) Copy Section

Architecture Diagrams Index

This directory serves as an index of all architecture diagrams used throughout the WPF UI documentation.

Architecture Views Copy Chapter

Context Diagram Copy Section

NuGet Package Distribution Flowchart

• Location: views/context.md
• Type: Mermaid flowchart
• Purpose: Shows the NuGet package distribution flow from GitHub Actions CD through NuGet.org to developer machines
• Key Components: GitHub Actions CD, NuGet.org, Developer Machine

Logical Architecture Copy Section

Module/Package Dependency Diagram

• Location: views/logical-architecture.md
• Type: Mermaid graph TD
• Purpose: Shows dependencies between all 10 solution projects
• Key Components: Abstractions, Core, DI, Tray, SyntaxHighlight, Toast, Gallery, FlaUI, FontMapper, Extension

Core Library Internal Structure (Layer Diagram)

• Location: views/logical-architecture.md
• Type: Mermaid graph TB
• Purpose: Six-layer architecture of the core Wpf.Ui library
• Layers: Controls, Appearance/Theming, Services, Infrastructure, Win32 Interop, Resources

Control Architecture Class Diagram

• Location: views/logical-architecture.md
• Type: Mermaid classDiagram
• Purpose: Shows control inheritance and interface implementation patterns
• Key Components: WPF base classes, capability interfaces (IAppearanceControl, IIconControl), concrete controls

Target Framework Matrix

• Location: views/logical-architecture.md
• Type: Mermaid gantt chart
• Purpose: Visualizes TFM coverage across all modules
• Key Components: All solution projects with their target frameworks

Service Registration & DI Integration

• Location: views/logical-architecture.md
• Type: Mermaid sequenceDiagram
• Purpose: Shows Generic Host DI registration flow and runtime page resolution
• Key Components: IHostBuilder, IServiceCollection, IServiceProvider, NavigationView, INavigationViewPageProvider

Control Lifecycle State Diagram

• Location: views/logical-architecture.md
• Type: Mermaid stateDiagram-v2
• Purpose: Documents the complete lifecycle of WPF UI controls from construction through GC
• States: Constructed, Loaded, Template Applied, Themed, Unloaded, GC

Cross-Cutting Concerns Copy Chapter

Navigation Copy Section

Navigation System Lifecycle Sequence Diagram

• Location: cross-cutting/navigation.md
• Type: Mermaid sequenceDiagram
• Purpose: Complete flow from NavigationService.Navigate() through page resolution, caching, INavigationAware callbacks, and transition animation
• Key Components: Consumer Code, NavigationService, NavigationView, INavigationViewPageProvider, Page Cache, Frame, TransitionAnimationProvider

Page Cache Mode State Diagram

• Location: cross-cutting/navigation.md
• Type: Mermaid stateDiagram-v2
• Purpose: Illustrates the three caching strategies (Disabled, Enabled, Required) and their decision logic
• Key States: PageRequested, CheckCacheMode, CacheDisabled, CacheEnabled, CacheRequired, PageDisplayed

Theming and Appearance Copy Section

Theme Change Flow Sequence Diagram

• Location: cross-cutting/theming-and-appearance.md
• Type: Mermaid sequence diagram
• Purpose: Illustrates the complete flow of a theme change from OS event to UI update
• Key Components: User, App, SystemThemeWatcher, WndProc, ApplicationThemeManager, ResourceDictionaryManager, UI

Theme System Architecture

• Location: cross-cutting/theming-and-appearance.md
• Type: Component description with code examples
• Purpose: Documents the five core manager classes and their responsibilities
• Key Components: ApplicationThemeManager, ApplicationAccentColorManager, SystemThemeWatcher, WindowBackgroundManager, ResourceDictionaryManager

Win32 Interop Copy Section

Win32 Interop Component Diagram

• Location: cross-cutting/win32-interop.md
• Type: Mermaid graph TB with subgraphs
• Purpose: Three-layer component diagram showing all Win32 interop participants from controls through managed wrappers to CsWin32-generated P/Invoke
• Layers: High-Level Utilities & Controls, Managed Wrappers (Interop/), CsWin32 Source Generation

Three-Layer Architecture Diagram

• Location: cross-cutting/win32-interop.md
• Type: Mermaid graph diagram
• Purpose: Shows the layered architecture for Win32 API access
• Layers:
  • Layer 1: CsWin32 Generated Code (Windows.Win32 namespace)
  • Layer 2: Managed Wrappers (UnsafeNativeMethods, Custom PInvoke)
  • Layer 3: High-Level Utilities (Win32/Utilities, Appearance Managers)

WndProc Message Flow

• Location: cross-cutting/win32-interop.md
• Type: Code example with explanation
• Purpose: Documents window message interception pattern used by SystemThemeWatcher and TitleBar
• Key Messages: WM_DWMCOLORIZATIONCOLORCHANGED, WM_THEMECHANGED, WM_SYSCOLORCHANGE, WM_NCHITTEST

Architectural Decisions Copy Chapter

ADR-002: Control Library Architecture Copy Section

Control Folder Structure

• Location: decisions/ADR-002-control-library-architecture.md
• Type: Directory tree visualization
• Purpose: Shows the folder-per-control organization pattern
• Examples: Button/, NavigationView/, ContentDialog/

Partial Class Decomposition

• Location: decisions/ADR-002-control-library-architecture.md
• Type: Directory structure with annotations
• Purpose: Demonstrates how complex controls split into partial classes by concern
• Example: NavigationView with 6 partial files (Base, Properties, Events, Navigation, TemplateParts, AttachedProperties)

ADR-003: Win32 Interop via CsWin32 Copy Section

Handle Validation Pattern Flowchart

• Location: decisions/ADR-003-win32-interop-via-cswin32.md
• Type: Code example with step-by-step comments
• Purpose: Documents the mandatory three-step validation pattern for all Win32 calls
• Steps:
  1. Check for zero handle
  2. Verify window exists (IsWindow)
  3. Perform operation with exception handling

ADR-005: Feature Folder Organization Copy Section

Feature Folder Patterns

• Location: decisions/ADR-005-feature-folder-controls.md
• Type: Multiple directory tree visualizations
• Purpose: Shows three organization patterns: Simple controls, Complex controls with partials, Controls with related types
• Examples:
  • Simple: Badge/ (2 files)
  • Complex: NavigationView/ (7+ files)
  • With Related Types: NavigationView/ with NavigationViewItem, NavigationViewItemHeader, etc.

Module Interfaces Copy Section

Module Dependency Graph (Public/Internal)

• Location: MODULE-INTERFACES.md
• Type: Mermaid graph TD with subgraphs
• Purpose: Shows module dependencies with public/internal type counts per module
• Key Components: All distributable and non-distributable modules with API surface annotations

Data Flow Diagrams Copy Chapter

Theme Change Flow Copy Section

Diagram: Sequence diagram showing theme change propagation

User → OS Settings → WndProc → SystemThemeWatcher → ApplicationThemeManager →
ResourceDictionaryManager → Application.Resources → UI Update

Win32 Call Stack Copy Section

Diagram: Layer diagram showing Win32 interop call flow

High-Level Code → UnsafeNativeMethods (validation) → PInvoke (CsWin32) → Win32 API

Navigation Flow Copy Section

Diagram: (Not yet created) Could be added to show:

NavigationService → NavigationView → PageProvider → Page Resolution →
Frame Navigation → INavigationAware Callbacks

Component Diagrams Copy Chapter

Theming System Components Copy Section

Components:

• ApplicationThemeManager (theme selection)
• ApplicationAccentColorManager (accent colors)
• SystemThemeWatcher (OS sync)
• WindowBackgroundManager (window appearance)
• ResourceDictionaryManager (resource swapping)

Relationships:

• SystemThemeWatcher → ApplicationThemeManager (triggers Apply)
• ApplicationThemeManager → ResourceDictionaryManager (delegates swapping)
• ApplicationAccentColorManager → ResourceDictionaryManager (updates dynamic resources)

Control Architecture Components Copy Section

Components:

• Control Class (.cs file)
• Implicit Style (.xaml file)
• Dependency Properties
• Routed Events
• Capability Interfaces (IAppearanceControl, IIconControl, IThemeControl)

Relationships:

• Control Class → Dependency Properties (registers)
• Control Class → Capability Interfaces (implements)
• XAML Style → Control Class (targets via TargetType)

Future Diagram Additions Copy Chapter

Recommended Additions Copy Section

1. Content Dialog Lifecycle - Async ShowAsync() flow with cancellation and result handling
2. Icon System Hierarchy - IconElement inheritance tree (FontIcon, SymbolIcon, ImageIcon)
3. Accent Color Derivation - How 20+ accent resources are computed from system accent
4. Gallery App Architecture - MVVM structure with ViewModels, Views, Services, and Models

Recently Added (2026-02-10) Copy Section

• Navigation System Flow — Added in cross-cutting/navigation.md
• DI Integration Flow — Added in views/logical-architecture.md
• Service Layer Architecture — Covered by DI Integration and Module Interfaces diagrams

Diagram Guidelines Copy Chapter

Mermaid Syntax Copy Section

All diagrams use Mermaid for easy maintenance and version control:

Sequence Diagram:

sequenceDiagram
    participant A
    participant B
    A->>B: Message
    B-->>A: Response

Graph Diagram:

graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]

    style A fill:#e1f5e1
    style B fill:#fff4e1

Class Diagram:

classDiagram
    class Button {
        +Icon IconElement
        +Appearance ControlAppearance
    }
    Button --|> IAppearanceControl
    Button --|> IIconControl

Diagram Best Practices Copy Section

1. Keep diagrams focused (single concern per diagram)
2. Use consistent styling across related diagrams
3. Include legend when colors/shapes have meaning
4. Maintain diagram source in markdown (not separate image files)
5. Update diagrams when architecture changes

Diagram Tools Copy Chapter

Recommended Tools Copy Section

• Mermaid Live Editor - https://mermaid.live/
• VS Code Extensions:
  • Markdown Preview Mermaid Support
  • Mermaid Editor

Generating PNG/SVG Copy Section

For presentations or external documentation:

# Using mmdc (Mermaid CLI)
npm install @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.png

Maintenance Copy Chapter

Ownership Copy Section

Architecture diagram maintenance is part of architecture documentation updates. When making architectural changes:

1. Identify affected diagrams
2. Update diagram source in markdown
3. Verify rendering in preview
4. Update this index if adding new diagrams

Review Checklist Copy Section

• Diagram accurately reflects current architecture
• All components labeled clearly
• Relationships shown with appropriate arrows
• Color coding explained (if used)
• Renders correctly in GitHub markdown preview
• Index updated with new diagram location

Index (`docs/index.md`) Copy Section

<h1 class="display-1">WPF UI</h1>
          A simple way to make your application written in WPF keep up with modern design trends. Library changes
              the base elements like Page, ToggleButton or List, and also includes additional controls like
              Navigation, NumberBox, Dialog or Snackbar.<a class="btn btn-outline-primary mr-05"
              href="/documentation/getting-started.html">Start tutorial</a><a class="btn btn-outline-light"
              href="/documentation">Read the docs</a>
      
  






  
    
      
        
          <h4>Check out the Gallery</h4>
          Check out all the controls and functionality with the help of the free **WPF UI Gallery ** app.
        
        
          <a href="https://apps.microsoft.com/store/detail/wpf-ui/9N9LKV8R9VGM?cid=windows-lp-hero" target="_blank" rel="noopener" class="btn btn-ms-store">
            
          </a>
        
      
    
  







  
    <h2 class="display-4">Fluent UI in your favorite environment</h2>
  



  
    
      
      **Open source**
      WPF UI is free and open source. You can check the source code or
        change it to your liking.
    
  


  
    
      
      **Easy to install**
      WPF UI is delivered via NuGet package manager. Just find it in
        the search and add to your project.
    
  


  
    
      
      **Compatible**
      Most styles and controls work right away in Visual Studio
        Designer.
    
  






    
        850KDownloads
    


    
        9KGitHub Stars
    


    
        900Forks

Support Copy Chapter

To ensure you receive the expert guidance you need, we offer a variety of support plans designed to meet the diverse needs of our community. Whether you are looking to modernize your WPF applications or need assistance with our other libraries, our tailored support solutions are here to help. From priority email support to 24/7 dedicated assistance, we provide flexible plans to suit your project requirements.

<a class="btn btn-block btn-outline-primary mr-05" href="https://lepo.co/support">Take a look at the lepo.co support plans</a>


    <a class="btn btn-block btn-outline-light" href="https://github.com/sponsors/pomianowski">Sponsor WPF UI on GitHub</a>

Created with ❤ in Poland by lepo.co
A simple way to make your application written in WPF keep up with modern design trends. Library changes the base elements like Page, ToggleButton or List, and also includes additional controls like Navigation, NumberBox, Dialog or Snackbar.

Getting Started

Documentation Getting Started (`docs/documentation/getting-started.md`) Copy Section

Getting started

Adding dictionaries Copy Chapter

XAML, and hence WPF, operate on resource dictionaries. These are HTML-like files that describe the appearance and various aspects of the controls. WPF UI adds its own sets of these files to tell the application how the controls should look.

There should be a file called App.xaml in your new application. Add new dictionaries to it using WPF UI ControlsDictionary and ThemesDictionary classes:

<Application
  ...
  xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
  <Application.Resources>
    <ResourceDictionary>
      <ResourceDictionary.MergedDictionaries>
        <ui:ThemesDictionary Theme="Dark" />
        <ui:ControlsDictionary />
      </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
  </Application.Resources>
</Application>

Notice that the ThemeDictionary lets you choose a color theme, Light or Dark.

The main window Copy Chapter

There should be a MainWindow.xaml file in your newly created application. It contains the arrangement of the controls used and their parameters.

<Window x:Class="WpfApp1.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:WpfApp1"
        mc:Ignorable="d"
        Title="MainWindow" Height="450" Width="800">
    <Grid>

    </Grid>
</Window>

Add the WPF UI library namespace to this window to tell the XAML compiler that you will be using controls from the library.

<Window
  ...
  xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml" />

Adding controls Copy Chapter

To add a new control from the WPF UI library, just enter its class name, prefixing it with the ui: prefix:

<Window x:Class="WpfApp1.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
        xmlns:local="clr-namespace:WpfApp1"
        mc:Ignorable="d"
        Title="MainWindow" Height="450" Width="800">
    <Grid>
      <ui:SymbolIcon Symbol="Fluent24"/>
    </Grid>
</Window>

Well...

That's it when it comes to the basics, information about individual controls can be found in documentation. Rules for building a WPF application can be found in the official Microsoft documentation. You can check out how to build MVVM applications here.

If you think this documentation needs improvement, please help improve it here.

Documentation Index (`docs/documentation/index.md`) Copy Section

WPF UI Docs

WPF UI is a library built for Windows Presentation Foundation (WPF) and the C# language.
To be able to work with them comfortably, you will need:

• Visual Studio 2022 Community Edition
• .NET desktop development
  (Additional workload in Visual Studio)

[!NOTE]
Visual Studio 2022 and Visual Studio Code are two different programs. If you want to create WPF apps, it's possible to compile them in Visual Studio Code, however for comfortable work we recommend Visual Studio 2022 or JetBrains Rider.

Installation Copy Chapter

You can install WPF UI, the library for the Windows Presentation Foundation framework, in several ways.

• Directly specify the Wpf.Ui.dll file in your application's project file (.csproj).
• Copy the library source code into your application codebase.
• Use the NuGet package manager.

We recommend using the NuGet package manager, it allows you to easily install and update your application dependencies.
More information on how to install WPF UI using NuGet can be found here.

Extension for Visual Studio Copy Chapter

Creators of WPF UI have prepared a special plugin that will automatically create a project based on WPF UI, Dependency Injection and MVVM, thanks to which you will quickly and easily start a new apps.

Learn more about the WPF UI plug-in for Visual Studio 2022

Getting started Copy Chapter

Once you have chosen how to install WPF UI, you can move on to creating your first app, more on this in Getting Started.

Migration Index (`docs/migration/index.md`) Copy Section

Migration Guides

Guides for migrating between major versions of Wpf.Ui.

• v2 Migration
• v3 Migration
• v4 Migration

Docfx.Json (`docs/docfx.json`) Copy Section

{
"metadata": [
{
"src": [
{
"files": [
"Wpf.Ui/.csproj",
"Wpf.Ui.Tray/.csproj",
"Wpf.Ui.Abstractions/.csproj",
"Wpf.Ui.DependencyInjection/.csproj"
],
"src": "../src"
}
],
"dest": "api",
"includePrivateMembers": false,
"disableGitFeatures": false,
"disableDefaultFilter": false,
"noRestore": false,
"namespaceLayout": "flattened",
"memberLayout": "samePage",
"allowCompilationErrors": false
}
],
"build": {
"content": [
{
"files": [
"/*.{md,yml}"
],
"exclude": [
"_site/",
"obj/",
"architecture/"
]
}
],
"resource": [
{
"files": [
"/images/",
"codesnippet/",
"manifest.webmanifest",
"robots.txt"
],
"exclude": [
"_site/",
"obj/**"
]
}
],
"xref": [],
"xrefService": [
"https://xref.docs.microsoft.com/query?uid={uid}"
],
"postProcessors": [
"ExtractSearchIndex"
],
"globalMetadata": {
"_appTitle": "WPF UI",
"_appName": "WPF UI",
"_appFaviconPath": "images/favicon.ico",
"_appLogoPath": "images/wpfui.png",
"_appFooter": "Made with <a href="https://dotnet.github.io/docfx\" rel="noreferrer">docfx, <a href="https://chat.openai.com/\" rel="noreferrer">ChatGPT | Copyright © 2026 <a href="https://lepo.co/\">lepo.co"
},
"dest": "_site",
"template": [
"default",
"templates/wpfui"
],
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"markdownEngineName": "markdig",
"noLangKeyword": false,
"keepFileLink": false,
"cleanupCacheHistory": false,
"disableGitFeatures": false
},
"sitemap": {
"baseUrl": "https://wpfui.lepo.co",
"priority": 0.1,
"changefreq": "monthly"
}
}

Toc.Yml (`docs/toc.yml`) Copy Section

items:

• name: Home
  href: /
• name: Documentation
  href: /documentation/
  items:
  • name: Getting started
    href: documentation/getting-started.md
  • name: NuGet Package
    href: documentation/nuget.md
  • name: Visual Studio Extension
    href: documentation/extension.md
  • name: Themes
    href: documentation/themes.md
  • name: Icons
    href: documentation/icons.md
  • name: Theme Watcher
    href: documentation/system-theme-watcher.md
  • name: Theme Accent
    href: documentation/accent.md
  • name: Navigation
    href: documentation/navigation-view.md
  • name: Menu
    href: documentation/menu.md
  • name: Gallery
    href: documentation/gallery.md
  • name: Releases
    href: documentation/releases.md
• name: API v4.0
  href: api/
• name: Migration
  href: /migration/
  items:
  • name: Key changes in v4
    href: migration/v4-migration.md
  • name: Key changes in v3
    href: migration/v3-migration.md
  • name: Key changes in v2
    href: migration/v2-migration.md
• name: Support plans
  href: https://lepo.co/support

Architecture CONSTITUTION (`docs/architecture/CONSTITUTION.md`) Copy Section

WPF UI Project Constitution v4.2.0

Spec-Driven Development (SDD) Document
Single source of truth for coding conventions, boundary rules, and project-specific guidelines.
Intended audience: AI coding agents and human contributors.

Table of Contents Copy Chapter

1. Project Identity
2. Coding Conventions
   • Namespaces
   • Nullable Reference Types
   • Private Fields
   • File Headers
   • XML Documentation
   • Dependency Properties
   • Control Authoring
   • XAML Styles
   • Service Pattern
   • Error Handling
   • Win32 Interop
   • Test Naming
   • MVVM (Gallery / Samples)
   • Central Package Management
   • Commit Convention
3. Boundary System
   • ALWAYS DO
   • ASK FIRST
   • NEVER DO
4. Rules Files Summary

1. Project Identity Copy Chapter

Project Structure Copy Section

Core Library Layout (`src/Wpf.Ui/`) Copy Section

2. Coding Conventions Copy Chapter

2.1 Namespaces Copy Section

All C# files use file-scoped namespaces. All controls use the flat Wpf.Ui.Controls namespace regardless of subfolder depth, with a ReSharper suppression comment.

// ReSharper disable once CheckNamespace
namespace Wpf.Ui.Controls;

public class Button : System.Windows.Controls.Button, IAppearanceControl, IIconControl
{
    // ...
}

Services use the Wpf.Ui namespace:

namespace Wpf.Ui;

public class SnackbarService : ISnackbarService
{
    // ...
}

Gallery app follows folder-based namespaces:

namespace Wpf.Ui.Gallery.ViewModels.Pages.BasicInput;

public partial class AnchorViewModel : ViewModel
{
    // ...
}

2.2 Nullable Reference Types Copy Section

Nullable is enabled globally via Directory.Build.props. Use is not null pattern matching over != null.

// Good
if (_presenter is null)
{
    throw new InvalidOperationException($"The SnackbarPresenter was never set");
}

_snackbar ??= new Snackbar(_presenter);

// Good - nullable property types
public IconElement? Icon
{
    get => (IconElement?)GetValue(IconProperty);
    set => SetValue(IconProperty, value);
}

2.3 Private Fields Copy Section

Private fields use _camelCase (underscore prefix). This is enforced by .editorconfig naming rules.

private bool _valueUpdating;
private SnackbarPresenter? _presenter;
private Snackbar? _snackbar;

In Gallery ViewModels with CommunityToolkit.Mvvm, the same convention applies:

[ObservableProperty]
private bool _isAnchorEnabled = true;

2.4 File Headers Copy Section

C# files -- MIT license header enforced as a build error via IDE0073:

// This Source Code Form is subject to the terms of the MIT License.
// If a copy of the MIT was not distributed with this file, You can obtain one at https://opensource.org/licenses/MIT.
// Copyright (C) Leszek Pomianowski and WPF UI Contributors.
// All Rights Reserved.

XAML files -- XML comment block with MIT license and Microsoft credit where applicable:

2.5 XML Documentation Copy Section

Public APIs require `` and <example> tags. Examples show XAML usage with <code lang="xml"> and HTML-escaped angle brackets.

Control class documentation:

/// <summary>
/// Creates a hyperlink to web pages, files, email addresses, locations in the same page,
/// or anything else a URL can address.
/// </summary>
/// <example>
/// <code lang="xml">
/// &lt;ui:Anchor
///     NavigateUri="https://lepo.co/" /&gt;
/// </code>
/// </example>
public class Anchor : Wpf.Ui.Controls.HyperlinkButton { }

Control with multiple XAML examples:

/// <summary>
/// Inherited from the <see cref="System.Windows.Controls.Button"/>,
/// adding <see cref="SymbolRegular"/>.
/// </summary>
/// <example>
/// <code lang="xml">
/// &lt;ui:Button
///     Appearance="Primary"
///     Content="WPF UI button with font icon"
///     Icon="{ui:SymbolIcon Symbol=Fluent24}" /&gt;
/// </code>
/// <code lang="xml">
/// &lt;ui:Button
///     Appearance="Primary"
///     Content="WPF UI button with font icon"
///     Icon="{ui:FontIcon '&#x1F308;'}" /&gt;
/// </code>
/// </example>

C# code examples (e.g., for static managers):

/// <example>
/// <code lang="csharp">
/// ApplicationThemeManager.Apply(
///     ApplicationTheme.Light
/// );
/// </code>
/// </example>

DependencyProperty documentation uses a single-line ``:

/// <summary>Identifies the <see cref="Icon"/> dependency property.</summary>
public static readonly DependencyProperty IconProperty = DependencyProperty.Register(
    nameof(Icon),
    typeof(IconElement),
    typeof(Button),
    new PropertyMetadata(null, null, IconElement.Coerce)
);

Internal code: Avoid comments unless explaining Win32 interop/marshalling. Never add comments that restate what the code does.

2.6 Dependency Properties Copy Section

Use DependencyProperty.Register with nameof(). Always include XML doc with the Identifies the ... dependency property pattern.

/// <summary>Identifies the <see cref="Icon"/> dependency property.</summary>
public static readonly DependencyProperty IconProperty = DependencyProperty.Register(
    nameof(Icon),
    typeof(IconElement),
    typeof(Button),
    new PropertyMetadata(null, null, IconElement.Coerce)
);

/// <summary>
/// Gets or sets displayed <see cref="IconElement"/>.
/// </summary>
[Bindable(true)]
[Category("Appearance")]
public IconElement? Icon
{
    get => (IconElement?)GetValue(IconProperty);
    set => SetValue(IconProperty, value);
}

For two-way binding with specific update triggers:

/// <summary>Identifies the <see cref="Value"/> dependency property.</summary>
public static readonly DependencyProperty ValueProperty = DependencyProperty.Register(
    nameof(Value),
    typeof(double?),
    typeof(NumberBox),
    new FrameworkPropertyMetadata(
        null,
        FrameworkPropertyMetadataOptions.BindsTwoWayByDefault,
        OnValueChanged,
        null,
        false,
        UpdateSourceTrigger.LostFocus
    )
);

2.7 Control Authoring Copy Section

Each control resides in its own subfolder under Controls/{Name}/ containing at minimum:

• {Name}.cs -- C# control class
• {Name}.xaml -- XAML ResourceDictionary with styles and templates

Complex controls are split into partial classes:

• NavigationView.Base.cs -- Static constructor, instance constructor
• NavigationView.Properties.cs -- DependencyProperty declarations
• NavigationView.Events.cs -- RoutedEvent declarations
• NavigationView.TemplateParts.cs -- Template part handling
• NavigationView.Navigation.cs -- Navigation logic

Static constructor pattern (required for custom-styled controls):

static NavigationView()
{
    DefaultStyleKeyProperty.OverrideMetadata(
        typeof(NavigationView),
        new FrameworkPropertyMetadata(typeof(NavigationView))
    );
}

Template parts pattern:

[TemplatePart(Name = PART_ClearButton, Type = typeof(Button))]
[TemplatePart(Name = PART_InlineIncrementButton, Type = typeof(RepeatButton))]
[TemplatePart(Name = PART_InlineDecrementButton, Type = typeof(RepeatButton))]
public partial class NumberBox : Wpf.Ui.Controls.TextBox
{
    private const string PART_ClearButton = nameof(PART_ClearButton);
    private const string PART_InlineIncrementButton = nameof(PART_InlineIncrementButton);
    private const string PART_InlineDecrementButton = nameof(PART_InlineDecrementButton);
}

Base class selection:

2.8 XAML Styles Copy Section

Control styles require OverridesDefaultStyle=True and SnapsToDevicePixels=True. Use DynamicResource for theme-dependent values and StaticResource for constants.

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:controls="clr-namespace:Wpf.Ui.Controls">

    
    <Thickness x:Key="ButtonPadding">11,5,11,6</Thickness>
    <Thickness x:Key="ButtonBorderThemeThickness">1</Thickness>

    <Style x:Key="DefaultRepeatButtonStyle" TargetType="{x:Type RepeatButton}">
        <Setter Property="FocusVisualStyle" Value="{DynamicResource DefaultControlFocusVisualStyle}" />
        <Setter Property="Background" Value="{DynamicResource ButtonBackground}" />
        <Setter Property="Foreground" Value="{DynamicResource ButtonForeground}" />
        <Setter Property="BorderBrush" Value="{DynamicResource ControlElevationBorderBrush}" />
        <Setter Property="BorderThickness" Value="{StaticResource ButtonBorderThemeThickness}" />
        <Setter Property="Padding" Value="{StaticResource ButtonPadding}" />
        <Setter Property="SnapsToDevicePixels" Value="True" />
        <Setter Property="OverridesDefaultStyle" Value="True" />
    </Style>
</ResourceDictionary>

Resource key naming conventions:

2.9 Service Pattern Copy Section

Services follow the I{Name}Service / {Name}Service naming convention. Both interface and implementation live at the src/Wpf.Ui/ root level (NOT in a Services/ subfolder).

Interface (src/Wpf.Ui/ISnackbarService.cs):

namespace Wpf.Ui;

/// <summary>
/// Represents a contract with the service that provides global <see cref="Snackbar"/>.
/// </summary>
public interface ISnackbarService
{
    TimeSpan DefaultTimeOut { get; set; }
    void SetSnackbarPresenter(SnackbarPresenter contentPresenter);
    SnackbarPresenter? GetSnackbarPresenter();
    void Show(string title, string message, ControlAppearance appearance, IconElement? icon, TimeSpan timeout);
}

Implementation (src/Wpf.Ui/SnackbarService.cs):

namespace Wpf.Ui;

/// <summary>
/// A service that provides methods related to displaying the <see cref="Snackbar"/>.
/// </summary>
public class SnackbarService : ISnackbarService
{
    private SnackbarPresenter? _presenter;
    private Snackbar? _snackbar;

    /// <inheritdoc />
    public TimeSpan DefaultTimeOut { get; set; } = TimeSpan.FromSeconds(5);

    /// <inheritdoc />
    public void Show(
        string title,
        string message,
        ControlAppearance appearance,
        IconElement? icon,
        TimeSpan timeout
    )
    {
        if (_presenter is null)
        {
            throw new InvalidOperationException($"The SnackbarPresenter was never set");
        }

        _snackbar ??= new Snackbar(_presenter);
        // ...
    }
}

Available services:

2.10 Error Handling Copy Section

Win32/Interop code -- Bare catch blocks swallowing exceptions (intentional for cross-OS compatibility):

catch
{
    // Ignore registry access errors on non-Windows or restricted environments
    return null;
}

Service code -- Throw ArgumentNullException / InvalidOperationException for precondition violations:

if (_presenter is null)
{
    throw new InvalidOperationException($"The SnackbarPresenter was never set");
}

protected void ThrowIfNavigationControlIsNull()
{
    if (NavigationControl is null)
    {
        throw new ArgumentNullException(nameof(NavigationControl));
    }
}

2.11 Win32 Interop Copy Section

The project uses a three-layer architecture for native Windows API access.

Layer 1: CsWin32 auto-generated P/Invoke via Microsoft.Windows.CsWin32 NuGet package. Native function names are listed in src/Wpf.Ui/NativeMethods.txt.

Layer 2: Managed wrappers with validation (src/Wpf.Ui/Interop/UnsafeNativeMethods.cs):

internal static class UnsafeNativeMethods
{
    public static unsafe bool ApplyWindowCornerPreference(
        IntPtr handle,
        WindowCornerPreference cornerPreference
    )
    {
        // ALWAYS validate handle before calling Win32 APIs
        if (handle == IntPtr.Zero)
        {
            return false;
        }

        if (!PInvoke.IsWindow(new HWND(handle)))
        {
            return false;
        }

        DWM_WINDOW_CORNER_PREFERENCE pvAttribute = UnsafeReflection.Cast(cornerPreference);

        return PInvoke.DwmSetWindowAttribute(
                new HWND(handle),
                DWMWINDOWATTRIBUTE.DWMWA_WINDOW_CORNER_PREFERENCE,
                &pvAttribute,
                sizeof(int)
            ) == HRESULT.S_OK;
    }
}

Layer 3: Utility helpers (src/Wpf.Ui/Win32/):

internal sealed class Utilities
{
    public static bool IsOSWindows11OrNewer => _osVersion.Build >= 22000;
}

Critical rule: Always validate handles (IntPtr.Zero check + PInvoke.IsWindow) before any native API call. Always search the existing codebase before assuming standard WPF approaches work for TitleBar, window management, system theme detection, or DWM integration.

2.12 Test Naming Copy Section

Unit tests use MethodName_ExpectedResult_WhenCondition:

public class TransitionAnimationProviderTests
{
    [Fact]
    public void ApplyTransition_ReturnsFalse_WhenDurationIsLessThan10()
    {
        UIElement mockedUiElement = Substitute.For<UIElement>();

        var result = TransitionAnimationProvider.ApplyTransition(mockedUiElement, Transition.FadeIn, -10);

        Assert.False(result);
    }

    [Fact]
    public void ApplyTransition_ReturnsFalse_WhenElementIsNull()
    {
        var result = TransitionAnimationProvider.ApplyTransition(null, Transition.FadeIn, 1000);

        Assert.False(result);
    }
}

Integration tests use the UiTest base class with FlaUI and AwesomeAssertions:

public sealed class TitleBarTests : UiTest
{
    [Fact]
    public async Task CloseButton_ShouldCloseWindow_WhenClicked()
    {
        Button? closeButton = FindFirst("TitleBarCloseButton").AsButton();

        closeButton.Should().NotBeNull("because CloseButton should be present in the main window title bar");
        closeButton.Click(moveMouse: false);

        await Wait(2);

        Application
            ?.HasExited.Should()
            .BeTrue("because the main window should be closed after clicking the close button");
    }
}

2.13 MVVM (Gallery / Samples) Copy Section

The Gallery app uses CommunityToolkit.Mvvm. ViewModels are partial classes inheriting from ViewModel (which extends ObservableObject).

ViewModel (src/Wpf.Ui.Gallery/ViewModels/Pages/BasicInput/AnchorViewModel.cs):

namespace Wpf.Ui.Gallery.ViewModels.Pages.BasicInput;

public partial class AnchorViewModel : ViewModel
{
    [ObservableProperty]
    private bool _isAnchorEnabled = true;

    [RelayCommand]
    private void OnAnchorCheckboxChecked(object sender)
    {
        if (sender is not CheckBox checkbox)
        {
            return;
        }

        IsAnchorEnabled = !(checkbox?.IsChecked ?? false);
    }
}

Page (src/Wpf.Ui.Gallery/Views/Pages/BasicInput/AnchorPage.xaml.cs):

namespace Wpf.Ui.Gallery.Views.Pages.BasicInput;

[GalleryPage("Button which opens a link.", SymbolRegular.CubeLink20)]
public partial class AnchorPage : INavigableView<AnchorViewModel>
{
    public AnchorViewModel ViewModel { get; init; }

    public AnchorPage(AnchorViewModel viewModel)
    {
        ViewModel = viewModel;
        DataContext = this;

        InitializeComponent();
    }
}

Key MVVM conventions:

• [ObservableProperty] for _camelCase backing fields (generates PascalCase properties)
• [RelayCommand] for On-prefixed private methods (generates {Name}Command ICommand)
• Pattern matching with is not for type checks in command handlers
• DataContext = this set in page constructor (not in XAML)
• INavigableView<TViewModel> interface for navigation-aware pages

2.14 Central Package Management Copy Section

All NuGet package versions are centralized in Directory.Packages.props. Individual .csproj files reference packages without version attributes.

Directory.Packages.props (versions defined here):

<Project>
  <ItemGroup>
    <PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.0" />
    <PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.242" />
    <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
    <PackageVersion Include="WpfAnalyzers" Version="4.1.1" />
    <PackageVersion Include="xunit.v3" Version="3.2.0" />
    
  </ItemGroup>
</Project>

.csproj (NO version attribute):

<PackageReference Include="Microsoft.Windows.CsWin32">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

2.15 Commit Convention Copy Section

Format: type(scope): description (#PR_NUMBER)

Examples from actual commits:

fix(controls): Fix TextBlock issues (#1640)
fix(controls): Remove AnimationFactorToValueConverter from CheckBox.xaml (#1649)
fix(controls): NavigationViewItemAutomationPeer followup (#1646)
fix(controls): Update ContentDialog For TitleBar CenterContent (#1642)
feat(app): Add ability to disable automatic apply of system accent color in UiApplication (#1643)

3. Boundary System Copy Chapter

3.1 ALWAYS DO Copy Section

These practices are mandatory. Violations will be caught by analyzers, build errors, or code review.

3.2 ASK FIRST Copy Section

These actions require discussion with the maintainer before proceeding.

3.3 NEVER DO Copy Section

These practices are forbidden. Violations will be rejected in code review.

Concrete examples of NEVER DO violations and their corrections:

// N1 VIOLATION: version in .csproj
<PackageReference Include="NSubstitute" Version="5.3.0" />
// CORRECT: no version attribute
<PackageReference Include="NSubstitute" />

// N2 VIOLATION: var for non-apparent type
var service = container.Resolve<ISnackbarService>();
// CORRECT: explicit type
ISnackbarService service = container.Resolve<ISnackbarService>();

// N3 VIOLATION: primary constructor
public class MyService(ILogger logger) : IMyService { }
// CORRECT: traditional constructor
public class MyService : IMyService
{
    private readonly ILogger _logger;

    public MyService(ILogger logger)
    {
        _logger = logger;
    }
}

// N7 VIOLATION: no handle validation
PInvoke.DwmSetWindowAttribute(new HWND(handle), attr, &value, sizeof(int));
// CORRECT: validate first
if (handle == IntPtr.Zero) return false;
if (!PInvoke.IsWindow(new HWND(handle))) return false;
PInvoke.DwmSetWindowAttribute(new HWND(handle), attr, &value, sizeof(int));

// N8 VIOLATION: expression-bodied property
public string Name => _name;
// CORRECT: block body
public string Name
{
    get => _name;
}

// N9 VIOLATION: folder-matching namespace
namespace Wpf.Ui.Controls.Button;
// CORRECT: flat Controls namespace
// ReSharper disable once CheckNamespace
namespace Wpf.Ui.Controls;

// N10 VIOLATION: this. qualification
this._name = name;
// CORRECT: no this.
_name = name;

4. Rules Files Summary Copy Chapter

The project enforces conventions through multiple configuration files working in concert.

Configuration Files Overview Copy Section

`.editorconfig` -- Key Rules Copy Section

Encoding and Indentation:

Enforced Diagnostics (error/warning level):

Suppressed Diagnostics:

Naming Rules:

`.csharpierrc` -- Formatter Configuration Copy Section

{
    "printWidth": 110,
    "useTabs": false,
    "tabWidth": 4,
    "preprocessorSymbolSets": [
        "",
        "DEBUG",
        "DEBUG,CODE_STYLE"
    ]
}

Run formatter: dotnet csharpier .

`Directory.Build.props` -- Central Build Configuration Copy Section

`Directory.Build.targets` -- Build Targets Copy Section

Key responsibilities:

• Analyzer packages: AsyncFixer, IDisposableAnalyzers, StyleCop.Analyzers added to all projects (except .dcproj, .sfproj, VS template/extension projects)
• PolySharp: Added for netstandard2.0/2.1 and net462/472/481 targets (backports modern C# features)
• SourceLink: GitHub SourceLink for NuGet packages
• Assembly signing: Conditional on SourceLinkEnabled=true AND GeneratePackageOnBuild=true, using src/lepo.snk
• Trimming/AOT: Enabled for .NET 6+ targets (IsTrimmable, EnableTrimAnalyzer, EnableAotAnalyzer, EnableSingleFileAnalyzer)
• Commit hash: Embedded as AssemblyMetadataAttribute("CommitHash", ...) via SourceRevisionId

`Directory.Packages.props` -- Centralized Package Versions Copy Section

All NuGet package versions for the entire solution are defined here. Key packages:

`.github/copilot-instructions.md` -- AI Agent Instructions Copy Section

Provides GitHub Copilot with:

• Project structure and build commands
• Code conventions (never assume library availability, modern C#)
• XML documentation requirements with concrete examples
• Windows platform guidance (search before assuming WPF approaches work)
• Tone/style: no emoticons, minimize output, no preamble/postamble
• MVVM patterns for Gallery pages
• Testing patterns (unit + integration)

`CLAUDE.md` -- Claude Code Guidance Copy Section

Provides Claude Code with:

• Build commands for all solution configurations
• Architecture overview (project structure, core library layout)
• Key patterns (Win32 interop, XAML resources, MVVM, CPM)
• Testing frameworks and conventions
• Code conventions summary
• Commit convention format

`.github/pull_request_template.md` -- PR Template Copy Section

PR type checkboxes:

• Update
• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Build related changes
• Documentation content changes

Required sections:

• What is the current behavior? (with Issue Number field)
• What is the new behavior?
• Other information (screenshots)

Version Information Copy Chapter

Architecture IMPLEMENTATION GUIDE (`docs/architecture/IMPLEMENTATION-GUIDE.md`) Copy Section

WPF UI Implementation Guide

Step-by-step guides for common implementation tasks in the WPF UI project.

Table of Contents Copy Chapter

1. How to Add a New Control
2. How to Add a New Service
3. How to Add a Gallery Page
4. How to Use Win32 Interop
5. How to Add Theme Support
6. Testing a Feature

1. How to Add a New Control Copy Chapter

This guide walks through creating a new control following the WPF UI conventions.

Step 1: Create Control Folder Structure Copy Section

src/Wpf.Ui/Controls/
└── MyControl/
    ├── MyControl.cs       # Code-behind class
    └── MyControl.xaml     # Style and ControlTemplate

Step 2: Create the Control Class (MyControl.cs) Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Step 3: Create the XAML Style (MyControl.xaml) Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Step 4: Register in Wpf.Ui.xaml Copy Section

Add reference to src/Wpf.Ui/Resources/Wpf.Ui.xaml:

<ResourceDictionary.MergedDictionaries>
    
    <ResourceDictionary Source="pack://application:,,,/Wpf.Ui;component/Controls/MyControl/MyControl.xaml" />
</ResourceDictionary.MergedDictionaries>

Step 5: Add Designer Support (Optional) Copy Section

Add toolbox icon bitmap to src/Wpf.Ui/Assets/Toolbox/MyControl.bmp (16x16 pixels).

Register in src/Wpf.Ui/VisualStudioToolsManifest.xml:

<ToolboxItems UIFramework="WPF" VSCategory="WPF UI" BlendCategory="WPF UI">
    <Item Type="Wpf.Ui.Controls.MyControl" />
</ToolboxItems>

Step 6: Add to Category Documentation Copy Section

Document the control category in architecture notes for future reference.

2. How to Add a New Service Copy Chapter

This guide shows how to create a new service following the WPF UI service pattern.

Step 1: Create the Service Interface (IMyService.cs) Copy Section

// This Source Code Form is subject to the terms of the MIT License.
// If a copy of the MIT was not distributed with this file, You can obtain one at https://opensource.org/licenses/MIT.
// Copyright (C) Leszek Pomianowski and WPF UI Contributors.
// All Rights Reserved.

namespace Wpf.Ui;

/// <summary>
/// Provides functionality for managing custom operations.
/// </summary>
public interface IMyService
{
    /// <summary>
    /// Gets the current state of the service.
    /// </summary>
    bool IsActive { get; }

    /// <summary>
    /// Initializes the service with the specified parameter.
    /// </summary>
    /// <param name="parameter">The initialization parameter.</param>
    void Initialize(string parameter);

    /// <summary>
    /// Performs an asynchronous operation.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    Task<bool> PerformOperationAsync(CancellationToken cancellationToken = default);
}

Step 2: Create the Service Implementation (MyService.cs) Copy Section

// This Source Code Form is subject to the terms of the MIT License.
// If a copy of the MIT was not distributed with this file, You can obtain one at https://opensource.org/licenses/MIT.
// Copyright (C) Leszek Pomianowski and WPF UI Contributors.
// All Rights Reserved.

using System;
using System.Threading;
using System.Threading.Tasks;

namespace Wpf.Ui;

/// <summary>
/// Implementation of <see cref="IMyService"/>.
/// </summary>
public partial class MyService : IMyService
{
    private string? _parameter;
    private bool _isActive;

    /// <inheritdoc />
    public bool IsActive => _isActive;

    /// <inheritdoc />
    public void Initialize(string parameter)
    {
        ArgumentNullException.ThrowIfNull(parameter);

        _parameter = parameter;
        _isActive = true;
    }

    /// <inheritdoc />
    public async Task<bool> PerformOperationAsync(CancellationToken cancellationToken = default)
    {
        ThrowIfNotInitialized();

        try
        {
            // Perform async operation
            await Task.Delay(100, cancellationToken);
            return true;
        }
        catch (OperationCanceledException)
        {
            return false;
        }
    }

    private void ThrowIfNotInitialized()
    {
        if (!_isActive || _parameter is null)
        {
            throw new InvalidOperationException("Service has not been initialized. Call Initialize() first.");
        }
    }
}

Step 3: Add DI Extension Method Copy Section

Create src/Wpf.Ui.DependencyInjection/ServiceCollectionExtensions.MyService.cs:

// This Source Code Form is subject to the terms of the MIT License.
// If a copy of the MIT was not distributed with this file, You can obtain one at https://opensource.org/licenses/MIT.
// Copyright (C) Leszek Pomianowski and WPF UI Contributors.
// All Rights Reserved.

using Microsoft.Extensions.DependencyInjection;
using Wpf.Ui;

namespace Wpf.Ui.DependencyInjection;

/// <summary>
/// Extension methods for registering WPF UI services.
/// </summary>
public static partial class ServiceCollectionExtensions
{
    /// <summary>
    /// Registers <see cref="IMyService"/> as a singleton.
    /// </summary>
    /// <param name="services">The service collection.</param>
    /// <returns>The service collection for chaining.</returns>
    public static IServiceCollection AddMyService(this IServiceCollection services)
    {
        _ = services.AddSingleton<IMyService, MyService>();
        return services;
    }
}

Step 4: Register in Application Copy Section

// In your application startup (e.g., App.xaml.cs or Program.cs)
services.AddMyService();

Step 5: Use the Service Copy Section

public partial class MyViewModel : ViewModel
{
    private readonly IMyService _myService;

    public MyViewModel(IMyService myService)
    {
        _myService = myService;
        _myService.Initialize("parameter-value");
    }

    [RelayCommand]
    private async Task OnPerformAction()
    {
        bool result = await _myService.PerformOperationAsync();
        // Handle result
    }
}

3. How to Add a Gallery Page Copy Chapter

This guide demonstrates adding a new demo page to the WPF UI Gallery application.

Step 1: Create ViewModel Copy Section

Create src/Wpf.Ui.Gallery/ViewModels/Pages/MyCategory/MyControlViewModel.cs:

/* Detailed source-code truncated for AI context efficiency. */

Step 2: Create Page (XAML) Copy Section

Create src/Wpf.Ui.Gallery/Views/Pages/MyCategory/MyControlPage.xaml:

/* Detailed source-code truncated for AI context efficiency. */

Step 3: Create Page Code-Behind Copy Section

Create src/Wpf.Ui.Gallery/Views/Pages/MyCategory/MyControlPage.xaml.cs:

// This Source Code Form is subject to the terms of the MIT License.
// If a copy of the MIT was not distributed with this file, You can obtain one at https://opensource.org/licenses/MIT.
// Copyright (C) Leszek Pomianowski and WPF UI Contributors.
// All Rights Reserved.

using Wpf.Ui.Controls;
using Wpf.Ui.Gallery.Attributes;
using Wpf.Ui.Gallery.ViewModels.Pages.MyCategory;

namespace Wpf.Ui.Gallery.Views.Pages.MyCategory;

[GalleryPage("Custom control demonstration.", SymbolRegular.Heart24)]
public partial class MyControlPage : INavigableView<MyControlViewModel>
{
    public MyControlViewModel ViewModel { get; }

    public MyControlPage(MyControlViewModel viewModel)
    {
        ViewModel = viewModel;
        DataContext = this;
        InitializeComponent();
    }
}

Step 4: Register in DI Container Copy Section

Add to src/Wpf.Ui.Gallery/App.xaml.cs or DI configuration:

// Register ViewModel
services.AddSingleton<MyControlViewModel>();

// Register Page
services.AddSingleton<MyControlPage>();

Step 5: Add Navigation Entry Copy Section

If you need manual navigation registration (not using automatic discovery), add to navigation setup:

navigationService.SetNavigationControl(navigationView);

// Register page type
menuItems.Add(new NavigationViewItem
{
    Content = "MyControl",
    Icon = new SymbolIcon { Symbol = SymbolRegular.Heart24 },
    TargetPageType = typeof(MyControlPage)
});

4. How to Use Win32 Interop Copy Chapter

This guide demonstrates the three-layer Win32 interop architecture used in WPF UI.

Step 1: Add Function to NativeMethods.txt Copy Section

Edit src/Wpf.Ui/NativeMethods.txt:

// Existing entries...
DwmSetWindowAttribute
IsWindow

// Add your new function
GetSystemMetrics

This triggers CsWin32 to auto-generate P/Invoke declarations in the Windows.Win32 namespace.

Step 2: Create Managed Wrapper (if needed) Copy Section

If you need a safe wrapper with handle validation, add to src/Wpf.Ui/Interop/UnsafeNativeMethods.cs:

using Windows.Win32;
using Windows.Win32.Foundation;
using Windows.Win32.UI.WindowsAndMessaging;

namespace Wpf.Ui.Interop;

internal static partial class UnsafeNativeMethods
{
    /// <summary>
    /// Safely retrieves a system metric value with handle validation.
    /// </summary>
    /// <param name="handle">Window handle for context (optional).</param>
    /// <param name="metric">The system metric to retrieve.</param>
    /// <returns>The metric value, or 0 if the operation fails.</returns>
    public static int GetSystemMetricSafe(IntPtr handle, SYSTEM_METRICS_INDEX metric)
    {
        // Validate handle if provided
        if (handle != IntPtr.Zero && !PInvoke.IsWindow(new HWND(handle)))
        {
            return 0;
        }

        try
        {
            return PInvoke.GetSystemMetrics(metric);
        }
        catch
        {
            // Swallow exception for OS compatibility (intentional)
            return 0;
        }
    }
}

Step 3: Create Utility Helper (if needed) Copy Section

If you need higher-level utility functions, add to src/Wpf.Ui/Win32/Utilities.cs:

using Wpf.Ui.Interop;
using Windows.Win32.UI.WindowsAndMessaging;

namespace Wpf.Ui.Win32;

internal sealed class Utilities
{
    /// <summary>
    /// Gets the width of the window border.
    /// </summary>
    public static int BorderWidth => UnsafeNativeMethods.GetSystemMetricSafe(
        IntPtr.Zero,
        SYSTEM_METRICS_INDEX.SM_CXBORDER
    );

    /// <summary>
    /// Gets the height of the window border.
    /// </summary>
    public static int BorderHeight => UnsafeNativeMethods.GetSystemMetricSafe(
        IntPtr.Zero,
        SYSTEM_METRICS_INDEX.SM_CYBORDER
    );
}

Step 4: Use in Your Code Copy Section

using Wpf.Ui.Interop;
using Wpf.Ui.Win32;
using Windows.Win32;
using Windows.Win32.Foundation;

// Option 1: Direct P/Invoke (for simple cases)
int screenWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXSCREEN);

// Option 2: Safe wrapper (validates handle, catches exceptions)
int borderWidth = UnsafeNativeMethods.GetSystemMetricSafe(
    windowHandle,
    SYSTEM_METRICS_INDEX.SM_CXBORDER
);

// Option 3: High-level utility
int borderHeight = Utilities.BorderHeight;

Step 5: Handle WndProc Messages (if needed) Copy Section

To intercept Windows messages:

using System.Windows.Interop;
using Windows.Win32.UI.WindowsAndMessaging;

public class MyWindow : Window
{
    private HwndSource? _hwndSource;

    protected override void OnSourceInitialized(EventArgs e)
    {
        base.OnSourceInitialized(e);

        _hwndSource = (HwndSource)PresentationSource.FromVisual(this);
        _hwndSource?.AddHook(WndProc);
    }

    private IntPtr WndProc(IntPtr hWnd, int msg, IntPtr wParam, IntPtr lParam, ref bool handled)
    {
        switch ((uint)msg)
        {
            case PInvoke.WM_DWMCOLORIZATIONCOLORCHANGED:
                // Handle theme change
                handled = true;
                break;

            case PInvoke.WM_THEMECHANGED:
                // Handle system theme change
                handled = true;
                break;
        }

        return IntPtr.Zero;
    }

    protected override void OnClosed(EventArgs e)
    {
        _hwndSource?.RemoveHook(WndProc);
        base.OnClosed(e);
    }
}

Important Notes Copy Section

1. Always validate handles before calling Win32 APIs:

   csharp Copy

   if (handle == IntPtr.Zero || !PInvoke.IsWindow(new HWND(handle)))
       return false;

2. Catch exceptions in interop code for OS compatibility (some APIs may not exist on older Windows versions)

3. Use unsafe keyword for pointer operations

4. Check OS version before using new APIs:

   csharp Copy

   if (Wpf.Ui.Win32.Utilities.IsOSWindows11OrNewer)
   {
       // Use Windows 11-specific API
   }

5. How to Add Theme Support Copy Chapter

This guide shows how to make your control theme-aware.

Step 1: Use DynamicResource in XAML Copy Section

<Style TargetType="{x:Type controls:MyControl}">
    
    <Setter Property="Background" Value="{DynamicResource ControlFillColorDefaultBrush}" />
    <Setter Property="Foreground" Value="{DynamicResource TextFillColorPrimaryBrush}" />
    <Setter Property="BorderBrush" Value="{DynamicResource ControlElevationBorderBrush}" />

    
    <Setter Property="Padding" Value="{StaticResource MyControlPadding}" />
</Style>

Step 2: Subscribe to Theme Changes (if needed) Copy Section

If your control needs to react to theme changes programmatically:

using Wpf.Ui.Appearance;

public class MyControl : ContentControl
{
    public MyControl()
    {
        ApplicationThemeManager.Changed += OnThemeChanged;
    }

    private void OnThemeChanged(ApplicationTheme currentTheme, Color systemAccent)
    {
        // React to theme change
        UpdateVisuals(currentTheme);
    }

    private void UpdateVisuals(ApplicationTheme theme)
    {
        // Update control state based on theme
        if (theme == ApplicationTheme.Dark)
        {
            // Dark theme-specific logic
        }
        else
        {
            // Light theme-specific logic
        }
    }
}

Step 3: Use Theme-Aware Brushes Copy Section

Available dynamic brush resources:

Background Brushes:

• ApplicationBackgroundBrush
• ControlFillColorDefaultBrush
• ControlFillColorSecondaryBrush
• ControlFillColorTertiaryBrush
• ControlFillColorDisabledBrush

Foreground Brushes:

• TextFillColorPrimaryBrush
• TextFillColorSecondaryBrush
• TextFillColorTertiaryBrush
• TextFillColorDisabledBrush

Accent Brushes:

• AccentFillColorDefaultBrush
• AccentFillColorSecondaryBrush
• AccentFillColorTertiaryBrush
• SystemAccentColor (Color, not Brush)

Border Brushes:

• ControlElevationBorderBrush
• ControlStrokeColorDefaultBrush
• ControlStrokeColorSecondaryBrush

Step 4: Implement IThemeControl (if applicable) Copy Section

public class MyControl : ContentControl, IThemeControl
{
    /// <summary>Identifies the <see cref="Theme"/> dependency property.</summary>
    public static readonly DependencyProperty ThemeProperty = DependencyProperty.Register(
        nameof(Theme),
        typeof(ApplicationTheme),
        typeof(MyControl),
        new PropertyMetadata(ApplicationTheme.Light, OnThemeChanged)
    );

    /// <summary>
    /// Gets or sets the theme of the control.
    /// </summary>
    public ApplicationTheme Theme
    {
        get => (ApplicationTheme)GetValue(ThemeProperty);
        set => SetValue(ThemeProperty, value);
    }

    private static void OnThemeChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        if (d is MyControl control)
        {
            control.UpdateTheme((ApplicationTheme)e.NewValue);
        }
    }

    private void UpdateTheme(ApplicationTheme theme)
    {
        // Update control based on theme
    }
}

Step 5: Test Theme Switching Copy Section

// Apply theme programmatically
ApplicationThemeManager.Apply(ApplicationTheme.Dark);

// Apply system accent color
ApplicationAccentColorManager.ApplySystemAccent();

// Watch for system theme changes
SystemThemeWatcher.Watch(myWindow);

6. Testing a Feature Copy Chapter

This guide covers both unit testing and integration testing for WPF UI.

Unit Test Example Copy Section

Create tests/Wpf.Ui.UnitTests/Controls/MyControlTests.cs:

/* Detailed source-code truncated for AI context efficiency. */

Integration Test Example Copy Section

Create tests/Wpf.Ui.Gallery.IntegrationTests/MyControlTests.cs:

/* Detailed source-code truncated for AI context efficiency. */

Test Infrastructure Copy Section

Base Test Class (tests/Wpf.Ui.Gallery.IntegrationTests/Fixtures/UiTest.cs):

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using FlaUI.Core;
using FlaUI.Core.AutomationElements;
using FlaUI.UIA3;
using Xunit;

namespace Wpf.Ui.Gallery.IntegrationTests.Fixtures;

public abstract class UiTest : IAsyncLifetime
{
    protected Application? Application { get; private set; }
    protected Window Window { get; private set; } = null!;
    private Process? _process;

    public async Task InitializeAsync()
    {
        // Launch Gallery application
        var appPath = GetApplicationPath();
        _process = Process.Start(appPath);

        await Task.Delay(2000); // Wait for app to start

        // Attach to application
        Application = FlaUI.Core.Application.Attach(_process);

        using var automation = new UIA3Automation();
        Window = Application.GetMainWindow(automation);
    }

    public async Task DisposeAsync()
    {
        Application?.Close();
        Application?.Dispose();

        if (_process != null && !_process.HasExited)
        {
            _process.Kill();
            _process.Dispose();
        }

        await Task.CompletedTask;
    }

    private static string GetApplicationPath()
    {
        // Path to Gallery executable
        return Path.Combine(
            AppDomain.CurrentDomain.BaseDirectory,
            "..\\..\\..\\..\\..\\src\\Wpf.Ui.Gallery\\bin\\Debug\\net10.0-windows\\Wpf.Ui.Gallery.exe"
        );
    }
}

Running Tests Copy Section

# Run all tests
dotnet test

# Run only unit tests
dotnet test tests/Wpf.Ui.UnitTests/Wpf.Ui.UnitTests.csproj

# Run only integration tests
dotnet test tests/Wpf.Ui.Gallery.IntegrationTests/Wpf.Ui.Gallery.IntegrationTests.csproj

# Run with code coverage
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

Common Pitfalls to Avoid Copy Chapter

1. Don't add package versions to .csproj - use Directory.Packages.props only

2. Don't forget handle validation in Win32 interop:

   csharp Copy

   if (handle == IntPtr.Zero || !PInvoke.IsWindow(new HWND(handle)))
       return false;

3. Don't use var for non-apparent types (causes warning)

4. Don't forget MIT license header (causes error via IDE0073)

5. Don't modify control namespace to match folder structure - use flat Wpf.Ui.Controls

6. Don't use StaticResource for theme-dependent values - use DynamicResource

7. Don't forget to register pages and ViewModels in DI container

8. Don't use this. qualification (SA1101 suppressed)

9. Don't add XML docs that restate code - explain WHY, not WHAT

10. Don't skip the [GalleryPage] attribute on Gallery pages

Quick Reference Checklist Copy Chapter

Adding a Control Copy Section

• Create folder under Controls/
• Create .cs file with control class
• Create .xaml file with style
• Implement interfaces (IAppearanceControl, IIconControl)
• Register DependencyProperties with XML docs
• Override DefaultStyleKeyProperty
• Add to Wpf.Ui.xaml MergedDictionaries
• Add toolbox icon (optional)
• Add unit tests

Adding a Service Copy Section

• Create I{Name}Service.cs interface
• Create {Name}Service.cs implementation
• Add DI extension method in Wpf.Ui.DependencyInjection
• Add XML docs with examples
• Add unit tests
• Document in CLAUDE.md

Adding a Gallery Page Copy Section

• Create ViewModel in ViewModels/Pages/{Category}/
• Create Page.xaml in Views/Pages/{Category}/
• Create Page.xaml.cs code-behind
• Add [GalleryPage] attribute
• Register ViewModel and Page in DI
• Add navigation entry (if manual)
• Add code examples with syntax:CodeBlock

Architecture MODULE INTERFACES (`docs/architecture/MODULE-INTERFACES.md`) Copy Section

Module Interfaces

WPF UI v4.2.0 | Public and internal API surface per module

This document defines the public vs internal API surface for each module in the WPF UI solution. It serves as the contract specification for inter-module communication and consumer-facing APIs.

Module Dependency Graph Copy Chapter

graph TD
    subgraph "Public API Surface"
        Abstractions["<b>Wpf.Ui.Abstractions</b><br/><i>Public: 6 types</i><br/><i>Internal: none</i>"]
        Core["<b>Wpf.Ui</b><br/><i>Public: 77+ controls, 6 services,<br/>managers, converters, markup</i><br/><i>Internal: Win32, Interop</i>"]
        DI["<b>Wpf.Ui.DependencyInjection</b><br/><i>Public: 2 types</i><br/><i>Internal: none</i>"]
        Tray["<b>Wpf.Ui.Tray</b><br/><i>Public: 4 types</i><br/><i>Internal: 7 types</i>"]
        Syntax["<b>Wpf.Ui.SyntaxHighlight</b><br/><i>Public: 2 types</i><br/><i>Internal: 2 types</i>"]
    end

    subgraph "Non-Distributable"
        Toast["<b>Wpf.Ui.ToastNotifications</b><br/><i>Public: 1 type (STUB)</i>"]
        FlaUI["<b>Wpf.Ui.FlaUI</b><br/><i>Public: 1 type</i>"]
        FontMapper["<b>Wpf.Ui.FontMapper</b><br/><i>Build-time tool</i>"]
    end

    Core --> Abstractions
    DI --> Abstractions
    Tray --> Core
    Syntax --> Core

    style Abstractions fill:#e1f5ff,stroke:#0277bd
    style Core fill:#fff4e1,stroke:#f57f17
    style DI fill:#e8f5e9,stroke:#2e7d32
    style Tray fill:#e8f5e9,stroke:#2e7d32
    style Syntax fill:#e8f5e9,stroke:#2e7d32
    style Toast fill:#fff9c4,stroke:#f9a825
    style FlaUI fill:#f3e5f5,stroke:#6a1b9a
    style FontMapper fill:#f3e5f5,stroke:#6a1b9a

Module: Wpf.Ui.Abstractions Copy Chapter

NuGet: WPF-UI.Abstractions
TFMs: net10.0, net9.0, net8.0, net462, netstandard2.1, netstandard2.0
Dependencies: None (zero external dependencies)

Public Types Copy Section

Internal Types Copy Section

None. This module is entirely public by design -- it defines the contract surface.

Module: Wpf.Ui (Core) Copy Chapter

NuGet: WPF-UI
TFMs: net10.0-windows, net9.0-windows, net8.0-windows, net481, net472, net462
Dependencies: Wpf.Ui.Abstractions, Microsoft.Windows.CsWin32 (build-time), System.Memory

Public Namespaces Copy Section

Public Service Interfaces Copy Section

Internal / Should-Be-Internal Namespaces Copy Section

Note: Wpf.Ui.Interop and Wpf.Ui.Win32 expose raw P/Invoke declarations that are implementation details. Consumers should not depend on these namespaces. A future major version should mark them internal.

Module: Wpf.Ui.DependencyInjection Copy Chapter

NuGet: WPF-UI.DependencyInjection
TFMs: net10.0, net9.0, net8.0, net462, netstandard2.1, netstandard2.0
Dependencies: Wpf.Ui.Abstractions, Microsoft.Extensions.DependencyInjection.Abstractions 3.1.0

Public Types Copy Section

Internal Types Copy Section

None.

Module: Wpf.Ui.Tray Copy Chapter

NuGet: WPF-UI.Tray
TFMs: net10.0-windows, net9.0-windows, net8.0-windows, net481, net472, net462
Dependencies: Wpf.Ui, System.Drawing.Common

Public Types Copy Section

Internal Types Copy Section

Module: Wpf.Ui.SyntaxHighlight Copy Chapter

NuGet: WPF-UI.SyntaxHighlight
TFMs: net10.0-windows, net9.0-windows, net8.0-windows, net481, net472, net462
Dependencies: Wpf.Ui

Public Types Copy Section

Internal Types Copy Section

Module: Wpf.Ui.ToastNotifications Copy Chapter

NuGet: WPF-UI.ToastNotifications
TFMs: net10.0-windows, net9.0-windows, net8.0-windows, net481, net472, net462
Dependencies: None (standalone stub)

Public Types Copy Section

Warning: This module is a placeholder with no implementation. See RECOMMENDATIONS.md — recommended to either implement or remove.

Module: Wpf.Ui.FlaUI Copy Chapter

NuGet: WPF-UI.FlaUI
TFMs: net10.0-windows, net9.0-windows, net8.0-windows, net481
Dependencies: FlaUI.Core

Public Types Copy Section

Module: Wpf.Ui.FontMapper Copy Chapter

Type: Build-time console tool (not a distributable library)
TFMs: net10.0
Dependencies: None

Public Types Copy Section

None. This is a build tool that generates SymbolRegular and SymbolFilled enums from Fluent System Icons font JSON data. It is not referenced by other projects at runtime.

Cross-Module Interface Rules Copy Chapter

1. Abstractions are the only shared contract. Modules that need to communicate must do so through Wpf.Ui.Abstractions interfaces.
2. Core library is the integration point. Only Wpf.Ui may depend on Win32 interop and WPF framework internals.
3. Satellite packages depend downward only. Tray and SyntaxHighlight depend on Core; they never depend on each other.
4. DI package depends on Abstractions only. Wpf.Ui.DependencyInjection must never take a dependency on Wpf.Ui to keep it lightweight.
5. Internal namespaces are not API surface. Types in Wpf.Ui.Interop and Wpf.Ui.Win32 are implementation details even though they are currently public.

Architecture RECOMMENDATIONS (`docs/architecture/RECOMMENDATIONS.md`) Copy Section

WPF UI - Architecture Recommendations

Generated: 2026-02-10. These recommendations are based on architectural analysis and should be re-evaluated as the codebase evolves.

Recommendations Copy Chapter

Testing Copy Section

Architecture Copy Section

Technical Debt Copy Section

CI/CD Copy Section

Documentation Copy Section

Task Backlog Copy Chapter

Structured work items derived from the recommendations above. Each item includes acceptance criteria (AC).

TB-001: Add unit tests for core controls [Critical] Copy Section

Source: Testing #1
AC:

• NavigationView has ≥5 unit tests covering navigation, caching, back stack
• TitleBar has ≥3 tests covering minimize/maximize/close commands
• FluentWindow has ≥2 tests covering backdrop type selection
• ContentDialog has ≥3 tests covering show/hide/result lifecycle
• NumberBox has ≥3 tests covering min/max/step validation
• ToggleSwitch has ≥2 tests covering checked/unchecked state
• All tests follow MethodName_ExpectedResult_WhenCondition naming convention
• All tests use XUnit v3, NSubstitute, AwesomeAssertions

TB-002: Enable test execution in CI [Critical] Copy Section

Source: CI/CD #1, Testing #2
AC:

• .github/workflows/ contains a job that runs dotnet test tests/Wpf.Ui.UnitTests/ on every PR
• CI job fails the PR if any test fails
• Test results are visible in the GitHub Actions summary
• Job runs on ubuntu-latest or windows-latest as appropriate for WPF tests

TB-003: Add code coverage reporting with threshold [High] Copy Section

Source: CI/CD #2
AC:

• Coverlet generates coverage report during CI test run
• Coverage report is uploaded as a CI artifact or displayed in PR summary
• Minimum coverage threshold is set (≥50% for initial baseline)
• Build fails if coverage drops below threshold

TB-004: Enforce CSharpier formatting in CI [Medium] Copy Section

Source: CI/CD #3
AC:

• CI job runs dotnet csharpier --check . on every PR
• PR fails if any file is not formatted
• Contributing guide documents the dotnet csharpier . command

TB-005: Wrap static theme managers with injectable interfaces [High] Copy Section

Source: Architecture #1
AC:

• IApplicationThemeManager interface exists with Apply(), GetAppTheme(), and Changed event
• IApplicationAccentColorManager interface exists with Apply() and GetColorizationColor()
• Default implementations delegate to existing static classes
• Interfaces are registered in DI via ServiceCollectionExtensions
• Existing static API remains functional (non-breaking change)

TB-006: Document NavigationView page caching strategy [High] Copy Section

Source: Architecture #2
AC:

• XML doc comments on NavigationCacheMode enum explain each mode
• docs/architecture/cross-cutting/navigation.md describes caching lifecycle
• Gallery demo includes a page demonstrating cache mode differences
• At least one unit test verifies cache behavior per mode

TB-007: Implement or remove Wpf.Ui.ToastNotifications [High] Copy Section

Source: Technical Debt #1
AC:

• Decision documented: implement with Windows App SDK toast APIs OR remove from solution
• If implemented: at least one functional toast notification scenario works end-to-end
• If removed: NuGet package is delisted, project removed from solution, references cleaned up

TB-008: Audit and reduce Win32/Interop public API surface [Medium] Copy Section

Source: Technical Debt #2
AC:

• All types in Wpf.Ui.Interop and Wpf.Ui.Win32 are marked internal or documented as public API
• [EditorBrowsable(EditorBrowsableState.Never)] added to types that must remain public for binary compat
• No consumer-facing documentation references internal interop types

TB-009: Add integration tests for NavigationView caching [High] Copy Section

Source: Testing #3
AC:

• FlaUI integration test navigates forward/backward and verifies page instance identity (cached vs new)
• Test covers NavigationCacheMode.Enabled, Disabled, and Required
• Test verifies INavigationAware.OnNavigatedTo/OnNavigatedFrom callback order

TB-010: Add contract tests for service interfaces [Medium] Copy Section

Source: Testing #4
AC:

• INavigationService has ≥3 contract tests (Navigate, GoBack, SetService)
• IContentDialogService has ≥2 contract tests (ShowAsync, SetDialogHost)
• ISnackbarService has ≥2 contract tests (Show, SetPresenter)
• Tests verify interface contracts, not implementation details
• Tests use NSubstitute for mock dependencies

Architecture TESTING SPEC (`docs/architecture/TESTING-SPEC.md`) Copy Section

Testing Specification for AI Agents

Overview Copy Chapter

This document provides testing guidelines for AI agents working on the WPF UI project. The project uses separate unit and integration test suites with distinct frameworks and patterns.

Test Project Structure Copy Chapter

Unit Tests Copy Section

Project: tests/Wpf.Ui.UnitTests/
Target Framework: net10.0-windows
Project Reference: Wpf.Ui

Integration Tests Copy Section

Project: tests/Wpf.Ui.Gallery.IntegrationTests/
Target Framework: net10.0-windows10.0.26100.0
Project References: Wpf.Ui.FlaUI, Wpf.Ui.Gallery

Testing Frameworks Copy Chapter

Unit Testing Stack Copy Section

• XUnit v2-style (PackageReference: xunit, xunit.runner.visualstudio)
• NSubstitute 5.3.0 - Mocking framework
• Standard XUnit Assert - Assertion library
• Coverlet 6.0.4 - Code coverage collector

Integration Testing Stack Copy Section

• XUnit v3 (PackageReference: xunit.v3, xunit.runner.visualstudio)
• FlaUI.UIA3 5.0.0 - UI automation framework
• AwesomeAssertions 9.3.0 - Fluent assertion library (FluentAssertions successor)
• Custom Wpf.Ui.FlaUI - Custom automation element wrappers

Unit Test Template Copy Chapter

Naming Convention Copy Section

MethodName_ExpectedResult_WhenCondition

Alternative format:

GivenCondition_MethodName_ExpectedResult

Basic Structure Copy Section

using Xunit;
using NSubstitute;
using Wpf.Ui.Animations; // Namespace under test

namespace Wpf.Ui.UnitTests.Animations;

public class TransitionAnimationProviderTests
{
    [Fact]
    public void ApplyTransition_ReturnsFalse_WhenDurationIsLessThan10()
    {
        // Arrange
        UIElement mockedUiElement = Substitute.For<UIElement>();

        // Act
        var result = TransitionAnimationProvider.ApplyTransition(
            mockedUiElement,
            Transition.FadeIn,
            -10
        );

        // Assert
        Assert.False(result);
    }

    [Fact]
    public void ApplyTransition_ReturnsFalse_WhenElementIsNull()
    {
        // Arrange
        UIElement? nullElement = null;

        // Act
        var result = TransitionAnimationProvider.ApplyTransition(
            nullElement,
            Transition.FadeIn,
            100
        );

        // Assert
        Assert.False(result);
    }
}

Mocking with NSubstitute Copy Section

// Create mock
UIElement element = Substitute.For<UIElement>();

// Setup return value
INavigationService service = Substitute.For<INavigationService>();
service.Navigate(typeof(DashboardPage)).Returns(true);

// Verify call
service.Received(1).Navigate(Arg.Any<Type>());

Global Usings Copy Section

Located in tests/Wpf.Ui.UnitTests/Usings.cs:

global using System;
global using System.Windows;
global using NSubstitute;
global using Xunit;

Integration Test Template Copy Chapter

Naming Convention Copy Section

Subject_ShouldExpectedBehavior_WhenCondition

Base Class Pattern Copy Section

All integration tests inherit from UiTest:

using AwesomeAssertions;
using FlaUI.Core.AutomationElements;
using FlaUI.UIA3.Patterns;

namespace Wpf.Ui.Gallery.IntegrationTests;

public sealed class NavigationTests : UiTest
{
    [Fact]
    public async Task Settings_ShouldBeAvailable_ThroughAutoSuggestBox()
    {
        // Arrange
        Wpf.Ui.FlaUI.AutoSuggestBox? autoSuggestBox =
            FindFirst("NavigationAutoSuggestBox")?.As<AutoSuggestBox>();

        autoSuggestBox.Should().NotBeNull(
            "because AutoSuggestBox should be present in the navigation bar"
        );

        // Act
        autoSuggestBox!.Enter("Settings");
        await Wait(1);

        // Assert
        TextBox? pageTitle = FindFirst("PageTitle")?.AsTextBox();
        pageTitle.Should().NotBeNull();
        pageTitle!.Text.Should().Be("Settings");
    }
}

UiTest Base Class Features Copy Section

Location: tests/Wpf.Ui.Gallery.IntegrationTests/Fixtures/UiTest.cs

Provided Methods:

// Find element by automation ID
protected AutomationElement? FindFirst(string automationId)

// Find element by condition
protected AutomationElement? FindFirst(Func<ConditionFactory, ConditionBase> buildCondition)

// Wait for specified seconds
protected async Task Wait(int seconds, CancellationToken cancellationToken = default)

// Type text
protected void Enter(string text)

// Press key
protected void Press(VirtualKeyShort key)

Lifecycle:

• IAsyncLifetime implementation
• Each test gets its own application instance
• Application launched via TestedApplication fixture
• Automatic cleanup after test completion

AwesomeAssertions Syntax Copy Section

// Null checks
element.Should().NotBeNull("because element must exist");
element.Should().BeNull();

// String assertions
text.Should().Be("Expected");
text.Should().Contain("substring");
text.Should().StartWith("prefix");

// Boolean assertions
condition.Should().BeTrue("because condition must be met");
Application?.HasExited.Should().BeTrue();

// Collection assertions
items.Should().HaveCount(5);
items.Should().Contain(item);

FlaUI Element Access Copy Section

// Find and cast to specific control
Button? button = FindFirst("ButtonId").AsButton();
TextBox? textBox = FindFirst("TextBoxId")?.AsTextBox();

// Custom automation elements
var autoSuggestBox = FindFirst("AutoSuggestBoxId")?.AsAutoSuggestBox();

// Interact with controls
button.Click(moveMouse: false);
textBox.Text = "value";

// Pattern-based interaction
var invokePattern = element.Patterns.Invoke.Pattern;
invokePattern.Invoke();

Running Tests Copy Chapter

Unit Tests Copy Section

# Run all unit tests
dotnet test tests/Wpf.Ui.UnitTests/

# Run specific test class
dotnet test tests/Wpf.Ui.UnitTests/ --filter "FullyQualifiedName~TransitionAnimationProviderTests"

# Run with coverage
dotnet test tests/Wpf.Ui.UnitTests/ --collect:"XPlat Code Coverage"

Integration Tests Copy Section

# Run all integration tests
dotnet test tests/Wpf.Ui.Gallery.IntegrationTests/

# Run specific test
dotnet test tests/Wpf.Ui.Gallery.IntegrationTests/ --filter "FullyQualifiedName~TitleBarTests"

# Run with diagnostics
dotnet test tests/Wpf.Ui.Gallery.IntegrationTests/ --logger "console;verbosity=detailed"

XUnit Runner Configuration Copy Section

Location: tests/Wpf.Ui.Gallery.IntegrationTests/xunit.runner.json

{
  "$schema": "https://xunit.net/schema/current/xunit.runner.schema.json",
  "parallelizeTestCollections": false,
  "diagnosticMessages": true,
  "culture": "invariant"
}

Important: Integration tests do NOT run in parallel due to single Gallery app instance.

Test Organization Copy Chapter

Namespace Mirroring Copy Section

Test namespaces mirror source namespaces:

src/Wpf.Ui/Animations/TransitionAnimationProvider.cs
↓
tests/Wpf.Ui.UnitTests/Animations/TransitionAnimationProviderTests.cs

File Naming Copy Section

{ClassName}Tests.cs

Test Coverage Areas Copy Section

Current Unit Test Coverage:

• Animations: TransitionAnimationProvider
• Extensions: SymbolExtensions.Swap(), SymbolExtensions.GetString()

Current Integration Test Coverage:

• Window title verification
• TitleBar button interaction (Close, Minimize, Maximize)
• Navigation via AutoSuggestBox
• Navigation via NavigationView
• ContentDialog result verification
• ContentDialog keyboard focus isolation

Guidelines for AI Agents Copy Chapter

When Writing Unit Tests Copy Section

1. Mock dependencies using NSubstitute
2. Test public API surface only
3. Use XUnit Assert methods for assertions
4. Follow naming convention strictly
5. One assertion per test (where logical)
6. Test both success and failure paths

When Writing Integration Tests Copy Section

1. Inherit from UiTest base class
2. Use automation IDs for element discovery
3. Add delays with Wait() for UI updates
4. Use AwesomeAssertions fluent syntax
5. Provide clear "because" messages in assertions
6. Clean up state (handled automatically by fixture)

Test File Template Locations Copy Section

Unit Test Template:

tests/Wpf.Ui.UnitTests/Animations/TransitionAnimationProviderTests.cs
tests/Wpf.Ui.UnitTests/Extensions/SymbolExtensionsTests.cs

Integration Test Template:

tests/Wpf.Ui.Gallery.IntegrationTests/TitleBarTests.cs
tests/Wpf.Ui.Gallery.IntegrationTests/NavigationTests.cs

Common Patterns Copy Chapter

Testing Dependency Properties Copy Section

[Fact]
public void PropertyName_DefaultValue_IsExpected()
{
    var control = new MyControl();
    Assert.Equal(expectedDefault, control.PropertyName);
}

[Fact]
public void PropertyName_CanBeSet_AndRetrieved()
{
    var control = new MyControl();
    var expectedValue = new SomeType();

    control.PropertyName = expectedValue;

    Assert.Equal(expectedValue, control.PropertyName);
}

Testing Services Copy Section

[Fact]
public void Navigate_ReturnsTrue_WhenNavigationSucceeds()
{
    // Arrange
    var pageProvider = Substitute.For<INavigationViewPageProvider>();
    pageProvider.GetPage(Arg.Any<Type>()).Returns(new DashboardPage());

    var service = new NavigationService(pageProvider);
    var navigationView = Substitute.For<INavigationView>();
    service.SetNavigationControl(navigationView);

    // Act
    bool result = service.Navigate(typeof(DashboardPage));

    // Assert
    Assert.True(result);
}

Continuous Integration Copy Chapter

Tests are NOT currently run in CI (PR validator only builds Gallery app).

To add test execution to CI, modify .github/workflows/wpf-ui-pr-validator.yaml:

- name: Run Unit Tests
  run: dotnet test tests/Wpf.Ui.UnitTests/ --no-restore --verbosity normal

- name: Run Integration Tests
  run: dotnet test tests/Wpf.Ui.Gallery.IntegrationTests/ --no-restore --verbosity normal

Architecture UNCERTAINTIES (`docs/architecture/UNCERTAINTIES.md`) Copy Section

Architecture Uncertainties

This document collects areas where the architecture documentation is incomplete or uncertain based on the analysis. These items require further investigation or are subject to change.

Core Library (Group 1) Copy Chapter

Test Coverage Copy Section

Area: tests/ directory (outside analysis scope)

Cannot determine exact test coverage. Given 77+ controls with complex state management (NavigationView journal, ContentDialog async lifecycle), the testability of static managers (ApplicationThemeManager, SystemThemeWatcher) is limited. Service interfaces (INavigationService, IContentDialogService, etc.) are testable through mock implementations.

Current unit test coverage is minimal (6 tests covering Animations and Extensions only).

WindowBackdrop Implementation Copy Section

Area: src/Wpf.Ui/Controls/Window/WindowBackdrop.cs

WindowBackdrop class is referenced in FluentWindow and WindowBackgroundManager (ApplyBackdrop, RemoveBackdrop, RemoveBackground, RemoveTitlebarBackground) but was not directly examined. Likely located in Controls/Window/ directory and provides Mica/Acrylic/Tabbed backdrop effects via DWM APIs.

NavigationView Page Caching Copy Section

Area: src/Wpf.Ui/Controls/NavigationView/NavigationCache.cs and NavigationCacheMode.cs

These files exist but were not deeply examined. The caching strategy for navigation pages includes Required, Enabled, and Disabled modes but the exact implementation details need further investigation.

PolySharp Configuration Copy Section

Area: Central Package Management in Directory.Packages.props

PolySharp is referenced in core library csproj via PolySharpExcludeGeneratedTypes but the actual package reference appears to come from Directory.Packages.props (central package management) which was not fully examined. The exact polyfill configuration and version require verification.

Satellite Libraries (Group 2) Copy Chapter

Toast Notifications Implementation Status Copy Section

Module: Wpf.Ui.ToastNotifications

It is unclear whether this library has any concrete implementation plans or if it is purely a placeholder for future work. The Toast.Show() method throws NotImplementedException. The library has no dependency on Wpf.Ui core despite being a WPF-targeting project.

FlaUI Library Scope Copy Section

Module: Wpf.Ui.FlaUI

The FlaUI library has no project reference to Wpf.Ui, yet it exists under the Wpf.Ui namespace. It only depends on FlaUI.Core. Currently contains only an AutoSuggestBox automation element wrapper. It is unclear whether additional automation elements for other WPF UI controls will be added.

FontMapper Integration Workflow Copy Section

Module: Wpf.Ui.FontMapper

The FontMapper generates enum files for the core library but has no project reference to it. The generated output path uses a relative 'generated/' directory. The exact integration workflow (how generated files reach the core library) is not evident from the project analysis alone.

Additional Issue: FetchVersion() returns a hardcoded version '1.1.316' instead of actually fetching from GitHub API (the API call code is commented out).

SyntaxHighlight Font Dependency Copy Section

Module: Wpf.Ui.SyntaxHighlight

The SyntaxHighlight.xaml references a FontFamily with key 'FiraCode' using pack URI pointing to Wpf.Ui (not Wpf.Ui.SyntaxHighlight), suggesting the font may need to also exist in the core library.

Additional Issue: The CodeBlock.cs is also listed as an EmbeddedResource in the csproj, which is unusual for a source file.

WIP Status: Highlighter class is marked as work in progress. The autodetect language feature defaults to XAML, and C# and XAML use identical regex patterns.

Gallery and Tests (Group 3) Copy Chapter

Gallery MSIX Packaging Copy Section

Module: Wpf.Ui.Gallery.Package

A .wapproj (Windows Application Packaging) project is referenced in Wpf.Ui.Gallery.slnf but not directly analyzed. This likely creates an MSIX package for the Gallery app. The packaging configuration and deployment process need clarification.

GalleryAssembly Reference Copy Section

Area: src/Wpf.Ui.Gallery/ControlsLookup/

Referenced as GalleryAssembly.Asssembly (note triple 's') in DependencyModel and ControlsLookup. The actual GalleryAssembly class was not directly read. It likely provides the Gallery assembly reference for reflection-based page discovery.

ReflectionEventing Usage Copy Section

Package: ReflectionEventing and ReflectionEventing.DependencyInjection

These packages are referenced in the Gallery csproj but their usage was not traced to specific event handling code within the analyzed files. The purpose and integration point of these packages require investigation.

Visual Studio Extension Copy Section

Module: src/Wpf.Ui.Extension

The VS2022 extension project (.vsix) is built for x64 and arm64 platforms but was not analyzed. The extension capabilities and integration points with Visual Studio are unknown.

Build and Infrastructure Copy Chapter

.NET SDK Version Mismatch Copy Section

Area: build.ps1

The build script references .NET SDK 8 for installation (winget install Microsoft.DotNet.SDK.8) but the project now targets .NET 10. The build script may be outdated.

Dependabot Target Branch Copy Section

Area: .github/dependabot.yml

The Dependabot configuration targets the 'development' branch, not 'main'. The branch strategy and merge workflow from development to main are not documented.

CI Test Execution Copy Section

Area: .github/workflows/wpf-ui-pr-validator.yaml

The PR validator workflow only builds the Gallery app and does not run any tests (unit or integration). The rationale for not including test execution in CI is unclear.

Strong-Name Signing Copy Section

Area: GitHub Actions secrets and certificate management

The CD pipeline fetches a strong-name certificate from GitHub secrets (${{ secrets.WPF_UI_CERTIFICATE_BASE64 }}). The certificate generation, storage, and rotation procedures are not documented.

Documentation and Versioning Copy Chapter

Version Synchronization Copy Section

Area: Directory.Build.props vs actual package versions

The Version property is set to 4.2.0, but the synchronization mechanism between this central version, individual package versions, and changelog updates is not documented.

API Compatibility Copy Section

Area: Deprecated APIs and migration paths

Several APIs are marked [Obsolete] (ContentDialog legacy constructors, WindowBackgroundManager.UpdateBackground with forceBackground parameter). The deprecation timeline and migration strategy for consumers are not documented.

Automation Peer Coverage Copy Chapter

Area: src/Wpf.Ui/AutomationPeers/

Only 4 automation peers exist for 77+ controls:

• CardControlAutomationPeer
• ContentDialogAutomationPeer
• CardActionAutomationPeer
• NavigationViewItemAutomationPeer

Many interactive controls (Button, NavigationView base, TextBox, etc.) may lack custom automation peer implementations. The strategy for expanding accessibility support is unclear. This potentially affects screen reader compatibility and UI automation testing.

Theme Resource Keys Copy Chapter

Area: Dynamic resource naming and contracts

20+ accent-related dynamic resources are updated programmatically by ApplicationAccentColorManager:

• SystemAccentColor
• AccentFillColorDefault
• TextOnAccentFillColorPrimary
• (and others)

The complete list of dynamic resources and their contracts (expected types, update triggers) is not centrally documented. Third-party theme authors may struggle to determine which resources must be provided.

Multi-Target Conditional Compilation Copy Chapter

Area: Cross-framework API compatibility

Various conditional compilation symbols are used:

• NET5_0_OR_GREATER
• NET6_0_OR_GREATER
• NET8_0_OR_GREATER
• NET48_OR_GREATER_or_NETCOREAPP3_0_OR_GREATER

The decision matrix for when to use each symbol and the feature availability across frameworks is not documented in a single location.

System Requirements Copy Chapter

Area: Minimum Windows version and feature matrix

The library supports Windows 7 through Windows 11, but feature availability varies:

• Mica/Acrylic backdrops require Windows 11
• Some DWM features require Windows 10
• Certain APIs have Fall Creators Update requirements

A comprehensive feature compatibility matrix by Windows version is not documented.

Documentation About Wpf (`docs/documentation/about-wpf.md`) Copy Section

What is WPF

WPF (Windows Presentation Foundation) is a resolution-independent UI framework for building Windows desktop applications. It provides vector-based graphics, advanced layout, data binding, multimedia, animation, and extensive styling and templating capabilities.

.NET Framework vs Modern .NET Copy Chapter

WPF has two implementations:

Modern .NET (.NET 6+): Open-source implementation hosted on GitHub. Provides improved performance, new APIs, side-by-side deployment, and modern tooling. Despite .NET being cross-platform, WPF only runs on Windows.

.NET Framework 4: Legacy Windows-only implementation. Maintained for compatibility with existing applications but receives minimal new features.

New WPF applications should target modern .NET (.NET 6 or later) to benefit from:

• Better performance and reduced memory usage
• Regular updates and new features
• Modern C# language versions
• Improved debugging and diagnostics
• Side-by-side deployment without machine-wide installations

Documentation Accent (`docs/documentation/accent.md`) Copy Section

Accent Colors

Accent colors provide visual emphasis and brand identity in WPF UI applications. The library manages accent color resources that automatically adapt to light and dark themes.

[!TIP]
Use SystemThemeWatcher.Watch(this) in your main window constructor to automatically sync accent colors with Windows personalization settings.

Apply System Accent Copy Chapter

Use the system's personalization accent color:

using Wpf.Ui.Appearance;

ApplicationAccentColorManager.ApplySystemAccent();

Apply Theme with Accent Copy Chapter

Apply theme and accent together:

using Wpf.Ui.Appearance;
using Wpf.Ui.Controls;

ApplicationThemeManager.Apply(
    ApplicationTheme.Dark,
    WindowBackdropType.Mica,
    updateAccent: true  // Automatically applies system accent
);

Available backdrop types: None, Auto, Mica, Acrylic, Tabbed.

[!IMPORTANT]
Always use DynamicResource (not StaticResource) for accent color bindings to receive runtime updates when accent changes.

Apply Custom Accent Copy Chapter

Set a custom accent color:

ApplicationAccentColorManager.Apply(
    Color.FromArgb(0xFF, 0xEE, 0x00, 0xBB),
    ApplicationTheme.Dark
);

Retrieve the Windows colorization color programmatically:

Color colorizationColor = ApplicationAccentColorManager.GetColorizationColor();
ApplicationAccentColorManager.Apply(colorizationColor, ApplicationTheme.Dark);

Accent Color Resources Copy Chapter

WPF UI provides these accent color resources:

System Accent Colors Copy Section

Base accent colors that update when you call ApplicationAccentColorManager.Apply():

• SystemAccentColor - Primary system accent
• SystemAccentColorPrimary - Lighter/darker variant for light/dark themes
• SystemAccentColorSecondary - More prominent variant (most commonly used)
• SystemAccentColorTertiary - Strongest variant

<Border Background="{DynamicResource SystemAccentColorSecondaryBrush}" />

[!TIP]
SystemAccentColorSecondary is the most commonly used variant for interactive elements and provides optimal contrast in both light and dark themes.

Accent Text Colors Copy Section

For text and interactive elements like links:

• AccentTextFillColorPrimaryBrush - Primary accent text (rest/hover state)
• AccentTextFillColorSecondaryBrush - Secondary accent text
• AccentTextFillColorTertiaryBrush - Tertiary accent text (pressed state)
• AccentTextFillColorDisabledBrush - Disabled accent text

<ui:Anchor
    Content="WPF UI Documentation"
    NavigateUri="https://wpfui.lepo.co/"
    Foreground="{DynamicResource AccentTextFillColorPrimaryBrush}" />

Accent Fill Colors Copy Section

For button backgrounds and filled surfaces:

• AccentFillColorDefaultBrush - Default accent fill
• AccentFillColorSecondaryBrush - Secondary fill (90% opacity)
• AccentFillColorTertiaryBrush - Tertiary fill (80% opacity)
• AccentFillColorDisabledBrush - Disabled state fill

<Button Background="{DynamicResource AccentFillColorDefaultBrush}" />

Text on Accent Colors Copy Section

For text displayed on accent-colored backgrounds. These resources automatically adjust to black or white based on accent brightness:

• TextOnAccentFillColorPrimary - Primary text color on accent backgrounds
• TextOnAccentFillColorSecondary - Secondary text on accent backgrounds
• TextOnAccentFillColorDisabled - Disabled text on accent backgrounds

[!NOTE]
Text colors automatically switch between black and white when accent brightness exceeds 80% HSV to maintain readability.

Theme-Specific Behavior Copy Chapter

Accent variants adjust automatically based on the application theme:

Dark Theme:

• Primary: Base color + 17 brightness, -30% saturation
• Secondary: Base color + 17 brightness, -45% saturation
• Tertiary: Base color + 17 brightness, -65% saturation

Light Theme:

• Primary: Base color - 10 brightness
• Secondary: Base color - 25 brightness
• Tertiary: Base color - 40 brightness

[!NOTE]
Brightness adjustments are calculated in HSV color space. Negative values darken the color, positive values lighten it.

Advanced: Custom Accent Variants Copy Chapter

Specify all accent variants manually:

ApplicationAccentColorManager.Apply(
    systemAccent: Color.FromArgb(0xFF, 0x00, 0x78, 0xD4),
    primaryAccent: Color.FromArgb(0xFF, 0x00, 0x67, 0xC0),
    secondaryAccent: Color.FromArgb(0xFF, 0x00, 0x3E, 0x92),
    tertiaryAccent: Color.FromArgb(0xFF, 0x00, 0x1A, 0x68)
);

[!CAUTION]
Manually specified accent variants won't automatically adjust when theme changes. Consider using automatic variant generation unless you need precise color control.

Accessing Current Accent Copy Chapter

Read current accent colors from ApplicationAccentColorManager:

Color currentSystemAccent = ApplicationAccentColorManager.SystemAccent;
Color currentPrimaryAccent = ApplicationAccentColorManager.PrimaryAccent;
Color currentSecondaryAccent = ApplicationAccentColorManager.SecondaryAccent;
Color currentTertiaryAccent = ApplicationAccentColorManager.TertiaryAccent;

Brush accentBrush = ApplicationAccentColorManager.SystemAccentBrush;

Theme Changed Event Copy Chapter

Monitor accent changes when theme is applied:

ApplicationThemeManager.Changed += (theme, accent) =>
{
    Debug.WriteLine($"Theme changed to {theme}, accent: {accent}");
};

Automatic System Theme Tracking Copy Chapter

Use SystemThemeWatcher to automatically update theme and accent when Windows settings change:

using Wpf.Ui.Appearance;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        // Watch system theme changes with Mica backdrop and accent updates
        SystemThemeWatcher.Watch(this);
        
        InitializeComponent();
    }
}

With custom backdrop and accent settings:

SystemThemeWatcher.Watch(
    this,
    WindowBackdropType.Acrylic,
    updateAccents: true
);

Stop watching for theme changes:

SystemThemeWatcher.UnWatch(this);

[!NOTE]
SystemThemeWatcher monitors WM_WININICHANGE messages and automatically applies system theme and accent when Windows personalization settings change.

Documentation Extension (`docs/documentation/extension.md`) Copy Section

Visual Studio 2022 Extension for WPF UI

Visual Studio allows you to add extensions that can be installed in several ways:

• Build them locally and then install the .vsix package.
• Download the extension from the internet and install the .vsix file.
• Install the extension using the search in Visual Studio.

In this tutorial, we'll cover the last way, if you want to know more, check out Manage extensions for Visual Studio.

In any case, if you want to download a plugin and install it manually, or leave your review, you can find it in the Visual Studio Marketplace:
https://marketplace.visualstudio.com/items?itemName=lepo.wpf-ui

[!NOTE]
The source code for WPF UI Visual Studio 2022 extension is public and you can check it out here.

How to? Copy Chapter

1. Install Visual Studio 2022 from Visual Studio 2022 downloads.

2. After installation, open Visual Studio

3. Expand the Extensions tab in the menu and then click Manage Extensions

4. In the Online tab, use the search engine to enter WPF-UI in it, then click Download

5. After downloading, restart Visual Studio

6. After restarting, you will see a window asking you to confirm the installation.

7. Once installed, you can restart Visual Studio and click Create new project

8. In the top right corner, you can select the project type

9. Voila, you have just installed the WPF UI extension.

Done! Copy Chapter

After creating a project, you can familiarize yourself with its structure and proceed to further steps.

• WPF UI - Getting started
• Introduction to the MVVM Toolkit
• .NET Generic Host in ASP.NET Core

Documentation Fonticon (`docs/documentation/fonticon.md`) Copy Section

FontIcon

FontIcon is a control responsible for rendering icons based on the provided font.

Implementation Copy Section

class Wpf.Ui.Controls.FontIcon

Exposes Copy Chapter

// Gets or sets displayed glyph
FontIcon.Glyph = '\uE00B';

// Gets or sets used font family
FontIcon.FontFamily = "Segoe Fluent Icons";

// Icon foreground
FontIcon.Foreground = Brushes.White;

// Icon size
FontIcon.FontSize = 16;

How to use Copy Section

<ui:FontIcon
  Glyph="&#xe00b;"
  FontFamily="{DynamicResource SegoeFluentIcons}"
  FontSize="16"
  Foreground="White"/>

Documentation Gallery (`docs/documentation/gallery.md`) Copy Section

WPF UI Gallery

WPF UI Gallery is a free application available in the Microsoft Store, with which you can test all functionalities.
https://apps.microsoft.com/store/detail/wpf-ui/9N9LKV8R9VGM

$ winget install 'WPF UI'

Documentation Icons (`docs/documentation/icons.md`) Copy Section

Fluent System Icons

Fluent System Icons is a set of icons that is designed to be used with Microsoft's Fluent Design System. It is a collection of over 1,500 icons that are designed to be modern, consistent, and scalable, and can be used in a variety of applications and platforms, including web and mobile applications.

The Fluent System Icons set includes a range of icons, such as those for basic navigation, media playback, communication, and more. The icons are available in various sizes, from 16x16 to 512x512 pixels, and are provided in vector format, allowing for easy scaling and customization.

Fluent System Icons is available for free and can be downloaded from the official Microsoft website. It is also open source, meaning that developers can contribute to the icon set or create their own custom icons based on the existing ones.
Fluent UI System Icons

WPF UI uses Fluent UI System Icons in most of the graphical controls.

Getting started Copy Chapter

Icons are displayed by using the font that comes with the library. All glyphs are mapped to the SymbolRegular and SymbolFilled enums.

Icon controls and fonts will be automatically added to your application if you add ControlsDictionary in the App.xaml file:

<Application
    ...
    xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
    <Application.Resources>
        <ui:ThemesDictionary Theme="Dark" />
        <ui:ControlsDictionary />
    </Application.Resources>
</Application>

[!NOTE]
You can find out how the Control Dictionary works here

Segoe Fluent Icons Copy Chapter

Not all icons available in WinUi 3 are in Fluent UI System Icons. Some of them require the Segoe Fluent Icons font.
According to the EULA of Segoe Fluent Icons we cannot ship a copy of it with this dll. Segoe Fluent Icons is installed by default on Windows 11, but if you want these icons in an application for Windows 10 and below, you must manually add the font to your application's resources.
https://docs.microsoft.com/en-us/windows/apps/design/style/segoe-fluent-icons-font
https://docs.microsoft.com/en-us/windows/apps/design/downloads/#fonts

In the App.xaml dictionaries, you can add an alternate path to the font

<Application
    ...
    xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
    <Application.Resources>
        <ui:ThemesDictionary Theme="Dark" />
        <ui:ControlsDictionary />

        <FontFamily x:Key="SegoeFluentIcons">pack://application:,,,/;component/Fonts/#Segoe Fluent Icons</FontFamily>
    </Application.Resources>
</Application>

Documentation Navigation View (`docs/documentation/navigation-view.md`) Copy Section

NavigationView

NavigationView is a top-level navigation control that provides a collapsible navigation pane (the "hamburger menu") and a content area. It is the primary way to implement top-level navigation in your app.

[!TIP]
For a complete implementation example, see the WPF UI Gallery application.

Anatomy Copy Chapter

The NavigationView control has several key areas:

• Pane: The area on the left or top that contains navigation items.
• Header: An area at the top of the content area, often used for a page title or a BreadcrumbBar.
• Content Area: The main area of the control where page content is displayed.
• AutoSuggestBox: An optional search box integrated into the navigation pane.
• MenuItems: The primary list of navigation items.
• FooterMenuItems: A secondary list of navigation items, typically for settings or about pages.

Basic Usage Copy Chapter

Define NavigationView in your XAML and add NavigationViewItem objects to the MenuItems and FooterMenuItems collections.

<ui:NavigationView
    xmlns:pages="clr-namespace:YourApp.Views.Pages"
    xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
    <ui:NavigationView.MenuItems>
        <ui:NavigationViewItem
            Content="Home"
            Icon="{ui:SymbolIcon Home24}"
            TargetPageType="{x:Type pages:DashboardPage}" />
        <ui:NavigationViewItem
            Content="Data"
            Icon="{ui:SymbolIcon DataHistogram24}"
            TargetPageType="{x:Type pages:DataPage}" />
    </ui:NavigationView.MenuItems>
    <ui:NavigationView.FooterMenuItems>
        <ui:NavigationViewItem
            Content="Settings"
            Icon="{ui:SymbolIcon Settings24}"
            TargetPageType="{x:Type pages:SettingsPage}" />
    </ui:NavigationView.FooterMenuItems>
</ui:NavigationView>

[!NOTE]
TargetPageType is a required property on NavigationViewItem that specifies the page to navigate to when the item is selected. The value must be a System.Type.

Programmatic Navigation Copy Chapter

You can navigate programmatically by calling the Navigate method with either the Type of the page or its PageTag.

// Navigate by Type
MyNavigationView.Navigate(typeof(SettingsPage));

// Navigate by Tag
MyNavigationView.Navigate("settings");

To use tags, you must define a PageTag on the NavigationViewItem. If not defined, a tag is automatically generated from the Content property (e.g., "Settings Page" becomes "settingspage").

<ui:NavigationViewItem
    Content="Settings"
    PageTag="settings"
    TargetPageType="{x:Type pages:SettingsPage}" />

Back Navigation Copy Section

NavigationView automatically handles back navigation. The back button is shown when CanGoBack is true. You can also call GoBack() programmatically.

if (MyNavigationView.CanGoBack)
{
    MyNavigationView.GoBack();
}

Pane Display Mode Copy Chapter

Control the visibility and behavior of the navigation pane with the PaneDisplayMode property.

• Left: The pane is always open on the left.
• Top: The pane is shown as a horizontal bar at the top.
• LeftCompact: The pane is collapsed to show only icons, and expands on hover or when the hamburger button is clicked.
• LeftMinimal: The pane is hidden and can be opened as an overlay.

<ui:NavigationView PaneDisplayMode="Top" />

You can also control the pane's open state with the IsPaneOpen property.

[!TIP]
To create a responsive layout that changes PaneDisplayMode based on window width, bind PaneDisplayMode to a property in your ViewModel and update it in the Window.SizeChanged event.

Header Copy Chapter

The Header property provides a content area above the navigation frame. It is commonly used with a BreadcrumbBar to show the user's location.

<ui:NavigationView>
    <ui:NavigationView.Header>
        <ui:BreadcrumbBar />
    </ui:NavigationView.Header>
</ui:NavigationView>

The BreadcrumbBar will automatically sync with the NavigationView's navigation history.

MVVM Integration Copy Chapter

For MVVM applications, it is recommended to use INavigationService and IPageService for navigation and page resolution.

1. Service Configuration Copy Section

First, register the required services and your pages/ViewModels with your dependency injection container.

// Using Microsoft.Extensions.DependencyInjection
Host.CreateDefaultBuilder()
    .ConfigureServices((context, services) =>
    {
        // Main window
        services.AddScoped<IWindow, MainWindow>();
        services.AddScoped<MainWindowViewModel>();

        // Services
        services.AddSingleton<INavigationService, NavigationService>();
        services.AddSingleton<IPageService, PageService>();

        // Pages and ViewModels
        services.AddScoped<DashboardPage>();
        services.AddScoped<DashboardViewModel>();
        services.AddScoped<SettingsPage>();
        services.AddScoped<SettingsViewModel>();
    }).Build();

2. ViewModel Setup Copy Section

In your MainWindowViewModel, define collections for your navigation items and bind them to the NavigationView.

public partial class MainWindowViewModel : ObservableObject
{
    [ObservableProperty]
    private ICollection<object> _menuItems = new ObservableCollection<object>();

    [ObservableProperty]
    private ICollection<object> _footerMenuItems = new ObservableCollection<object>();

    public MainWindowViewModel()
    {
        MenuItems = new ObservableCollection<object>
        {
            new NavigationViewItem("Home", SymbolRegular.Home24, typeof(DashboardPage)),
            new NavigationViewItem("Data", SymbolRegular.DataHistogram24, typeof(DataPage))
        };

        FooterMenuItems = new ObservableCollection<object>
        {
            new NavigationViewItem("Settings", SymbolRegular.Settings24, typeof(SettingsPage))
        };
    }
}

3. View Setup Copy Section

In your MainWindow.xaml, bind the MenuItemsSource and FooterMenuItemsSource properties to the collections in your ViewModel. Then, attach the INavigationService.

<ui:NavigationView
    x:Name="RootNavigationView"
    MenuItemsSource="{Binding MenuItems}"
    FooterMenuItemsSource="{Binding FooterMenuItems}" />

public partial class MainWindow : IWindow
{
    public MainWindow(
        MainWindowViewModel viewModel,
        INavigationService navigationService,
        IPageService pageService
    )
    {
        ViewModel = viewModel;
        DataContext = this;
        InitializeComponent();

        // Attach the service to the NavigationView
        navigationService.SetNavigationControl(RootNavigationView);
        
        // You can also set the page service, which is required for some functionalities
        RootNavigationView.SetPageService(pageService);
    }

    public MainWindowViewModel ViewModel { get; }
}

4. Navigating from a ViewModel Copy Section

Inject INavigationService into any ViewModel and use it to navigate.

public partial class DashboardViewModel : ObservableObject
{
    private readonly INavigationService _navigationService;

    public DashboardViewModel(INavigationService navigationService)
    {
        _navigationService = navigationService;
    }

    [RelayCommand]
    private void OnGoToSettings()
    {
        _navigationService.Navigate(typeof(SettingsPage));
    }
}

Navigation Events Copy Chapter

NavigationView provides several events to hook into the navigation lifecycle:

• Navigating: Occurs before navigation starts. Can be cancelled.
• Navigated: Occurs after navigation is complete.
• SelectionChanged: Occurs when a NavigationViewItem is selected.

private void OnNavigating(NavigationView sender, NavigatingCancelEventArgs args)
{
    // Don't navigate to settings if the user is not an admin
    if (args.PageType == typeof(SettingsPage) && !_isAdmin)
    {
        args.Cancel = true;
    }
}

Navigation-Aware Pages Copy Chapter

Implement INavigationAware on your page's code-behind or INavigableView<T> on your ViewModel to receive navigation events directly.

INavigationAware Copy Section

This interface is ideal for code-behind scenarios.

public partial class MyPage : INavigationAware
{
    public void OnNavigatedTo()
    {
        // Page was navigated to
    }

    public void OnNavigatedFrom()
    {
        // Page was navigated away from
    }
}

`INavigableView` Copy Section

This interface is designed for MVVM. Your page must inherit from INavigableView<T> where T is its ViewModel. The ViewModel will then receive the navigation calls.

Page:

[GalleryPage("My Page", SymbolRegular.Page24)]
public partial class MyPage : INavigableView<MyViewModel>
{
    public MyViewModel ViewModel { get; }

    public MyPage(MyViewModel viewModel)
    {
        ViewModel = viewModel;
        DataContext = this;
        InitializeComponent();
    }
}

ViewModel:

public partial class MyViewModel : ObservableObject, INavigationAware
{
    public void OnNavigatedTo()
    {
        // Page was navigated to
    }

    public void OnNavigatedFrom()
    {
        // Page was navigated away from
    }
}

[!IMPORTANT]
For INavigableView<T> to work, your page must have a public ViewModel property that returns an instance of the ViewModel.

History and Caching Copy Chapter

NavigationView maintains a navigation history.

• History: A collection of Page instances that have been visited.
• CacheHistory: The number of pages to keep in memory. The default is 0. Set to a value greater than 0 to cache pages. When a cached page is navigated to, its previous state is preserved.

<ui:NavigationView CacheHistory="5" />

[!CAUTION]
Caching pages increases memory consumption. Use it only for pages that are expensive to create or where preserving state is critical. Avoid caching pages that display frequently changing data.

Documentation Nuget (`docs/documentation/nuget.md`) Copy Section

NuGet package for WPF UI

What's NuGet? Copy Chapter

NuGet is a free, open-source package management system for the Microsoft .NET platform. It simplifies the process of finding, installing, and managing third-party libraries and tools in .NET projects. NuGet allows developers to easily add functionality to their projects without having to manually download and reference external libraries. It also provides a way for developers to publish and share their own packages with the .NET community. Overall, NuGet makes it easier to manage dependencies in .NET projects and helps to improve productivity for developers.

• Read more here
• How to install NuGet packages
• Install and manage packages in Visual Studio using the NuGet Package Manager

How to install **WPF UI** in Visual Studio using the NuGet Package Manager? Copy Chapter

1. Create new WPF project Copy Section

2. Open _Manage NuGet Packages_ window via solution explorer Copy Section

3. In the _Browse_ tab, enter "**WPF-UI**" Copy Section

4. Install **WPF-UI** package Copy Section

Done!

Package installed, to learn more, go to the Getting started page.

Documentation Releases (`docs/documentation/releases.md`) Copy Section

WPF UI Releases

Documentation Symbolicon (`docs/documentation/symbolicon.md`) Copy Section

SymbolIcon

SymbolIcon is a control responsible for rendering icons.

Implementation Copy Section

class Wpf.Ui.Controls.SymbolIcon

Exposes Copy Chapter

// Gets or sets displayed symbol
SymbolIcon.Symbol = SymbolRegular.Empty;

// Defines whether or not we should use the SymbolFilled
SymbolIcon.Filled = false;

// Icon foreground
SymbolIcon.Foreground = Brushes.White;

// Icon size
SymbolIcon.FontSize = 16;

How to use Copy Section

<ui:SymbolIcon
  Symbol="Fluent24"
  Filled="False"
  FontSize="16"
  Foreground="White"/>

Documentation System Theme Watcher (`docs/documentation/system-theme-watcher.md`) Copy Section

SystemThemeWatcher

SystemThemeWatcher automatically synchronizes the application's theme, accent color, and window backdrop with the current Windows theme settings. It listens for system-level changes and applies them to your application in real-time.

[!TIP]
The simplest way to enable system theme tracking is to call SystemThemeWatcher.Watch(this); in your main window's constructor.

How It Works Copy Chapter

SystemThemeWatcher attaches a hook to a window's message procedure (WndProc) and listens for the WM_WININICHANGE system message. When Windows broadcasts this message (e.g., when the user changes from light to dark mode), the watcher automatically calls ApplicationThemeManager.ApplySystemTheme() to update your application's appearance.

Basic Usage Copy Chapter

Enable theme watching in your window's constructor. This will use the default Mica backdrop and update accent colors.

using Wpf.Ui.Appearance;

public partial class MainWindow : System.Windows.Window
{
    public MainWindow()
    {
        // This will apply the system theme, accent, and default backdrop.
        SystemThemeWatcher.Watch(this);

        InitializeComponent();
    }
}

Customization Copy Chapter

You can customize the backdrop effect and control whether the accent color is updated.

Window Backdrop Copy Section

Specify the WindowBackdropType to apply when the theme changes.

SystemThemeWatcher.Watch(
    this,
    WindowBackdropType.Acrylic // Use Acrylic backdrop
);

Available backdrop types:

• None: No backdrop effect.
• Auto: Automatically selects the appropriate backdrop.
• Mica: The default Windows 11 Mica effect.
• Acrylic: The semi-transparent Acrylic effect.
• Tabbed: A blurred wallpaper effect available in recent Windows 11 versions.

Accent Color Updates Copy Section

You can prevent the watcher from changing the application's accent color.

SystemThemeWatcher.Watch(
    this,
    updateAccents: false // Theme will change, but accent color will not
);

Stop Watching Copy Chapter

To stop a window from responding to system theme changes, use the UnWatch method.

SystemThemeWatcher.UnWatch(this);

[!IMPORTANT]
Do not call UnWatch on a window that has not been loaded, as it will throw an InvalidOperationException. It is safe to call Watch on a window that is not yet loaded.

Dependency Injection Usage Copy Chapter

If you are resolving your main window from a dependency injection container, you can start the watcher after the host is built.

var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddHostedService<ApplicationHostService>();
        services.AddSingleton<MainWindow>();
        // ... other services
    }).Build();

await host.StartAsync();

var mainWindow = host.Services.GetRequiredService<MainWindow>();

// Watch the window after it's been created
SystemThemeWatcher.Watch(mainWindow);

[!NOTE]
SystemThemeWatcher works on a static, global basis. While you can Watch multiple windows, the theme and accent settings applied will be the same for all of them based on the parameters of the last Watch call that triggered an update.

Documentation Themes (`docs/documentation/themes.md`) Copy Section

Application Themes

WPF UI provides a robust theming system that allows you to control your application's appearance, including support for light, dark, and high contrast modes. The ApplicationThemeManager class is the primary tool for managing themes at runtime.

[!IMPORTANT]
For theme changes to apply correctly, your colors and brushes should be referenced as DynamicResource.

Setting the Initial Theme Copy Chapter

The easiest way to set the initial theme is by using the ThemesDictionary in your App.xaml. This ensures that the correct theme resources are loaded at startup.

<Application
    xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ui:ThemesDictionary Theme="Light" />
                <ui:ControlsDictionary />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

The Theme property on ThemesDictionary can be set to Light or Dark.

Changing the Theme at Runtime Copy Chapter

Use the ApplicationThemeManager.Apply() method to change the theme while the application is running.

using Wpf.Ui.Appearance;
using Wpf.Ui.Controls;

// Apply the Light theme with a Mica backdrop
ApplicationThemeManager.Apply(
    ApplicationTheme.Light,
    WindowBackdropType.Mica
);

`ApplicationTheme` Enum Copy Section

This enum specifies the theme to apply:

• Light: The standard light theme.
• Dark: The standard dark theme.
• HighContrast: Automatically selects the appropriate Windows High Contrast theme.

System Theme Integration Copy Chapter

You can synchronize your application's theme with the current Windows theme settings.

One-Time Sync Copy Section

To apply the current system theme once, use ApplySystemTheme().

// Apply the current Windows theme (light or dark)
ApplicationThemeManager.ApplySystemTheme();

Automatic Tracking Copy Section

For continuous synchronization, use the SystemThemeWatcher. It automatically updates your app's theme and accent color when the user changes their Windows settings. See the SystemThemeWatcher documentation for more details.

using Wpf.Ui.Appearance;

public partial class MainWindow : System.Windows.Window
{
    public MainWindow()
    {
        // Watch for system theme changes
        SystemThemeWatcher.Watch(this);

        InitializeComponent();
    }
}

Reading the Current Theme Copy Chapter

You can get the current application and system themes at any time.

• ApplicationThemeManager.GetAppTheme(): Returns the current ApplicationTheme (Light, Dark, or HighContrast).
• ApplicationThemeManager.GetSystemTheme(): Returns the current SystemTheme.

ApplicationTheme currentAppTheme = ApplicationThemeManager.GetAppTheme();
SystemTheme currentSystemTheme = ApplicationThemeManager.GetSystemTheme();

if (currentAppTheme == ApplicationTheme.Dark)
{
    // ...
}

`SystemTheme` Enum Copy Section

This enum represents the actual theme reported by Windows, including decorative themes like Glow, CapturedMotion, and Sunrise. ApplicationThemeManager maps these to either Light or Dark.

High Contrast Themes Copy Chapter

WPF UI automatically handles Windows High Contrast themes. When a high contrast mode is detected, ApplicationThemeManager loads the appropriate high contrast resource dictionary (HC1, HC2, HCBlack, or HCWhite).

• ApplicationThemeManager.IsHighContrast(): Checks if the application is currently in a high contrast theme.
• ApplicationThemeManager.IsSystemHighContrast(): Checks if Windows is currently in a high contrast mode.

Theme Changed Event Copy Chapter

The ApplicationThemeManager.Changed event is triggered whenever the application's theme is successfully changed.

ApplicationThemeManager.Changed += (currentTheme, currentAccent) =>
{
    Debug.WriteLine($"Theme changed to {currentTheme} with accent {currentAccent}");
};

This event is useful for applying custom logic after a theme change, such as updating graphics or non-WPF UI elements.

[!TIP]
The Changed event is fired by both manual Apply() calls and automatic updates from SystemThemeWatcher, providing a single place to react to any theme change.

Migration V2 Migration (`docs/migration/v2-migration.md`) Copy Section

Migration plan

This page outlines key changes and important details to consider when migrating. It highlights what’s new, what’s changed, and any steps you need to take to ensure a smooth transition. This isn’t a full step-by-step guide but a quick reference to help you navigate the most critical parts of the migration process.

Key changes in v2 Copy Chapter

Global namespace change Copy Section

In version 2.0 the namespace has been changed from WPF-UI to the more .NET compatible Wpf.Ui. The package name has not been changed to maintain branding and consistency.

Navigation Copy Section

The navigation control has been rewritten yet again, making it almost completely incompatible.

All navigation controls inherit from Wpf.Ui.Controls.Navigation.NavigationBase base class.

<ui:NavigationStore
  Frame="{Binding ElementName=RootFrame}"
  Precache="False"
  SelectedPageIndex="-1"
  TransitionDuration="200"
  TransitionType="FadeInWithSlide">
  <ui:NavigationStore.Items>
    <ui:NavigationItem
      Cache="True"
      Content="Home"
      Icon="Home24"
      PageTag="dashboard"
      PageType="{x:Type pages:Dashboard}" />
    <ui:NavigationSeparator />
  </ui:NavigationStore.Items>
  <ui:NavigationStore.Footer>
    <ui:NavigationItem
      Click="NavigationButtonTheme_OnClick"
      Content="Theme"
      Icon="DarkTheme24" />
  </ui:NavigationStore.Footer>
</ui:NavigationStore>

<ui:NavigationFluent
  Frame="{Binding ElementName=RootFrame}"
  Precache="False"
  SelectedPageIndex="-1"
  TransitionDuration="200"
  TransitionType="FadeInWithSlide">
  <ui:NavigationFluent.Items>
    <ui:NavigationItem
      Cache="True"
      Content="Home"
      Icon="Home24"
      PageTag="dashboard"
      PageType="{x:Type pages:Dashboard}" />
    <ui:NavigationSeparator />
  </ui:NavigationFluent.Items>
  <ui:NavigationFluent.Footer>
    <ui:NavigationItem
      Click="NavigationButtonTheme_OnClick"
      Content="Theme"
      Icon="DarkTheme24" />
  </ui:NavigationFluent.Footer>
</ui:NavigationFluent>

<ui:NavigationCompact
  Frame="{Binding ElementName=RootFrame}"
  Precache="False"
  SelectedPageIndex="-1"
  TransitionDuration="200"
  TransitionType="FadeInWithSlide">
  <ui:NavigationCompact.Items>
    <ui:NavigationItem
      Cache="True"
      Content="Home"
      Icon="Home24"
      PageTag="dashboard"
      PageType="{x:Type pages:Dashboard}" />
    <ui:NavigationSeparator />
  </ui:NavigationCompact.Items>
  <ui:NavigationCompact.Footer>
    <ui:NavigationItem
      Click="NavigationButtonTheme_OnClick"
      Content="Theme"
      Icon="DarkTheme24" />
  </ui:NavigationCompact.Footer>
</ui:NavigationCompact>

Titlebar Copy Section

The titlebar control has been rewritten yet again, making it almost completely incompatible.

Migration V3 Migration (`docs/migration/v3-migration.md`) Copy Section

Migration plan

This page outlines key changes and important details to consider when migrating. It highlights what’s new, what’s changed, and any steps you need to take to ensure a smooth transition. This isn’t a full step-by-step guide but a quick reference to help you navigate the most critical parts of the migration process.

Navigation Copy Chapter

All navigation controls have been merged into one NavigationView, inspired by Win UI.

Icons Copy Chapter

All icons are based on the new IconElement control. They replaced icons in TitleBar, NavigationView, Button and other controls.

Control Gallery Copy Chapter

Inspired by Win UI Controls Gallery, a new application for testing and browsing controls was created -** WPF UI Gallery**. It replaced the Demo app.

Dialogs Copy Chapter

ContentDialog, MessageBox and Snackbar have been modified, their interfaces are not fully compatible.

Migration V4 Migration (`docs/migration/v4-migration.md`) Copy Section

Migration plan

This page outlines key changes and important details to consider when migrating. It highlights what’s new, what’s changed, and any steps you need to take to ensure a smooth transition. This isn’t a full step-by-step guide but a quick reference to help you navigate the most critical parts of the migration process.

Abstractions package Copy Chapter

Some WPF UI interfaces have been moved to a standalone package WPF-UI.Abstractions. You don't need to reference it, it will always be added automatically with WPF-UI NuGet package.

Navigation interfaces Copy Chapter

Navigation interfaces have been moved to a standalone WPF-UI.Abstractions package. This way, if you have models, views or other business services in another project, not related to WPF, you can develop them together for multiple applications.

New namespaces Copy Section

INavigationAware and INavigableView have beed moved to Wpf.Ui.Abstractions.Controls namespace.

Dependency injection based page creation Copy Section

IPageService have been renamed to INavigationViewPageProvider.

Its default implementation is in the new Wpf.Ui.DependencyInjection package. You just need to use the services.AddNavigationViewPageProvider() extension and then indicate in the navigation that you want to use this interface. Then NavigationView will use DI container for pages creation.

Program.cs

var builder = Host.CreateDefaultBuilder();
builder.Services.AddNavigationViewPageProvider();

MyWindow.xaml.cs

var pageProvider = serviceProvider.GetRequiredService<INavigationViewPageProvider>();

// NavigationControl is x:Name of our NavigationView defined in XAML.
NavigationControl.SetPageProviderService(pageProvider)

Navigation service Copy Section

The INavigationService defined in the main package (WPF-UI) makes navigation management easy. You can use it for convenient injection between view models. We HIGHLY recommend it to be Singleton.

var builder = Host.CreateDefaultBuilder();
builder.Services.AddNavigationViewPageProvider();
builder.Services.AddSingleton<INavigationService, NavigationService>();

Templates .Stylelintrc.Json (`docs/templates/.stylelintrc.json`) Copy Section

{
"extends": "stylelint-config-standard-scss",
"ignoreFiles": [
"**/*.ts"
],
"rules": {
"selector-class-pattern": null,
"font-family-no-missing-generic-family-keyword": [ true, {
"ignoreFontFamilies": [
"bootstrap-icons"
]
}]
}
}

Templates Package.Json (`docs/templates/package.json`) Copy Section

{
"name": "@docfx/template",
"version": "1.0.0",
"description": "Docfx static website templates",
"keywords": [
"docfx",
"template"
],
"author": "docfx",
"license": "MIT",
"browserslist": [
"defaults"
],
"scripts": {
"build": "node build.js",
"lint": "eslint wpfui/src && stylelint wpfui/src"
},
"dependencies": {
"@default/anchor-js": "npm:[email protected]",
"@default/bootstrap": "npm:[email protected]",
"@default/highlight.js": "npm:[email protected]",
"@default/lunr": "npm:[email protected]",
"@default/mark.js": "npm:[email protected]",
"@default/twbs-pagination": "josecebe/twbs-pagination#1.3.1",
"@default/url": "npm:@websanova/[email protected]",
"@websanova/url": "^2.6.3",
"anchor-js": "^5.0.0",
"bootstrap": "^5.3.1",
"bootstrap-icons": "^1.10.5",
"highlight.js": "^11.8.0",
"jquery": "3.7.0",
"lit-html": "^2.8.0",
"lunr": "2.3.9",
"mathjax": "^3.2.2",
"mermaid": "^10.3.0"
},
"devDependencies": {
"@types/jest": "^29.5.3",
"@typescript-eslint/eslint-plugin": "^6.2.1",
"@typescript-eslint/parser": "^6.2.1",
"browser-sync": "^2.29.3",
"esbuild": "~0.18.17",
"esbuild-sass-plugin": "~2.10.0",
"eslint": "^8.46.0",
"eslint-config-standard": "^17.1.0",
"jest": "^29.6.2",
"stylelint": "^15.10.2",
"stylelint-config-standard-scss": "^10.0.0",
"ts-jest": "^29.1.1",
"typescript": "^5.1.6",
"yargs": "^17.7.2"
}
}

Templates Tsconfig.Json (`docs/templates/tsconfig.json`) Copy Section

{
"compilerOptions": {
"removeComments": true,
"resolveJsonModule": true,
"esModuleInterop": true
}
}

Architecture Cross Cutting Navigation (`docs/architecture/cross-cutting/navigation.md`) Copy Section

Navigation System

WPF UI v4.2.0 | Cross-Cutting Concern

Overview Copy Chapter

The WPF UI navigation system provides page-based navigation within NavigationView, with support for page caching, back stack management, transition animations, and lifecycle callbacks. It integrates with Microsoft.Extensions.DependencyInjection for type-based page resolution.

Navigation Lifecycle Copy Chapter

The following sequence diagram shows the complete flow from a NavigationService.Navigate() call through to the page being displayed with transition animations.

/* Detailed source-code truncated for AI context efficiency. */

Page Cache Mode Copy Chapter

NavigationView supports three caching strategies via the NavigationCacheMode property on individual pages. The cache is maintained per-type within the INavigationViewPageProvider implementation.

stateDiagram-v2
    [*] --> PageRequested: Navigate(pageType)

    state PageRequested {
        [*] --> CheckCacheMode

        state CheckCacheMode <<choice>>
        CheckCacheMode --> CacheDisabled: Disabled
        CheckCacheMode --> CacheEnabled: Enabled
        CheckCacheMode --> CacheRequired: Required

        state CacheDisabled {
            [*] --> CreateNew_D: Always create new instance
            CreateNew_D --> ReturnPage_D: Return new page
        }

        state CacheEnabled {
            [*] --> LookupCache_E: Check cache
            LookupCache_E --> ReturnCached_E: Cache hit
            LookupCache_E --> CreateAndCache_E: Cache miss
            CreateAndCache_E --> ReturnPage_E: Store and return
            ReturnCached_E --> ReturnPage_E: Return cached
        }

        state CacheRequired {
            [*] --> LookupCache_R: Check cache
            LookupCache_R --> ReturnCached_R: Cache hit (guaranteed after first)
            LookupCache_R --> CreateAndCache_R: First request only
            CreateAndCache_R --> ReturnPage_R: Store and return
            ReturnCached_R --> ReturnPage_R: Return cached
        }
    }

    PageRequested --> PageDisplayed: Page resolved
    PageDisplayed --> [*]

Cache Mode Comparison Copy Section

Key Components Copy Chapter

NavigationService Copy Section

Thin wrapper around INavigationView that provides a service-oriented API for navigation. Registered in DI as INavigationService.

Key methods:

• Navigate(Type pageType) — Navigate to a page by type
• Navigate(string pageTag) — Navigate to a page by tag
• GoBack() — Navigate to the previous page in the back stack
• SetNavigationControl(INavigationView) — Bind to a NavigationView instance

INavigationViewPageProvider Copy Section

Abstraction for page instance resolution. Two implementations:

1. DependencyInjectionNavigationViewPageProvider (from Wpf.Ui.DependencyInjection) — resolves pages via IServiceProvider
2. Manual/custom — consumers can implement their own provider

INavigationAware Copy Section

Lifecycle interface for pages that need to respond to navigation events:

• OnNavigatedTo() — Called when the page becomes the active view
• OnNavigatedFrom() — Called when the page is navigated away from

Transition Animations Copy Section

TransitionAnimationProvider applies entry animations to navigated pages. Available transitions: FadeIn, FadeInFromBottom, SlideFromBottom, SlideFromRight, SlideFromLeft. Animations are skipped when HardwareAcceleration.RenderingTier < 2.

Integration with DI Copy Chapter

For hosted applications using Microsoft.Extensions.Hosting:

// In Program.cs or Startup
services.AddNavigationViewPageProvider<DependencyInjectionNavigationViewPageProvider>();
services.AddSingleton<INavigationService, NavigationService>();

// Pages registered in DI
services.AddTransient<DashboardPage>();
services.AddTransient<SettingsPage>();

The DependencyInjectionNavigationViewPageProvider resolves pages from the DI container, respecting their registered lifetime (Transient, Scoped, Singleton).

Back Stack Copy Chapter

NavigationView maintains an internal back stack of previously visited page types. The GoBack() operation pops the most recent entry and navigates to it. The back stack is cleared when navigating to a page that is already in the stack (cycle prevention).

Design Considerations Copy Chapter

• Static vs DI navigation: Simple apps can use NavigationService directly; hosted apps use DI. Both paths are supported.
• Cache ownership: The page cache lives in INavigationViewPageProvider, not in NavigationView. This allows DI-managed lifetimes to control cache behavior.
• Animation gating: Transition animations check rendering tier to avoid jank on software-rendered systems.
• Thread safety: Navigation must occur on the UI thread. NavigationService does not marshal calls.

Architecture Cross Cutting Testing (`docs/architecture/cross-cutting/testing.md`) Copy Section

Cross-Cutting Concern: Testing

Project: WPF UI (wpfui) v4.2.0
Last Updated: 2026-02-10

Overview Copy Chapter

WPF UI employs a two-tier testing strategy consisting of unit tests for isolated logic verification and integration tests for end-to-end UI automation. The testing infrastructure is intentionally lightweight, reflecting the library's nature as a visual control library where many behaviors require a running WPF application to validate.

Test Pyramid Copy Chapter

/  Integration Tests  \        8 tests
          /  (FlaUI + Gallery App) \      End-to-end UI automation
         /________________________\
        /                          \
       /      Unit Tests            \     6 tests
      /  (XUnit + NSubstitute)       \    Isolated logic, pure functions
     /________________________________\

Test Framework Versions Copy Chapter

All versions are managed centrally in Directory.Packages.props:

Test Naming Conventions Copy Chapter

Unit Tests Copy Section

Pattern: MethodName_ExpectedResult_WhenCondition

[Fact]
public void ApplyTransition_ReturnsFalse_WhenDurationIsLessThan10()

Alternative pattern: GivenX_Method_ExpectedResult

[Fact]
public void GivenAllRegularSymbols_Swap_ReturnsValidFilledSymbol()

Integration Tests Copy Section

Pattern: Subject_ShouldExpectedBehavior_WhenCondition

[Fact]
public async Task CloseButton_ShouldCloseWindow_WhenClicked()

Class Naming Copy Section

• Unit test classes: {ClassUnderTest}Tests (e.g., TransitionAnimationProviderTests)
• Integration test classes: {Feature}Tests (e.g., TitleBarTests, NavigationTests)
• Integration test classes are sealed; unit test classes are not

Test Directory Structure Copy Chapter

graph TD
    A["tests/"] --> B["Wpf.Ui.UnitTests/"]
    A --> C["Wpf.Ui.Gallery.IntegrationTests/"]

    B --> B1["Wpf.Ui.UnitTests.csproj<br/><i>net10.0-windows</i>"]
    B --> B2["Animations/"]
    B --> B3["Extensions/"]
    B --> B4["GlobalUsings.cs"]
    B2 --> B2a["TransitionAnimationProviderTests.cs"]
    B3 --> B3a["SymbolExtensionsTests.cs"]

    C --> C1["Wpf.Ui.Gallery.IntegrationTests.csproj<br/><i>net10.0-windows10.0.26100.0</i>"]
    C --> C2["Fixtures/"]
    C --> C3["WindowTests.cs"]
    C --> C4["TitleBarTests.cs"]
    C --> C5["NavigationTests.cs"]
    C --> C6["ContentDialogAutomationTests.cs"]
    C --> C7["xunit.runner.json"]
    C2 --> C2a["UiTest.cs <i>(base class)</i>"]
    C2 --> C2b["TestedApplication.cs <i>(app lifecycle)</i>"]

    D["src/Wpf.Ui.FlaUI/"] --> D1["AutoSuggestBox.cs<br/><i>Custom FlaUI element</i>"]

    style A fill:#f5f5f5,stroke:#333
    style B fill:#e3f2fd,stroke:#1565c0
    style C fill:#e8f5e9,stroke:#2e7d32
    style D fill:#fff3e0,stroke:#e65100

Test Infrastructure Copy Chapter

Unit Tests Copy Section

Unit tests reference the core Wpf.Ui project directly and use NSubstitute for mocking WPF types (e.g., UIElement). Global usings are defined for common namespaces:

System, System.Windows, NSubstitute, Xunit

Source: tests/Wpf.Ui.UnitTests/GlobalUsings.cs

Integration Tests Copy Section

Integration tests use a custom infrastructure built on FlaUI:

• TestedApplication (IAsyncLifetime): Launches and manages the Gallery .exe process. Finds the executable in the test output directory. Uses UIA3Automation for UI element discovery.
• UiTest (abstract base class, IAsyncLifetime): Provides helper methods for all UI tests:
  • FindFirst(string automationId) -- finds UI elements by automation ID
  • FindFirst(Func<ConditionFactory, ConditionBase>) -- finds by condition
  • Wait(int seconds) -- async delay for UI settling
  • Enter(string value) -- simulates keyboard text input
  • Press(VirtualKeyShort) -- simulates a key press

Integration Test Runner Configuration Copy Section

Tests run sequentially (no parallel test collections) with invariant culture:

{
  "parallelizeTestCollections": false,
  "diagnosticMessages": true,
  "culture": "invariant"
}

Source: tests/Wpf.Ui.Gallery.IntegrationTests/xunit.runner.json

Run Commands Copy Chapter

# Run unit tests
dotnet test tests/Wpf.Ui.UnitTests/Wpf.Ui.UnitTests.csproj

# Run integration tests (requires built Gallery app)
dotnet test tests/Wpf.Ui.Gallery.IntegrationTests/Wpf.Ui.Gallery.IntegrationTests.csproj

# Run all tests with coverage
dotnet test tests/Wpf.Ui.UnitTests/Wpf.Ui.UnitTests.csproj --collect:"XPlat Code Coverage"

Coverage Gaps and Observations Copy Chapter

CI/CD Integration Copy Chapter

The PR validation workflow (.github/workflows/wpf-ui-pr-validator.yaml) currently only builds the Gallery app in Release mode. It does not run unit or integration tests as part of PR checks. Test execution is a local development responsibility.

Architecture Cross Cutting Theming And Appearance (`docs/architecture/cross-cutting/theming-and-appearance.md`) Copy Section

Theming and Appearance System

Overview Copy Chapter

The WPF UI library implements a comprehensive theming system that supports Light, Dark, and four high-contrast themes. The system automatically synchronizes with OS theme changes, manages accent colors, and provides window backdrop effects (Mica, Acrylic, Tabbed).

Architecture Components Copy Chapter

Core Manager Classes Copy Section

ApplicationThemeManager

Location: src/Wpf.Ui/Appearance/ApplicationThemeManager.cs

Static class responsible for applying and managing application themes. Key functionality:

• Apply(ApplicationTheme theme) - Swaps theme resource dictionaries at runtime
• GetAppTheme() - Retrieves current application theme
• Changed event - ThemeChangedEvent delegate fires when theme changes globally

The manager uses URI-based resource dictionary swapping, searching application-level merged dictionaries for URIs containing 'wpf.ui;' and 'theme', then replacing them with the appropriate theme file.

ApplicationAccentColorManager

Location: src/Wpf.Ui/Appearance/ApplicationAccentColorManager.cs

Static class for accent color management:

• Apply(Color systemAccent, ApplicationTheme theme) - Updates 20+ dynamic color resources
• GetColorizationColor() - Retrieves system accent color
• ApplySystemAccent() - Applies Windows system accent colors

Uses WinRT IUISettings3 COM interface to retrieve system accent colors (Accent, AccentLight1-3, AccentDark1-3) with registry fallback to DWM AccentColor.

Dynamic Resources Updated:

• SystemAccentColor
• AccentFillColorDefault
• TextOnAccentFillColorPrimary
• AccentFillColorSecondary
• AccentFillColorTertiary
• (20+ total accent-related resources)

SystemThemeWatcher

Location: src/Wpf.Ui/Appearance/SystemThemeWatcher.cs

Static class providing automatic OS theme synchronization:

• Watch(Window window) - Hooks window to auto-sync theme with OS
• UnWatch(Window window) - Removes synchronization hook

Implementation uses WndProc message interception via HwndSource to listen for:

• WM_DWMCOLORIZATIONCOLORCHANGED
• WM_THEMECHANGED
• WM_SYSCOLORCHANGE

When detected, triggers ApplicationThemeManager.ApplySystemTheme().

WindowBackgroundManager

Location: src/Wpf.Ui/Appearance/WindowBackgroundManager.cs

Static class for window appearance management:

• UpdateBackground(Window? window, ApplicationTheme applicationTheme, WindowBackdropType backdrop) - Applies dark mode and backdrop effects
• Manages WindowBackdrop effects (Mica, Acrylic, Tabbed)
• Applies DWM window attributes for Windows 11+ visual effects

ResourceDictionaryManager

Location: src/Wpf.Ui/Appearance/ResourceDictionaryManager.cs

Internal helper class for resource dictionary manipulation:

• Finds resource dictionaries by namespace/name matching
• Swaps resource dictionaries by URI pattern
• Handles Application.Current.Resources.MergedDictionaries traversal

Theme Files Copy Chapter

Six XAML resource dictionaries located in src/Wpf.Ui/Resources/Theme/:

1. Light.xaml - Light theme color scheme
2. Dark.xaml - Dark theme color scheme
3. HC1.xaml - High contrast theme variant 1
4. HC2.xaml - High contrast theme variant 2
5. HCBlack.xaml - High contrast black theme
6. HCWhite.xaml - High contrast white theme

Supporting Resources Copy Section

Located in src/Wpf.Ui/Resources/ (parent directory, not the Theme/ subdirectory):

• Accent.xaml - Accent color definitions
• Palette.xaml - Color palette system
• StaticColors.xaml - Static color values
• Variables.xaml - Theme variables

Accent Color System Copy Chapter

The accent color system provides dynamic, theme-aware colors derived from Windows system settings:

Color Hierarchy Copy Section

System Accent Color (from WinRT UISettings)
  ├── Primary Accent (direct system color)
  ├── Secondary Accent (lighter/darker variant)
  └── Tertiary Accent (additional variant)

WinRT Integration Copy Section

// Retrieves colors via WinRT IUISettings3 COM interface
var uiSettings = new Windows.UI.ViewManagement.UISettings();
var accent = uiSettings.GetColorValue(UIColorType.Accent);
var accentLight1 = uiSettings.GetColorValue(UIColorType.AccentLight1);
var accentDark1 = uiSettings.GetColorValue(UIColorType.AccentDark1);

WindowBackdrop Effects Copy Chapter

Three backdrop effect types available via WindowBackdropType enum:

Mica Copy Section

Windows 11+ translucent backdrop with desktop wallpaper bleed-through. Applied via DwmSetWindowAttribute with DWMWA_SYSTEMBACKDROP_TYPE.

Acrylic Copy Section

Translucent acrylic material effect with blur. Requires Windows 10 Fall Creators Update or later.

Tabbed Copy Section

Windows 11 tabbed window effect grouping windows in the taskbar.

Implementation Copy Section

Effects are applied through DWM (Desktop Window Manager) APIs in WindowBackgroundManager and consumed by FluentWindow control.

Theme Change Flow Copy Chapter

sequenceDiagram
    participant User
    participant App
    participant SystemThemeWatcher
    participant WndProc
    participant ApplicationThemeManager
    participant ResourceDictionaryManager
    participant UI

    User->>App: Change OS Theme
    WndProc->>SystemThemeWatcher: WM_THEMECHANGED
    SystemThemeWatcher->>ApplicationThemeManager: ApplySystemTheme()
    ApplicationThemeManager->>ApplicationThemeManager: GetSystemTheme()
    ApplicationThemeManager->>ResourceDictionaryManager: UpdateDictionary("theme", newUri)
    ResourceDictionaryManager->>UI: Swap Theme XAML
    ApplicationThemeManager->>ApplicationThemeManager: Fire Changed Event
    ApplicationThemeManager->>UI: Trigger Visual Update
    UI->>User: Updated Appearance

Usage Examples Copy Chapter

Basic Theme Application Copy Section

// Apply dark theme
ApplicationThemeManager.Apply(ApplicationTheme.Dark);

// Get current theme
ApplicationTheme current = ApplicationThemeManager.GetAppTheme();

Automatic OS Synchronization Copy Section

public MainWindow()
{
    InitializeComponent();

    // Enable automatic theme synchronization
    Appearance.SystemThemeWatcher.Watch(this);
}

Custom Accent Color Copy Section

// Apply custom accent color
Color myAccent = Color.FromRgb(0, 120, 215);
ApplicationAccentColorManager.Apply(
    myAccent,
    ApplicationTheme.Dark,
    systemGlassColor: false,
    systemAccentColor: true
);

XAML Theme Selection Copy Section

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            
            <ui:ThemesDictionary Theme="Dark" />
            <ui:ControlsDictionary />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

Design Considerations Copy Chapter

Static Singleton Pattern Copy Section

The theme managers use static class design for simple, globally-accessible APIs. This pattern trades testability for API simplicity and ensures single-instance theme state across the application.

Runtime Resource Swapping Copy Section

Theme changes occur via runtime resource dictionary replacement rather than restart-required configuration. This enables live theme switching without application restart.

OS Integration Copy Section

Deep integration with Windows theme system via WndProc message hooks and WinRT UISettings ensures automatic synchronization with user preferences.

Multi-Version Support Copy Section

Theme system gracefully degrades on older Windows versions, falling back to registry-based accent color detection when WinRT APIs are unavailable.

Architecture Cross Cutting Win32 Interop (`docs/architecture/cross-cutting/win32-interop.md`) Copy Section

Win32 Interop Architecture

WPF UI v4.2.0 | Cross-Cutting Concern

Overview Copy Chapter

WPF UI relies heavily on Win32 interop to deliver Fluent Design features that are not natively available through the WPF framework. This includes DWM backdrop effects (Mica, Acrylic, Tabbed), dark mode title bars, window corner preferences, snap layout support, system tray icons, and taskbar progress indicators.

The interop layer follows a strict three-layer architecture that isolates raw platform calls from the rest of the library.

Component Diagram Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Three-Layer Architecture Copy Chapter

Layer 1: CsWin32 Source Generation Copy Section

The project uses Microsoft's CsWin32 source generator to produce type-safe P/Invoke bindings at compile time.

• Configuration: NativeMethods.txt lists the Win32 functions and types needed by the library.
• Generated namespace: Windows.Win32
• Foundation types: HWND, HRESULT, BOOL from Windows.Win32.Foundation

Key generated functions:

Layer 2: Managed Wrappers (`src/Wpf.Ui/Interop/`) Copy Section

Managed wrappers provide validated, exception-safe access to native APIs.

`UnsafeNativeMethods.cs` -- Handle-Validated Wrappers

Every method follows a defensive pattern:

1. Check that the handle is not IntPtr.Zero
2. Verify the handle via PInvoke.IsWindow()
3. Call the native API
4. Catch any exception and return false or null

This pattern ensures that callers never receive unmanaged exceptions and that invalid window handles are rejected before reaching the OS.

`UnsafeReflection.cs` -- Unsafe Enum/Struct Casting

Provides unsafe casting between managed enums/structs and their Win32 equivalents. Used where direct marshalling is insufficient or where performance-critical paths avoid boxing.

`PInvoke.cs` -- Custom P/Invoke Declarations

Contains hand-written P/Invoke declarations for functions that CsWin32 does not generate or generates with incompatible signatures. Example: SetWindowLongPtrW requires platform-specific handling (different entry points on 32-bit vs 64-bit Windows).

Layer 3: Utilities (`src/Wpf.Ui/Win32/`) Copy Section

`Utilities.cs` -- OS Version Detection

Provides high-level queries about the running environment:

These checks gate feature availability so that controls degrade gracefully on older Windows versions.

API Surface by Windows Component Copy Chapter

Interop Call Flow Copy Chapter

The following diagram illustrates the typical call path from a consumer application through the interop layers to the Windows OS.

sequenceDiagram
    participant App as Consumer App
    participant Control as WPF UI Control
    participant Unsafe as UnsafeNativeMethods
    participant CsWin32 as CsWin32 PInvoke
    participant OS as Windows OS

    App->>Control: Set property (e.g., WindowBackdropType = Mica)
    Control->>Control: Validate state and OS version
    Control->>Unsafe: Call managed wrapper (e.g., ApplyWindowDarkMode)

    Unsafe->>Unsafe: Check handle != IntPtr.Zero
    Unsafe->>CsWin32: PInvoke.IsWindow(hwnd)
    CsWin32->>OS: IsWindow()
    OS-->>CsWin32: BOOL result
    CsWin32-->>Unsafe: true/false

    alt Handle is valid
        Unsafe->>CsWin32: DwmSetWindowAttribute(hwnd, attr, value)
        CsWin32->>OS: DwmSetWindowAttribute()
        OS-->>CsWin32: HRESULT
        CsWin32-->>Unsafe: success/failure
        Unsafe-->>Control: true
    else Handle is invalid or call fails
        Unsafe-->>Control: false (exception swallowed)
    end

    Control-->>App: Property applied (or silently degraded)

Error Handling Pattern Copy Chapter

The Win32 interop layer follows a deliberate error-swallowing strategy:

1. Bare catch blocks are intentional. Win32 APIs may fail unpredictably across OS versions, and there is no reliable way to enumerate all failure modes at compile time. Swallowing exceptions ensures the application continues to function, albeit without the requested visual effect.

2. Graceful degradation is the design goal. If a Mica backdrop cannot be applied (e.g., on Windows 10), the window falls back to a solid background. No exception propagates to the consumer.

3. Handle validation is mandatory. Every wrapper method must validate that the HWND is non-zero and represents a valid window before calling any native API. This prevents access violations from stale or recycled handles.

4. Return values signal success. Methods return bool (success/failure) or nullable types rather than throwing. Callers check return values to determine whether the native operation succeeded.

Pattern:
  if (handle == IntPtr.Zero) return false;
  if (!PInvoke.IsWindow(handle)) return false;
  try {
      NativeCall(handle, ...);
      return true;
  } catch {
      return false;
  }

Platform Considerations Copy Chapter

• 32-bit vs 64-bit: SetWindowLongPtr does not exist as a distinct entry point on 32-bit Windows. The custom PInvoke.cs handles this by routing to SetWindowLong on x86 and SetWindowLongPtrW on x64.
• Windows 10 vs 11: Many DWM attributes (e.g., DWMWA_SYSTEMBACKDROP_TYPE) are only available on Windows 11 (build 22000+). The Utilities class gates these calls.
• COM activation: ITaskbarList4 and IUISettings3 require COM activation. These are wrapped to handle COMException gracefully.

Architecture Decisions ADR 001 Multi Target Framework (`docs/architecture/decisions/ADR-001-multi-target-framework.md`) Copy Section

ADR-001: Multi-Target Framework Support

Status Copy Chapter

Accepted

Context Copy Chapter

The WPF UI library needs to support a wide range of .NET implementations to maximize compatibility with existing projects while leveraging modern .NET features where available.

Supported Frameworks Copy Section

• .NET 10, 9, 8 - Modern .NET with Windows-specific APIs
• .NET Framework 4.8.1, 4.7.2, 4.6.2 - Legacy enterprise applications
• .NET Standard 2.0, 2.1 - Abstractions library only (maximizes compatibility)

Decision Copy Chapter

Core Library (Wpf.Ui) Copy Section

Target frameworks: net10.0-windows;net9.0-windows;net8.0-windows;net481;net472;net462

Rationale:

• Windows-specific project requires -windows TFM suffix for .NET 5+
• .NET Framework support ensures compatibility with legacy WPF applications
• Multi-version .NET support provides upgrade path for consumers

Abstractions Library (Wpf.Ui.Abstractions) Copy Section

Target frameworks: net10.0;net9.0;net8.0;net462;netstandard2.1;netstandard2.0

Rationale:

• No WPF dependencies allows broader compatibility
• .NET Standard 2.0 enables use in class libraries shared between .NET Framework and .NET Core/5+
• AOT-compatible (aot_compatible: true) for modern deployment scenarios

DI Integration (Wpf.Ui.DependencyInjection) Copy Section

Target frameworks: Same as Abstractions

Rationale:

• Depends only on Microsoft.Extensions.DependencyInjection.Abstractions (version 3.1.0 for broad compatibility)
• No WPF dependencies
• Enables DI integration in non-WPF contexts (e.g., background services)

Central Package Management Copy Chapter

All package versions are managed in Directory.Packages.props:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    
    <PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.242" />
    <PackageVersion Include="System.Memory" Version="4.6.3" />
  </ItemGroup>
</Project>

Individual projects reference packages without version attributes:

<PackageReference Include="Microsoft.Windows.CsWin32" />

Benefits:

• Single source of truth for package versions
• Prevents version conflicts across projects
• Simplifies dependency updates

Conditional Compilation Copy Chapter

Framework Detection Copy Section

#if NET5_0_OR_GREATER
    // Modern .NET APIs (Environment.OSVersion)
#else
    // .NET Framework fallback (registry)
#endif

#if NET6_0_OR_GREATER
    // DisposeAsync for CancellationTokenRegistration
#endif

#if NET8_0_OR_GREATER
    // Latest .NET 8+ features
#endif

Framework-Specific Dependencies Copy Section

<PackageReference Include="System.ValueTuple" Condition="'$(TargetFramework)' == 'net462'" />


<PackageReference Include="System.Drawing.Common" Condition="'$(TargetFramework)' != 'net462'" />

PolySharp Integration Copy Chapter

Package: PolySharp (build-time source generator)

Provides polyfills for newer C# features on older target frameworks:

• C# 11+ features on .NET 6/7/8
• C# 12+ features on older .NET versions

Configuration:

<ItemGroup>
  <CompilerVisibleProperty Include="PolySharpExcludeGeneratedTypes" />
</ItemGroup>

<PropertyGroup>
  
  <PolySharpExcludeGeneratedTypes>
    System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute;
    System.Diagnostics.CodeAnalysis.UnscopedRefAttribute
  </PolySharpExcludeGeneratedTypes>
</PropertyGroup>

Benefits:

• Use modern C# syntax across all target frameworks
• Init-only properties on .NET Framework
• Required members support
• CallerArgumentExpression on older frameworks

Language Version Copy Chapter

Set to C# 14.0 across all projects:

<LangVersion>14.0</LangVersion>

Note: Wpf.Ui.csproj overrides this to <LangVersion>preview</LangVersion> to enable C# preview features.

Combined with PolySharp, this enables:

• Latest C# language features
• Polyfills generated at compile-time for older frameworks
• No runtime dependencies

Enforcement Copy Chapter

MUST Follow Copy Section

1. All package versions in Directory.Packages.props only — Central Package Management is the single source of truth for NuGet versions
2. Use -windows TFM suffix for projects with WPF dependencies (e.g., net10.0-windows, not net10.0)
3. Use netstandard2.0/netstandard2.1 for abstraction-only packages that have no WPF or Windows dependency
4. Guard framework-specific code with #if NET{X}_0_OR_GREATER directives — never use runtime version checks for compile-time API differences
5. Use PolySharp for C# polyfills — never hand-write polyfill classes for language features (e.g., IsExternalInit, CallerArgumentExpression)
6. Set LangVersion in Directory.Build.props — override in individual .csproj only when justified (currently only Wpf.Ui.csproj overrides to preview)

MUST NOT Do Copy Section

1. Never add Version attribute to PackageReference in .csproj files — all versions must be in Directory.Packages.props
2. Never add a new TFM without updating all projects that share the same TFM set — all projects in a TFM group must stay in sync
3. Never use #if with specific patch versions (e.g., NET8_0_10) — only use _OR_GREATER suffixed symbols
4. Never remove a TFM from a shipping package without a major version bump — removing a TFM is a breaking change for consumers on that framework

Verification Copy Section

• CPM enforcement: <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> in Directory.Build.props causes build errors if Version is specified in .csproj
• TFM validation: Build compiles all target frameworks on every dotnet build — missing APIs surface as compile errors immediately
• PolySharp coverage: PolySharp source generator runs at build time and provides polyfills automatically; manual polyfills would cause duplicate symbol errors

Consequences Copy Chapter

Positive Copy Section

• Broad Compatibility: Supports applications from .NET Framework 4.6.2 through .NET 10
• Modern Development: C# 14 preview features via PolySharp
• Simplified Maintenance: Central package management
• Clear Upgrade Path: Consumers can upgrade .NET version without changing library
• AOT Ready: Abstractions library supports AOT scenarios

Negative Copy Section

• Increased Build Complexity: Each commit builds 6+ framework variants
• Larger Package Size: Multi-target packages include assemblies for all frameworks
• Conditional Compilation: Requires #if directives for framework-specific code
• Testing Burden: Features should be tested on multiple framework versions

Implementation Details Copy Chapter

Directory.Build.props Copy Section

Central build properties defined once:

<PropertyGroup>
  <Version>4.2.0</Version>
  <LangVersion>14.0</LangVersion>
  <Nullable>enable</Nullable>
  <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Conditional Property Groups Copy Section

<PropertyGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
  <DefineConstants>$(DefineConstants);NET8_0_OR_GREATER</DefineConstants>
</PropertyGroup>

<PropertyGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
  <DefineConstants>$(DefineConstants);BELOW_NET8</DefineConstants>
</PropertyGroup>

References Copy Chapter

• .NET Multi-Targeting Documentation
• Central Package Management
• PolySharp GitHub
• TFM Compatibility

Architecture Decisions ADR 002 Control Library Architecture (`docs/architecture/decisions/ADR-002-control-library-architecture.md`) Copy Section

ADR-002: Control Library Architecture

Status Copy Chapter

Accepted

Context Copy Chapter

The WPF UI library provides 77+ Fluent Design System controls. The architecture must support:

• Clear code organization
• XAML implicit styling
• Type-safe intellisense
• Easy discovery for developers
• Maintainable codebase at scale

Decision Copy Chapter

Folder-Per-Control Structure Copy Section

Each control resides in its own subfolder under src/Wpf.Ui/Controls/{ControlName}/:

Controls/
├── Button/
│   ├── Button.cs              # Control class
│   └── Button.xaml            # Implicit style ResourceDictionary
├── NavigationView/
│   ├── NavigationView.Base.cs         # Core logic
│   ├── NavigationView.Properties.cs   # Dependency properties
│   ├── NavigationView.Events.cs       # Routed events
│   ├── NavigationView.Navigation.cs   # Navigation logic
│   ├── NavigationView.TemplateParts.cs # Template part bindings
│   ├── NavigationView.AttachedProperties.cs
│   └── NavigationView.xaml            # Implicit style
└── ContentDialog/
    ├── ContentDialog.cs
    ├── ContentDialog.FocusBehavior.cs  # Focused concern
    ├── ContentDialogHost.cs            # Host control
    ├── ContentDialogHostBehavior.cs
    ├── EventArgs/                      # Supporting types
    └── ContentDialog.xaml

Benefits:

• Physical isolation prevents coupling between controls
• Easy to locate all files related to a control
• Supports partial class decomposition for complex controls
• Clear ownership boundaries

Paired .cs + .xaml Files Copy Section