winui-design

Name: winui-design
Author: microsoft

129installs20forks

How to install winui-design?

microsoft/win-dev-skills/winui-design

$npx -y skills add microsoft/win-dev-skills --skill winui-design

Installs into the current project.

Summary

Use when designing, reviewing, or fixing WinUI 3: layout planning, control choice, Fluent Design alignment, Light/Dark/High Contrast theming, typography, spacing, brushes, accessibility, and XAML data-binding design. Load before authoring new XAML, reviewing UI PRs, migrating des

Files · 1

View on GitHub

SKILL.md

1	## Search samples before writing XAML
2
3	This skill ships `winui-search.exe` alongside this `SKILL.md` (≈100 WinUI Gallery controls, every Windows Community Toolkit scenario, 90+ Reactor declarative-C# controls, curated platform-integration patterns; each result returns full code — XAML + C#, or C#-only for Reactor — plus pitfall notes). Front-load lookups, then code — don't interleave.
4
5	```powershell
6	.\winui-search.exe search "<feature 1>" "<feature 2>" ... # batch one focused query per feature (BM25 likes focused phrasing)
7	.\winui-search.exe get <id 1> <id 2> ... # batch up to 3 IDs — full XAML + C# + pitfall notes
8	.\winui-search.exe list # browse all patterns (heavy — prefer search)
9	.\winui-search.exe update # force cache refresh
10	```
11
12	Search covers controls and platform integration (file pickers, Share, JumpList, drag-drop, app lifecycle, dialogs) — front-load all lookups before writing XAML; don't interleave search with coding.
13
14	## App-shape anchors
15
16	Pick the closest shipping app silhouette before laying out a page:
17
18	\| App type \| Anchor controls \| Reference apps \|
19	\|----------\|-----------------\|----------------\|
20	\| Settings / config tool \| `NavigationView` Left + `SettingsCard` / `SettingsExpander` \| Windows Settings, Slack \|
21	\| Document / session editor \| `TabView` + full-bleed content, light chrome \| Windows Terminal, VS Code, Notepad \|
22	\| Hierarchical browser \| `TreeView` + `ListView` + `BreadcrumbBar` \| File Explorer, Outlook \|
23	\| Developer tool / dashboard \| `NavigationView` + card layout \| Dev Home, GitHub Desktop \|
24	\| Single-purpose utility \| Mode switcher + compact grid \| Calculator, Snipping Tool \|
25	\| Media / canvas / hero \| `Grid` with hero surface, floating commands, no `NavigationView` \| Photos, Spotify, Clipchamp \|
26
27	## Reach-for-this control map
28
29	Before writing XAML, map the requirement to a platform control. These mappings exist to short-circuit cross-framework instincts (WPF `DataGrid`, web `<select>`, HTML `<input type=date>`):
30
31	- Navigation: 2–7 sections → `NavigationView`; document/session tabs → `TabView`; breadcrumb trail → `BreadcrumbBar`; 2–3 modes → `SelectorBar`.
32	- Data display: Vertical list → `ListView`; tiles/grid → `GridView` or `ItemsRepeater` + `UniformGridLayout`; hierarchy → `TreeView`; tabular → `ListView` with a `Grid`-based `ItemTemplate` and a header `Grid` above (WinUI has no `DataGrid`; don't default to `CommunityToolkit.WinUI.Controls.DataGrid` — its columns can't use `x:Bind`); master-detail → `ListView` + detail `Grid`.
33	- Input: Text → `TextBox`; number → `NumberBox`; search → `AutoSuggestBox`; date → `CalendarDatePicker`; boolean → `ToggleSwitch`; pick one from 2–3 → `RadioButtons`; pick one from 4+ → `ComboBox`.
34	- Feedback: Blocking decision → `ContentDialog`; contextual action → `Flyout` / `MenuFlyout`; onboarding / hint → `TeachingTip`; inline status / async progress → `InfoBar`; system notification → `AppNotification`.
35
36	If the mapping above doesn't fit, search `winui-search.exe` before improvising.
37
38	## Window sizing (WinUI 3 specifics)
39
40	> WinUI 3 has no `SizeToContent`. Without an explicit size, Windows defaults the main window to ~1024×768 — oversized for most utilities. Size it in `MainWindow`'s constructor.
41
42	Rubric. Width = widest row + 48 padding, rounded up to nearest 20. Height = 32 (titlebar) + Σ(row heights) + Σ(spacing) + 48 padding, rounded up to 20. Round up — clipped content is a worse failure than a slightly-wide window. Sanity ranges (derive yours from the rubric):
43
44	- Single-purpose utility → ~440–560 wide
45	- Form / single-page tool → ~600–800 wide, ~640–800 tall
46	- Multi-pane (nav + content) → ~1100–1300 wide, ~720–840 tall
47	- Document / canvas / media editor → 1280+ wide
48
49	`AppWindow.Resize` takes physical pixels, not DIPs — multiply by the monitor's DPI scale. `XamlRoot.RasterizationScale` is null in the constructor and stale after `AppWindow.Move`, so `[DllImport] GetDpiForWindow` is the cleanest path:
50
51	```csharp
52	using Microsoft.UI;
53	using Microsoft.UI.Windowing;
54	using System.Runtime.InteropServices;
55	using Windows.Graphics;
56
57	public sealed partial class MainWindow : Window
58	{
59	[DllImport("user32.dll")]
60	private static extern uint GetDpiForWindow(IntPtr hWnd);
61
62	public MainWindow()
63	{
64	InitializeComponent();
65	var hwnd = Win32Interop.GetWindowFromWindowId(AppWindow.Id);
66	var scale = GetDpiForWindow(hwnd) / 96.0;
67	// widthDip / heightDip come from the rubric above — derive, don't copy.
68	App

People who liked this also viewed

6 picks

Type

winui-design

129installs20forks

View on GitHub

How to install winui-design?

microsoft/win-dev-skills/winui-design

$npx -y skills add microsoft/win-dev-skills --skill winui-design

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Search samples before writing XAML
2
3	This skill ships `winui-search.exe` alongside this `SKILL.md` (≈100 WinUI Gallery controls, every Windows Community Toolkit scenario, 90+ Reactor declarative-C# controls, curated platform-integration patterns; each result returns full code — XAML + C#, or C#-only for Reactor — plus pitfall notes). Front-load lookups, then code — don't interleave.
4
5	```powershell
6	.\winui-search.exe search "<feature 1>" "<feature 2>" ... # batch one focused query per feature (BM25 likes focused phrasing)
7	.\winui-search.exe get <id 1> <id 2> ... # batch up to 3 IDs — full XAML + C# + pitfall notes
8	.\winui-search.exe list # browse all patterns (heavy — prefer search)
9	.\winui-search.exe update # force cache refresh
10	```
11
12	Search covers controls and platform integration (file pickers, Share, JumpList, drag-drop, app lifecycle, dialogs) — front-load all lookups before writing XAML; don't interleave search with coding.
13
14	## App-shape anchors
15
16	Pick the closest shipping app silhouette before laying out a page:
17
18	\| App type \| Anchor controls \| Reference apps \|
19	\|----------\|-----------------\|----------------\|
20	\| Settings / config tool \| `NavigationView` Left + `SettingsCard` / `SettingsExpander` \| Windows Settings, Slack \|
21	\| Document / session editor \| `TabView` + full-bleed content, light chrome \| Windows Terminal, VS Code, Notepad \|
22	\| Hierarchical browser \| `TreeView` + `ListView` + `BreadcrumbBar` \| File Explorer, Outlook \|
23	\| Developer tool / dashboard \| `NavigationView` + card layout \| Dev Home, GitHub Desktop \|
24	\| Single-purpose utility \| Mode switcher + compact grid \| Calculator, Snipping Tool \|
25	\| Media / canvas / hero \| `Grid` with hero surface, floating commands, no `NavigationView` \| Photos, Spotify, Clipchamp \|
26
27	## Reach-for-this control map
28
29	Before writing XAML, map the requirement to a platform control. These mappings exist to short-circuit cross-framework instincts (WPF `DataGrid`, web `<select>`, HTML `<input type=date>`):
30
31	- Navigation: 2–7 sections → `NavigationView`; document/session tabs → `TabView`; breadcrumb trail → `BreadcrumbBar`; 2–3 modes → `SelectorBar`.
32	- Data display: Vertical list → `ListView`; tiles/grid → `GridView` or `ItemsRepeater` + `UniformGridLayout`; hierarchy → `TreeView`; tabular → `ListView` with a `Grid`-based `ItemTemplate` and a header `Grid` above (WinUI has no `DataGrid`; don't default to `CommunityToolkit.WinUI.Controls.DataGrid` — its columns can't use `x:Bind`); master-detail → `ListView` + detail `Grid`.
33	- Input: Text → `TextBox`; number → `NumberBox`; search → `AutoSuggestBox`; date → `CalendarDatePicker`; boolean → `ToggleSwitch`; pick one from 2–3 → `RadioButtons`; pick one from 4+ → `ComboBox`.
34	- Feedback: Blocking decision → `ContentDialog`; contextual action → `Flyout` / `MenuFlyout`; onboarding / hint → `TeachingTip`; inline status / async progress → `InfoBar`; system notification → `AppNotification`.
35
36	If the mapping above doesn't fit, search `winui-search.exe` before improvising.
37
38	## Window sizing (WinUI 3 specifics)
39
40	> WinUI 3 has no `SizeToContent`. Without an explicit size, Windows defaults the main window to ~1024×768 — oversized for most utilities. Size it in `MainWindow`'s constructor.
41
42	Rubric. Width = widest row + 48 padding, rounded up to nearest 20. Height = 32 (titlebar) + Σ(row heights) + Σ(spacing) + 48 padding, rounded up to 20. Round up — clipped content is a worse failure than a slightly-wide window. Sanity ranges (derive yours from the rubric):
43
44	- Single-purpose utility → ~440–560 wide
45	- Form / single-page tool → ~600–800 wide, ~640–800 tall
46	- Multi-pane (nav + content) → ~1100–1300 wide, ~720–840 tall
47	- Document / canvas / media editor → 1280+ wide
48
49	`AppWindow.Resize` takes physical pixels, not DIPs — multiply by the monitor's DPI scale. `XamlRoot.RasterizationScale` is null in the constructor and stale after `AppWindow.Move`, so `[DllImport] GetDpiForWindow` is the cleanest path:
50
51	```csharp
52	using Microsoft.UI;
53	using Microsoft.UI.Windowing;
54	using System.Runtime.InteropServices;
55	using Windows.Graphics;
56
57	public sealed partial class MainWindow : Window
58	{
59	[DllImport("user32.dll")]
60	private static extern uint GetDpiForWindow(IntPtr hWnd);
61
62	public MainWindow()
63	{
64	InitializeComponent();
65	var hwnd = Win32Interop.GetWindowFromWindowId(AppWindow.Id);
66	var scale = GetDpiForWindow(hwnd) / 96.0;
67	// widthDip / heightDip come from the rubric above — derive, don't copy.
68	App

People who liked this also viewed

6 picks

Type