From c8c56981d290e12c0c4347f3074eab2abea12623 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 29 Aug 2025 19:27:25 +0000 Subject: [PATCH 1/2] Initial plan From b0f186850e10087f3a6e5d14a07ac4f816a5644a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 29 Aug 2025 19:32:32 +0000 Subject: [PATCH 2/2] Add comprehensive Copilot instructions for MaterialDesignInXamlToolkit Co-authored-by: Keboo <952248+Keboo@users.noreply.github.com> --- .github/copilot-instructions.md | 224 ++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..cc163ae01c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,224 @@ +# Copilot Instructions for MaterialDesignInXamlToolkit + +## Repository Overview + +The 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. + +### Key Principles +- Theme library, not control library +- Styling existing WPF controls to match Material Design +- Custom controls only for Google-specified components that don't exist in WPF +- No application or business logic belongs in this library +- Provide base tools and springboard for developers to create their own controls + +## Architecture and Structure + +### Core Projects +- **`MaterialDesignThemes.Wpf`** - Main theming library with styles, templates, and controls +- **`MaterialDesignColors.Wpf`** - Color palette and theme management +- **`MaterialDesignThemes.MahApps`** - Integration with MahApps.Metro +- **`MainDemo.Wpf`** - Primary demonstration application +- **`MaterialDesign3.Demo.Wpf`** - Material Design 3 demonstration +- **`MaterialDesignToolkit.ResourceGeneration`** - Build-time resource generation tools + +### Key Technologies +- **WPF (Windows Presentation Foundation)** - UI framework +- **XAML** - Markup for UI definitions and styles +- **Material Design** - Google's design system implementation +- **.NET 9** - Target framework +- **C# 12.0** - Programming language +- **PowerShell** - Build automation scripts + +## Development Environment + +### Requirements +- **Windows** - Required for WPF development and compilation +- **.NET 9 SDK** - As specified in `global.json` +- **Visual Studio** or **Visual Studio Code** with C# extension +- **PowerShell** - For build scripts + +### Build and Test +```powershell +# Restore dependencies +dotnet restore MaterialDesignToolkit.Full.sln + +# Build (requires Windows) +dotnet build MaterialDesignToolkit.Full.sln --configuration Release --no-restore -p:Platform="Any CPU" -p:TreatWarningsAsErrors=True + +# Run tests +dotnet test MaterialDesignToolkit.Full.sln --configuration Release --no-build + +# Build NuGet packages +.\build\BuildNugets.ps1 -MDIXVersion "x.x.x" -MDIXColorsVersion "x.x.x" -MDIXMahAppsVersion "x.x.x" +``` + +## Code Style and Conventions + +### General Guidelines +- Follow standard Visual Studio settings with ReSharper suggestions +- Use .editorconfig settings (4-space indents for C#, 2-space for XAML/XML) +- Allman brace style (`csharp_new_line_before_open_brace = all`) +- No `this.` qualification unless necessary +- Prefer explicit types over `var` for built-in types +- Use PascalCase for public members, interfaces start with `I` + +### C# Conventions +```csharp +// Preferred dependency property pattern +public static readonly DependencyProperty MyPropertyProperty = + DependencyProperty.Register("MyProperty", typeof(string), typeof(MyControl), + new UIPropertyMetadata("DefaultValue", OnMyPropertyChanged)); + +public string MyProperty +{ + get => (string)GetValue(MyPropertyProperty); + set => SetValue(MyPropertyProperty, value); +} + +private static void OnMyPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) +{ + var control = (MyControl)d; + // Handle property change +} +``` + +### XAML Style Guidelines +- Use XamlStyler settings from `Settings.XamlStyler` +- 2-space indentation for XAML +- Keep first attribute on same line as element +- Order attributes according to defined groups +- Use `{StaticResource}` over `{DynamicResource}` where possible +- Follow resource naming: `MaterialDesign.Brush.Primary.Light` + +## WPF and Material Design Context + +### Theme Architecture +- **Base Themes**: Light and Dark variants +- **Color System**: Primary, Secondary, Surface, Background colors with variants +- **Elevation**: Shadow and overlay systems for depth +- **Typography**: Material Design text styles +- **Motion**: Transitions and animations + +### Common Patterns +```csharp +// Theme modification pattern +private static void ModifyTheme(Action modificationAction) +{ + var paletteHelper = new PaletteHelper(); + Theme theme = paletteHelper.GetTheme(); + + modificationAction?.Invoke(theme); + + paletteHelper.SetTheme(theme); +} + +// Color adjustment usage +theme.ColorAdjustment = new ColorAdjustment +{ + DesiredContrastRatio = desiredRatio, + Contrast = contrastValue, + Colors = colorSelection +}; +``` + +### Resource Dictionary Patterns +```xml + + + + + + + + +``` + +## Testing Approach + +### Test Structure +- **Unit Tests**: `MaterialDesignThemes.Wpf.Tests`, `MaterialDesignColors.Wpf.Tests` +- **UI Tests**: `MaterialDesignThemes.UITests` - Visual/integration testing +- **Demo Applications**: Manual testing and showcasing functionality + +### Test Patterns +```csharp +[Test] +public async Task ThemeTest_Example() +{ + await App.InitializeWithMaterialDesign( + baseTheme: BaseTheme.Light, + primary: PrimaryColor.Blue, + secondary: SecondaryColor.Orange); + + // Test implementation +} +``` + +## Build Pipeline and Automation + +### GitHub Actions Workflows +- **PR Verification**: `pr_verification.yml` - Build and test on PRs +- **Build Artifacts**: `build_artifacts.yml` - Main build pipeline +- **Release**: `release.yml` - Create releases and publish NuGets + +### PowerShell Build Scripts +- **`BuildNugets.ps1`** - Package creation +- **`ApplyXamlStyler.ps1`** - Code formatting +- **`MigrateBrushes.ps1`** - Resource migration utilities +- **`UpdateNugets.ps1`** - Package management + +## Domain-Specific Knowledge + +### Material Design Implementation +- Follow Google Material Design guidelines strictly +- Implement elevation through shadows and overlays +- Use consistent color theming system +- Support both Material Design 2 and 3 specifications +- Ensure accessibility compliance (contrast ratios, touch targets) + +### WPF Theming Best Practices +- Use `TemplateBinding` for connecting to parent properties +- Implement proper focus visuals and keyboard navigation +- Support high contrast mode and accessibility features +- Use appropriate triggers for state changes (hover, pressed, disabled) +- Leverage WPF's dependency property system effectively + +### Resource Organization +- Brush resources: `MaterialDesign.Brush.*` +- Style resources: Clear, descriptive names matching WPF conventions +- Template resources: Match control types and variants +- Color resources: Follow Material Design naming (Primary, Secondary, Surface, etc.) + +## API Design Guidelines + +- **Maintain backward compatibility** - This is a widely-used library +- **Minimal public API surface** - Only expose what's necessary +- **Consistent naming** - Follow WPF and Material Design conventions +- **Proper documentation** - XML docs for all public APIs +- **Designer support** - Ensure controls work well in Visual Studio designer + +## Common Tasks and Patterns + +### Adding a New Style +1. Define in appropriate XAML resource dictionary +2. Follow existing naming conventions +3. Test in demo applications +4. Ensure accessibility compliance +5. Add to migration scripts if replacing existing styles + +### Theme Modifications +1. Use `PaletteHelper` for runtime theme changes +2. Support both static and dynamic resource binding +3. Test with both Light and Dark themes +4. Verify color adjustments work properly + +### Custom Control Development +1. Only when no WPF equivalent exists +2. Follow Material Design specifications exactly +3. Implement proper template parts and visual states +4. Support theming and color adjustments +5. Include comprehensive tests and demo usage + +Remember: 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. \ No newline at end of file