Skip to content

Commit e6a002a

Browse files
CopilotKeboo
Copilot
and
Keboo
authored
✨ Set up Copilot instructions for MaterialDesignInXamlToolkit (#3910)
* Initial plan * Add comprehensive Copilot instructions for MaterialDesignInXamlToolkit Co-authored-by: Keboo <952248+Keboo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Keboo <952248+Keboo@users.noreply.github.com>
1 parent 471110f commit e6a002a

File tree

1 file changed

+224
-0
lines changed

1 file changed

+224
-0
lines changed

‎.github/copilot-instructions.md‎

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

0 commit comments

Comments
 (0)