win_ui_ux_design_skill/SKILL.md

name, description

name

description

win-ui-ux-design

Design, review, and implement professional Windows desktop UI/UX for WinUI 3, Windows App SDK, XAML, Fluent Design, and Windows-targeted Qt for Python applications using PySide or PyQt. Use when a task involves Windows desktop app shells or screens, Windows 桌面端界面, PySide6, PyQt6, PySide2, PyQt5, Qt Widgets, QML, navigation and windowing, title bars, NavigationView or framework-equivalent control selection, responsive XAML or Qt layouts, theme resources, QPalette or QSS, Mica or Acrylic, keyboard/mouse/touch interaction, accessibility, design-system specifications, UI audits, or translating designs into WinUI 3, PySide, or PyQt code.

Windows Desktop UI/UX Design

Design for Windows as a keyboard-and-pointer-first, resizable, high-density desktop environment that may also receive touch and pen input. Prefer familiar platform behavior over ornamental novelty.

Follow the core rules

• Optimize the user's task flow before styling individual controls.
• Prefer WinUI controls, system resources, and built-in interaction behavior before creating custom UI.
• Treat keyboard, pointer, touch, screen reader, scaling, theme, and high contrast as one experience rather than later adaptations.
• Specify every meaningful state: default, hover, pressed, focus, selected, disabled, loading, empty, error, offline or unavailable, success, and undo when relevant.
• Use semantic tokens and theme resources. Never encode meaning with color alone or assume the light palette works in dark mode.
• Keep density appropriate for desktop work. Do not enlarge mobile patterns or hide routine commands behind touch-only gestures.
• Gate every API, control, and Toolkit recommendation by the project's Windows App SDK version, target OS, packaging model, and dependencies.
• Distinguish WinUI 3 (Microsoft.UI.Xaml) from UWP/WinUI 2 (Windows.UI.Xaml). Never copy APIs across them without verification.

Run the workflow

1. Establish constraints

Inspect the project before proposing implementation details. Determine:

• framework and exact package versions;
• minimum Windows version and packaged or unpackaged deployment;
• primary tasks, audience, localization, data density, and accessibility needs;
• expected window sizes, multi-window behavior, and resize/snap scenarios;
• primary input modes and whether touch optimization is required;
• brand constraints, light/dark behavior, and existing design tokens.

If information is missing, state conservative assumptions and keep version-sensitive recommendations conditional.

2. Model the experience

Define the primary jobs, information hierarchy, window map, navigation model, and command surfaces. Keep top-level navigation shallow. Decide which work belongs in the main window, a secondary window, an inline surface, a flyout, or a modal dialog.

Describe the happy path and recovery paths before producing mockups or XAML. Preserve user context across navigation, resize, refresh, and errors.

3. Define the visual system

Create a small semantic system for type, spacing, geometry, color, elevation, material, icons, and motion. Use Windows defaults unless the brand requires a deliberate deviation. Read windows-foundations.md for current Fluent principles, responsive breakpoints, theme, material, and motion guidance.

4. Map intent to controls and patterns

Select controls by interaction semantics, not by appearance or arbitrary item-count thresholds. Reuse commands across menus, toolbars, context menus, and accelerators. Read controls-and-patterns.md before choosing navigation, collection, form, settings, feedback, or data-table patterns.

5. Specify interaction and accessibility

Document focus order, arrow-key behavior, access keys, accelerators, pointer affordances, context menus, touch targets, drag alternatives, accessible names, announcements, contrast, and scaling. Read input-accessibility.md for the required interaction and accessibility baseline.

6. Engineer and validate

When implementation is requested, follow the existing architecture and centralize tokens, commands, and state. Preserve virtualization and avoid synchronous work on the UI thread. Read engineering-validation.md for version gates, implementation practices, performance checks, and the test matrix.

Validate the result at realistic compact, medium, and wide window widths rather than only at a full-screen monitor resolution.

Produce decision-ready output

For a new design, provide:

1. assumptions and target scenarios;
2. information architecture and window/navigation model;
3. annotated layout with responsive behavior;
4. control and command mapping;
5. semantic visual tokens;
6. interaction and state matrix;
7. accessibility requirements;
8. implementation notes and acceptance checks.

For a review, lead with findings ordered by severity. For each finding, identify the affected screen or control, user impact, violated Windows convention, and concrete correction. Separate correctness and accessibility defects from subjective polish suggestions.

For implementation, change only the requested scope, reuse the project's patterns, build or run relevant checks, and report any API/version assumptions that remain unverified.

Reject common failure modes

• Do not present obsolete UWP or archived Toolkit APIs as current WinUI 3 guidance.
• Do not recommend ComboBox for multiple selection; it does not support it.
• Do not assume the archived Windows Community Toolkit DataGrid is available in current WinUI 3 projects.
• Do not use emoji as structural interface icons; use platform glyphs or a consistent vector icon set.
• Do not force Acrylic onto every surface. Use materials to express hierarchy and provide readable solid fallbacks.
• Do not require AutomationProperties.Name where a standard control already exposes an accurate accessible name; add explicit names when semantics are otherwise missing.
• Do not confirm every deletion by default. Prefer undo for frequent, recoverable actions and reserve modal confirmation for costly or irreversible consequences.
• Do not hard-code one window size, theme, DPI, locale, or input method as the design baseline.