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

Priority	Recommendation	Rationale	Affected
Critical	Add unit tests for core controls, targeting at least NavigationView, TitleBar, FluentWindow, ContentDialog, NumberBox, and ToggleSwitch.	Only 6 unit tests exist for a 77+ control library. Regressions ship undetected.	`src/Wpf.Ui/Controls/`, `tests/Wpf.Ui.UnitTests/`
Critical	Enable test execution in the PR validator CI workflow.	The current workflow builds the Gallery app but never runs tests. Merging broken code is possible.	`.github/workflows/`
High	Add integration tests for NavigationView page caching and lifecycle transitions.	Caching behavior is undocumented and untested. Users report inconsistent state across navigation.	`src/Wpf.Ui/Controls/NavigationView/`
Medium	Add contract tests for `INavigationService`, `IContentDialogService`, and `ISnackbarService`.	Service interfaces are the primary public API surface for DI consumers but lack test coverage.	`src/Wpf.Ui.Abstractions/`, `src/Wpf.Ui/Services/`

Priority	Recommendation	Rationale	Affected
High	Wrap static theme managers (`ApplicationThemeManager`, `ApplicationAccentColorManager`) with injectable service interfaces.	Static managers cannot be mocked or unit tested. `IThemeService` exists but the underlying managers remain untestable.	`src/Wpf.Ui/Appearance/`
High	Document NavigationView page caching strategy: when pages are created, cached, and disposed.	Caching behavior is implicit in the implementation with no documentation or configuration surface.	`src/Wpf.Ui/Controls/NavigationView/`
Medium	Add structured logging (e.g., `ILogger`) to Win32 interop error-handling paths.	Catch blocks intentionally swallow Win32 exceptions but produce no diagnostics. Silent failures make debugging difficult for consumers.	`src/Wpf.Ui/Interop/`, `src/Wpf.Ui/Win32/`

Priority	Recommendation	Rationale	Affected
High	Either implement `Wpf.Ui.ToastNotifications` or remove it from the solution.	The project is a stub with no implementation. It ships as a package that does nothing.	`src/Wpf.Ui.ToastNotifications/`
Medium	Audit and reduce public API surface of Win32/Interop namespaces.	Many P/Invoke declarations are public but intended for internal use only. Exposing raw Win32 types couples consumers to implementation details.	`src/Wpf.Ui/Win32/`, `src/Wpf.Ui/Interop/`
Low	Consolidate resource dictionary loading paths.	`ThemesDictionary` and `ControlsDictionary` have overlapping responsibilities that could confuse consumers.	`src/Wpf.Ui/Resources/`

Priority	Recommendation	Rationale	Affected
Critical	Add a CI job that runs `dotnet test tests/Wpf.Ui.UnitTests/` on every PR.	No tests run in CI. The existing test suite provides zero protection against regressions.	`.github/workflows/`
High	Add code coverage reporting (Coverlet is already configured) and set a minimum threshold.	Coverage tooling is present but never executed. Without a baseline, coverage can only decrease.	`tests/Wpf.Ui.UnitTests/`, `.github/workflows/`
Medium	Add a CI step to run `dotnet csharpier --check .` to enforce formatting.	CSharpier is configured but not enforced in CI. Formatting inconsistencies can slip through review.	`.github/workflows/`

Priority	Recommendation	Rationale	Affected
Medium	Add XML doc `<example>` tags with XAML usage to all public control APIs.	Project conventions require examples, but coverage is inconsistent across the 77+ controls.	`src/Wpf.Ui/Controls/`
Low	Create a process for keeping architecture docs in sync with code changes.	Architecture documentation (generated 2026-02-10) will drift from the implementation without a manual update process or automation.	`docs/architecture/`

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

Source: Testing #1 AC:

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

Source: CI/CD #2 AC:

Source: CI/CD #3 AC:

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)

Source: Architecture #2 AC:

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

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

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

Source: Testing #4 AC: