| name | windows-design |
| description | Use when the user asks for a Windows app, Win11/Win12 UI, XAML, Fluent design, WinUI, WPF, PowerToys-style tool, Microsoft Store app, desktop utility, admin tool, music/photo/creative app, Tauri desktop, Electron desktop, or any Windows desktop deliverable. Builds Windows apps across system-like WinUI 3, branded WinUI 3, Tauri 2, and Electron while preserving UX decisions, desktop archetype, originality seed, layout sketch, state coverage, Fluent/Mica rules, and motion restraint. ALWAYS ask which track first. SKIP when the user explicitly wants only Apple, Android, or web-in-browser. |
windows-design — pick the track first
Windows desktop has four distinct tracks. Each has different visual ceilings, different cost. Ask the user which one before any code. Do not default.
What This Skill Can Do
- Choose the right Windows track: strict WinUI, branded WinUI, Tauri, or Electron.
- Design desktop archetypes such as command centers, libraries, workbenches, monitoring cockpits, tray utilities, media apps, document apps, and settings/preferences.
- Preserve UX briefs, state coverage, command hierarchy, keyboard paths, inspector/detail panes, and recovery flows.
- Apply Fluent, Mica/Acrylic, Segoe UI Variable, Fluent icons, SettingsCard, NavigationView, InfoBar, and Windows density rules.
- Avoid generic sidebar/cards/table shells by using product-specific composition and anti-default rewrites.
Step 1 (MANDATORY) — Ask the user which track
Present these four options verbatim. Do not pick for them.
Which track do you want for this app?
1. System-like native (WinUI 3 strict) — feels like Settings/Calculator/Notepad. Best for: productivity utilities, internal tools, system panels. Visual ceiling: medium. Binary ~30MB. Users who care: Windows power users, IT admins. Examples: PowerToys, Snipping Tool, Sound Recorder.
2. Branded native (WinUI 3 + branded Fluent) — native chrome (Mica, Snap Layouts, ThemeResource auto dark/light/HC) but bespoke content surface (custom accent, custom display font, hero atmospheres, magazine layouts). Best for: consumer apps that want fit-in and identity. Visual ceiling: high but XAML-bound. Binary ~30MB. Examples: Apple Music for Windows, Files (community), Microsoft Photos rewrite, DevHome.
3. Tauri 2 + React/Tailwind/Motion — same React code as Electron but uses Windows' built-in WebView2 instead of bundled Chromium. Full visual freedom (mesh gradients, custom motion, real imagery, anything CSS can do). Binary ~5–10MB. RAM ~30–80MB. Mica still available via Tauri API. Examples: Cap, Spacedrive, ClashVerge, Pot.
4. Electron + React/Tailwind/Motion — bundles full Chromium. Same dev experience as Tauri but heavier. Binary ~150–250MB. RAM ~300–500MB. Largest ecosystem, every dev knows it. Examples: Spotify, Discord, VSCode, Slack, Notion, Figma desktop, Claude desktop, ChatGPT desktop.
Which? Or describe priorities (binary size, visual ambition, brand vs fit-in) and I'll pick.
If the user has already given enough signal in the brief (e.g. "I want a system tray utility" → 1; "I want it to look like Awwwards site" → 3; "Spotify-style" → 3 or 4), state your pick + reasoning in one sentence and proceed. But if ambiguous, ask.
Step 1b — Once picked, route
| Track | Reference docs | Default stack |
|---|
| 1. System-like WinUI 3 | ../../references/fluent-design.md | WinUI 3 + WinAppSDK 1.8 + CommunityToolkit.Mvvm + SettingsControls |
| 2. Branded WinUI 3 | ../../references/fluent-design.md + ../../references/branded-fluent.md | Same as 1 + custom accent override + embedded display font + bespoke surfaces |
| 3. Tauri 2 + Web | ../../references/web-fonts.md + ../../references/web-motion.md + ../../references/web-bans.md + ../../references/awwwards-ceiling.md | React 19 + Tailwind v4 + Motion (motion.dev) + Tauri 2 shell |
| 4. Electron + Web | Same as 3 | React 19 + Tailwind v4 + Motion + Electron shell + electron-builder |
For tracks 3 and 4, the web design rules from web-design SKILL apply — same anti-slop ban list, same typography curation, same aesthetic direction discipline.
Step 1c — UI decision brief
Before code, read:
../../references/ui-patterns/surface-taxonomy.md../../references/ui-patterns/ui-decision-brief.md../../references/ui-patterns/desktop-app-archetypes.md../../references/ui-patterns/originality-engine.md../../references/ui-patterns/design-recipes.md../../references/ui-patterns/anti-default-contrasts.md../../references/ui-patterns/visual-hierarchy.md../../references/ui-patterns/motion-budget.md
Write the UI decision brief, desktop archetype brief, originality brief when relevant, and a compact layout sketch before code. Pick the app shape before picking controls: command center, library/collection, workbench, monitoring cockpit, tray utility, media/consumer, document/knowledge, or setup/preferences. Then choose a composition archetype from the product subject: cockpit, command deck, ledger, timeline wall, studio desk, light table, archive index, inspection bay, instrument panel, or another concrete premise. If the sketch becomes sidebar + cards + table, use anti-default contrasts and rewrite it. Windows utilities and admin tools should favor operational density, stable navigation, command surfaces, inspectors, timelines, and low motion. Use SettingsCard/NavigationView strongly for preferences and system-like utilities, but do not make every Windows app a settings shell. Branded consumer apps may use richer content surfaces, but native chrome, Mica/Acrylic rules, Segoe UI Variable, and Fluent icons still apply.
Step 2a — Branded vs system-like (only if track 1 or 2 picked)
Track 1 = system-like. Track 2 = branded. The user already picked. Skip to step 2.
For reference: branded means native chrome + bespoke content surface. Read ../../references/branded-fluent.md.
Step 2 — WinUI 3 idioms
Every Win11 app must:
- Extend the title bar into the client area via
AppWindow.TitleBar API (preserve Snap Layouts hover)
- Apply Mica as the top-level window backdrop (
SystemBackdrop="Mica") — opaque, desktop-tinted
- Apply Acrylic only to transient surfaces: flyouts, command bars, menus
- Use Mica Alt for tabbed apps (Terminal, Edge, Files)
- Use 8px corner radius on windows, 4px on controls, 0px in dense grids
- Use tonal elevation (background brush shifts) — never CSS-style drop shadows
- Wire light/dark via
ThemeResource brushes, never hex literals
Reveal effect is deprecated in Win11 styling. Do not generate it.
Step 3 — Typography & icons
- Segoe UI Variable is the only correct face. Wire variable axes (wght 100–700, optical size). Never Segoe UI plain.
- Segoe Fluent Icons font for iconography. 1 epx monoline. Sizes: 16/20/24/32/40/48/64.
- For body text in productivity: weight 400, size 14, line height 20. For headlines: optical size adjusts automatically — let it.
Step 4 — Layout components (use these, not custom)
| Need | Use |
|---|
| Top-level navigation | NavigationView (Left, LeftCompact, Top modes) |
| Settings | SettingsCard (CommunityToolkit.WinUI.Controls.SettingsControls) |
| Library / collection | ListView / GridView + preview pane + metadata panel |
| Workbench / editor | CommandBar + canvas/document area + right-side inspector |
| Monitoring / jobs | timeline/list + InfoBar states + detail pane |
| Tray utility | compact window or tray flyout + one primary status/action |
| Inline alert | InfoBar (Severity: Informational/Success/Warning/Error) |
| Coachmark | TeachingTip |
| Disclosure | Expander |
| Path / breadcrumb | BreadcrumbBar |
| Tabbed segment toggle | SelectorBar |
Refer to WinUI Gallery (https://github.com/microsoft/WinUI-Gallery) for canonical control usage. When generating, mirror its patterns exactly.
Step 5 — Architecture
- CommunityToolkit.Mvvm (
[ObservableProperty], [RelayCommand]) — never raw INotifyPropertyChanged
- DI via
Microsoft.Extensions.Hosting
- Settings persistence via
Windows.Storage.ApplicationData.Current.LocalSettings or Microsoft.UI.Xaml.Settings
- Localization via
.resw resource files (not hardcoded strings)
Step 6 — Anti-slop ban list (Windows-specific)
Reject all of these:
- Inter / Roboto / system-ui on native chrome — only Segoe UI Variable
- CSS-style
box-shadow — use tonal elevation brushes (LayerFillColorDefaultBrush etc.)
- Custom hamburger menu where
NavigationView belongs
- Acrylic on long-lived window backgrounds (use Mica)
- Mica on flyouts (use Acrylic)
- Hardcoded hex colors — breaks dark mode + high contrast. ThemeResource only.
- Hand-rolled title bar that breaks Snap Layouts hover
- Square 90° corners
- Material Design ripples
- iOS-style segmented controls with sliding pill (use SelectorBar instead)
- Bottom tab bars (Android idiom)
- Custom scrollbars that override
ScrollViewer (breaks dynamic thinning)
- FontAwesome / Material Symbols icons (use Segoe Fluent Icons)
- Marketing-page spacing in productivity/admin tools
- Decorative cards replacing SettingsCard, table/list, or master-detail surfaces
- Sidebar plus cards plus table as the default for every desktop app
- Branded originality that only changes colors while keeping the same generic shell
Step 7 — Reference apps to emulate
- Files (files.community) — Mica + tabs + dual-pane + command palette
- PowerToys (recently redesigned by Niels Laute) — canonical NavigationView + InfoBar settings shell
- Windows Terminal — title-bar tab integration, JSON theming
- Microsoft Photos (2024 rewrite) — WinUI 3 + AI surfaces
- Snipping Tool / Clipchamp — modern command bar + teaching tips
- DevHome — dashboard widget pattern
- Notepad (rewrite) — minimal Fluent restraint
Step 8 — Tokens & assets
Read ../../references/fluent-design.md for deep token + spacing reference.
Step 9 — Fidelity tradeoffs to communicate
When the user picks a non-native stack, state the loss explicitly in one line:
- Tauri 2: "~3MB binary, but WebView2 chrome — Mica still works via window-backdrop API but font rendering and focus rings will look subtly off vs WinUI 3."
- Avalonia: "Cross-platform but Fluent theme is custom-drawn, not 1:1 with Win11."
- Electron: "Don't. Use Tauri 2 if web stack is mandated."
