Wpf Ui Shell

Overview

Define the primary shell window, shared resources, and navigation contract for a WPF widget host app.

Constraints

• Target .NET 8

• CommunityToolkit.Mvvm

• ViewModel-first navigation via a custom service

• No Prism, no Frame navigation, no heavy region manager

• Fluent-inspired design system using native WPF styles

• Light/Dark themes via ResourceDictionaries with runtime switching

• Single shell window as primary host; secondary windows for widgets/tools/dialogs

Definition of done (DoD)

• Shell uses ContentControl host (not Frame) for navigation

• Navigation service updates CurrentViewModel, views resolve via DataTemplate

• Theme switching works at runtime without restart

• Secondary windows inherit shared resources

• Tray icon provides app access when shell is hidden

Workflow

• Locate shell files: App.xaml , shell window XAML/code-behind, and theme dictionaries.

• Confirm the shell layout uses a ContentControl host (not Frame ).

• Define or update the navigation service and VM-to-view mapping.

• Centralize shared styles in merged dictionaries and keep view XAML lean.

• Add runtime theme switching by swapping merged dictionaries.

• Ensure secondary windows inherit the same resources and chrome rules.

Shell layout pattern

Use a minimal, durable layout with explicit regions and a content host:

<Grid> <Grid.RowDefinitions> <RowDefinition Height="Auto" /> <RowDefinition Height="*" /> </Grid.RowDefinitions>

<DockPanel Grid.Row="0"> <!-- Title bar / nav --> </DockPanel>

<ContentControl Grid.Row="1" Content="{Binding CurrentViewModel}" /> </Grid>

ViewModel-first navigation

Map view models to views using DataTemplates in App.xaml (or a merged dictionary). The navigation service updates CurrentViewModel on the shell VM.

<DataTemplate DataType="{x:Type vm:HomeViewModel}"> <views:HomeView /> </DataTemplate>

Resource dictionaries and themes

• Keep colors, brushes, typography, and control styles in merged dictionaries.

• Split themes into Themes/Light.xaml and Themes/Dark.xaml .

• Switch themes by replacing the theme dictionary at runtime.

References

• references/shell-layouts.md for layout variants (title bar, nav, content host).

• references/navigation-service.md for VM-first navigation patterns.

• references/theme-switching.md for dictionary swap details.

• references/design-system.md for Fluent-inspired style guidance.