Copilot instructions

1# Copilot Instructions for MaterialDesignInXamlToolkit
2 
3## Repository Overview
4 
5The MaterialDesignInXamlToolkit is a **theme library** for WPF applications that provides Material Design themes and styling. This is NOT a control library - the focus is on theming existing WPF controls and providing custom controls only when necessary to support Google's Material Design specifications.
6 
7### Key Principles
8- Theme library, not control library
9- Styling existing WPF controls to match Material Design
10- Custom controls only for Google-specified components that don't exist in WPF
11- No application or business logic belongs in this library
12- Provide base tools and springboard for developers to create their own controls
13 
14## Architecture and Structure
15 
16### Core Projects
17- **`MaterialDesignThemes.Wpf`** - Main theming library with styles, templates, and controls
18- **`MaterialDesignColors.Wpf`** - Color palette and theme management
19- **`MaterialDesignThemes.MahApps`** - Integration with MahApps.Metro
20- **`MainDemo.Wpf`** - Primary demonstration application
21- **`MaterialDesign3.Demo.Wpf`** - Material Design 3 demonstration
22- **`MaterialDesignToolkit.ResourceGeneration`** - Build-time resource generation tools
23 
24### Key Technologies
25- **WPF (Windows Presentation Foundation)** - UI framework
26- **XAML** - Markup for UI definitions and styles  
27- **Material Design** - Google's design system implementation
28- **.NET 8** and **.NET Framework 4.7.2** - Target frameworks for the library
29- **.NET 9 SDK** - Required for building (as specified in `global.json`)
30- **C# 12.0** - Programming language
31- **PowerShell** - Build automation scripts
32 
33## Development Environment
34 
35### Requirements
36- **Windows** - Required for WPF development and compilation
37- **.NET 9 SDK** - As specified in `global.json` (note: projects target .NET 8 and .NET Framework 4.7.2)
38- **Visual Studio 2022** or **Visual Studio Code** with C# extension
39- **PowerShell** - For build scripts
40 
41### Build and Test
42```powershell
43# Restore dependencies
44dotnet restore MaterialDesignToolkit.Full.slnx
45 
46# Build (requires Windows)
47dotnet build MaterialDesignToolkit.Full.slnx --configuration Release --no-restore -p:Platform="Any CPU" -p:TreatWarningsAsErrors=True
48 
49# Run tests
50dotnet test MaterialDesignToolkit.Full.slnx --configuration Release --no-build
51 
52# Build NuGet packages
53.\build\BuildNugets.ps1 -MDIXVersion "x.x.x" -MDIXColorsVersion "x.x.x" -MDIXMahAppsVersion "x.x.x"
54```
55 
56## Code Style and Conventions
57 
58### General Guidelines
59- Follow standard Visual Studio settings with ReSharper suggestions
60- Use .editorconfig settings (4-space indents for C#, 2-space for XAML/XML)
61- Allman brace style (`csharp_new_line_before_open_brace = all`)
62- No `this.` qualification unless necessary
63- Prefer explicit types over `var` for built-in types
64- Use PascalCase for public members, interfaces start with `I`
65 
66### C# Conventions
67```csharp
68// Preferred dependency property pattern
69public static readonly DependencyProperty MyPropertyProperty =
70    DependencyProperty.Register("MyProperty", typeof(string), typeof(MyControl), 
71        new UIPropertyMetadata("DefaultValue", OnMyPropertyChanged));
72 
73public string MyProperty
74{
75    get => (string)GetValue(MyPropertyProperty);
76    set => SetValue(MyPropertyProperty, value);
77}
78 
79private static void OnMyPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
80{
81    var control = (MyControl)d;
82    // Handle property change
83}
84```
85 
86### XAML Style Guidelines
87- Use XamlStyler settings from `Settings.XamlStyler`
88- 2-space indentation for XAML
89- Keep first attribute on same line as element
90- Order attributes according to defined groups
91- Use `{StaticResource}` over `{DynamicResource}` where possible
92- Follow resource naming: `MaterialDesign.Brush.Primary.Light`
93 
94## WPF and Material Design Context
95 
96### Theme Architecture
97- **Base Themes**: Light and Dark variants
98- **Color System**: Primary, Secondary, Surface, Background colors with variants
99- **Elevation**: Shadow and overlay systems for depth
100- **Typography**: Material Design text styles
101- **Motion**: Transitions and animations
102 
103### Common Patterns
104```csharp
105// Theme modification pattern
106private static void ModifyTheme(Action<Theme> modificationAction)
107{
108    var paletteHelper = new PaletteHelper();
109    Theme theme = paletteHelper.GetTheme();
110    
111    modificationAction?.Invoke(theme);
112    
113    paletteHelper.SetTheme(theme);
114}
115 
116// Color adjustment usage
117theme.ColorAdjustment = new ColorAdjustment
118{
119    DesiredContrastRatio = desiredRatio,
120    Contrast = contrastValue,
121    Colors = colorSelection
122};
123```
124 
125### Resource Dictionary Patterns
126```xml
127<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
128                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
129                    xmlns:materialDesign="http://materialdesigninxaml.net/winfx/xaml/themes">
130  
131  <ResourceDictionary.MergedDictionaries>
132    <materialDesign:BundledTheme BaseTheme="Light" PrimaryColor="DeepPurple" SecondaryColor="Lime" />
133    <ResourceDictionary Source="pack://application:,,,/MaterialDesignThemes.Wpf;component/Themes/Generic.xaml" />
134  </ResourceDictionary.MergedDictionaries>
135 
136</ResourceDictionary>
137```
138 
139## Testing Approach
140 
141### Test Structure
142- **Unit Tests**: `MaterialDesignThemes.Wpf.Tests`, `MaterialDesignColors.Wpf.Tests`
143- **UI Tests**: `MaterialDesignThemes.UITests` - Visual/integration testing
144- **Demo Applications**: Manual testing and showcasing functionality
145 
146### Test Patterns
147```csharp
148[Test]
149public async Task ThemeTest_Example()
150{
151    await App.InitializeWithMaterialDesign(
152        baseTheme: BaseTheme.Light,
153        primary: PrimaryColor.Blue,
154        secondary: SecondaryColor.Orange);
155        
156    // Test implementation
157}
158```
159 
160## Build Pipeline and Automation
161 
162### GitHub Actions Workflows
163- **PR Verification**: `pr_verification.yml` - Build and test on PRs
164- **Build Artifacts**: `build_artifacts.yml` - Main build pipeline
165- **Release**: `release.yml` - Create releases and publish NuGets
166 
167### PowerShell Build Scripts
168- **`BuildNugets.ps1`** - Package creation
169- **`ApplyXamlStyler.ps1`** - Code formatting
170- **`MigrateBrushes.ps1`** - Resource migration utilities
171- **`UpdateNugets.ps1`** - Package management
172 
173## Domain-Specific Knowledge
174 
175### Material Design Implementation
176- Follow Google Material Design guidelines strictly
177- Implement elevation through shadows and overlays
178- Use consistent color theming system
179- Support both Material Design 2 and 3 specifications
180- Ensure accessibility compliance (contrast ratios, touch targets)
181 
182### WPF Theming Best Practices
183- Use `TemplateBinding` for connecting to parent properties
184- Implement proper focus visuals and keyboard navigation
185- Support high contrast mode and accessibility features
186- Use appropriate triggers for state changes (hover, pressed, disabled)
187- Leverage WPF's dependency property system effectively
188 
189### Resource Organization
190- Brush resources: `MaterialDesign.Brush.*`
191- Style resources: Clear, descriptive names matching WPF conventions
192- Template resources: Match control types and variants
193- Color resources: Follow Material Design naming (Primary, Secondary, Surface, etc.)
194 
195## API Design Guidelines
196 
197- **Maintain backward compatibility** - This is a widely-used library
198- **Minimal public API surface** - Only expose what's necessary
199- **Consistent naming** - Follow WPF and Material Design conventions
200- **Proper documentation** - XML docs for all public APIs
201- **Designer support** - Ensure controls work well in Visual Studio designer
202 
203## Common Tasks and Patterns
204 
205### Adding a New Style
2061. Define in appropriate XAML resource dictionary
2072. Follow existing naming conventions
2083. Test in demo applications
2094. Ensure accessibility compliance
2105. Add to migration scripts if replacing existing styles
211 
212### Theme Modifications
2131. Use `PaletteHelper` for runtime theme changes
2142. Support both static and dynamic resource binding
2153. Test with both Light and Dark themes
2164. Verify color adjustments work properly
217 
218### Custom Control Development
2191. Only when no WPF equivalent exists
2202. Follow Material Design specifications exactly
2213. Implement proper template parts and visual states
2224. Support theming and color adjustments
2235. Include comprehensive tests and demo usage
224 
225Remember: This library's primary goal is to provide a complete, high-quality Material Design theming solution for WPF applications while maintaining excellent performance and broad compatibility.