docs/architecture/README.md
| Property | Value |
|---|---|
| Project | WPF UI (wpfui) |
| Version | 4.2.0 |
| Type | Open-source WPF UI control library |
| License | MIT |
| Language | C# 14 / XAML |
| Platforms | .NET 10/9/8 + .NET Framework 4.6.2/4.7.2/4.8.1 |
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.
| Document | Description |
|---|---|
| C4 Context (Level 1) | System context diagram showing WPF UI in its environment -- consumer applications, Windows OS, distribution channels |
| Logical Architecture | Module dependencies, layer diagram, core library internal component structure, detected patterns |
| Document | Description |
|---|---|
| CONSTITUTION.md | Project constitution -- coding conventions, boundary system (ALWAYS DO / ASK FIRST / NEVER DO), rules files summary |
| IMPLEMENTATION-GUIDE.md | Step-by-step guides for common tasks -- adding controls, services, gallery pages, Win32 interop, theming, testing |
| TESTING-SPEC.md | Testing specification -- frameworks, templates, naming conventions, run commands |
| MODULE-INTERFACES.md | Module interface contracts -- public vs internal API surface per module, dependency rules |
| Document | Description |
|---|---|
| Testing | Test strategy, frameworks, naming conventions, coverage gaps |
| Theming and Appearance | Theme system architecture, accent colors, backdrop effects, theme change flow |
| Win32 Interop | Three-layer interop architecture, key APIs, handle validation, WndProc patterns |
| Navigation | Navigation system lifecycle, page caching strategy, DI integration, transition animations |
| ADR | Decision |
|---|---|
| ADR-001 | Multi-target framework strategy (net10.0 through net462) |
| ADR-002 | WPF control library architecture with Fluent Design |
| ADR-003 | Win32 interop via CsWin32 source generator |
| ADR-004 | Static singleton managers for theming (implicit) |
| ADR-005 | Feature-folder organization for controls (implicit) |
| Document | Description |
|---|---|
| RECOMMENDATIONS.md | Prioritized architectural improvement recommendations |
| UNCERTAINTIES.md | Areas needing further investigation |
| Diagrams Index | Index of all architecture diagrams |
| LikeC4 Diagrams | Interactive C4 diagrams in LikeC4 DSL format |
WPF UI is organized as a set of layered NuGet packages built from a single solution:
INavigationViewPageProvider, INavigationAware, INavigableView<T>). Targets .NET and .NET Standard 2.0/2.1 for maximum portability.WPF-UI).SymbolRegular/SymbolFilled enums from Fluent System Icons font data..cs + .xaml files. Controls extend standard WPF base classes and implement capability interfaces (IAppearanceControl, IIconControl).ApplicationThemeManager. Accent colors derived from system settings via WinRT UISettings or DWM registry.UnsafeNativeMethods), and high-level utilities. Enables DWM backdrop effects, custom window chrome, and system theme detection.mindmap
root((WPF UI 4.2.0))
Languages
C# 14 (LangVersion preview)
XAML
Target Frameworks
.NET 10.0-windows
.NET 9.0-windows
.NET 8.0-windows
.NET Framework 4.8.1
.NET Framework 4.7.2
.NET Framework 4.6.2
.NET Standard 2.0/2.1
Abstractions only
Build & Tooling
MSBuild / dotnet CLI
Central Package Management
Directory.Packages.props
CSharpier formatter
110 char width
Source generators
CsWin32 P/Invoke
PolySharp polyfills
CommunityToolkit.Mvvm
Analyzers
WpfAnalyzers
StyleCop
AsyncFixer
IDisposableAnalyzers
Strong-name signing
lepo.snk
SourceLink
Microsoft.SourceLink.GitHub
Win32 / Native
DWM APIs
Mica / Acrylic / Tabbed backdrops
Window corner preference
Dark mode attribute
User32
SetWindowLong / GetWindowLong
Window message handling
Shell32
System tray icons
Taskbar progress
COM ITaskbarList4
Testing
XUnit v2 / v3
NSubstitute mocking
AwesomeAssertions
FlaUI UI automation
Coverlet coverage
CI/CD
GitHub Actions
PR validator
NuGet publish
VS Extension build
DocFX documentation
NuGet.org distribution
GitHub Pages docs
Design System
Microsoft Fluent Design
Fluent System Icons
Regular + Filled TTF fonts
Theme system
Light / Dark / High Contrast
Accent color system
WinRT UISettings integration
wpfui/
src/
Wpf.Ui/ Core library (NuGet: WPF-UI)
Controls/ 77 control subdirectories
Appearance/ Theme management system
Animations/ Transition animations
Converters/ XAML value converters
Extensions/ Extension methods
Hardware/ DPI and rendering detection
Input/ IRelayCommand pattern
Interop/ Win32 managed wrappers
Markup/ XAML markup extensions
Resources/ Theme dictionaries, fonts
Taskbar/ Taskbar progress COM
Win32/ OS version utilities
Wpf.Ui.Abstractions/ Contracts (multi-target)
Wpf.Ui.DependencyInjection/ MS DI integration
Wpf.Ui.Tray/ System tray support
Wpf.Ui.SyntaxHighlight/ Code display control
Wpf.Ui.ToastNotifications/ Toast notifications (stub)
Wpf.Ui.FlaUI/ FlaUI automation helpers
Wpf.Ui.FontMapper/ Icon enum code generator
Wpf.Ui.Gallery/ Demo/showcase application
Wpf.Ui.Extension/ VS 2022 extension
samples/
Wpf.Ui.Demo.Simple/ Minimal no-DI sample
Wpf.Ui.Demo.Mvvm/ Full MVVM + DI sample
Wpf.Ui.Demo.Console/ .NET Framework 4.7.2 console sample
Wpf.Ui.Demo.Dialogs/ ContentDialog sample
Wpf.Ui.Demo.SetResources.Simple/ Manual resource management sample
tests/
Wpf.Ui.UnitTests/ XUnit unit tests
Wpf.Ui.Gallery.IntegrationTests/ FlaUI integration tests
docs/ DocFX documentation site
.github/ CI/CD workflows, templates