AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

winui-app

Bootstrap, develop, and design modern WinUI 3 desktop applications with C# and the Windows App SDK using official Microsoft guidance, WinUI Gallery patterns, Windows App SDK samples, and CommunityToolkit components. Use when creating a brand new app, preparing a machine for WinUI, reviewing, refactoring, planning, troubleshooting, environment-checking, or setting up WinUI 3 XAML, controls, navigation, windowing, theming, accessibility, responsiveness, performance, deployment, or related Windows app design and development work.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--winui-app at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 18

references/controls-layout-and-adaptive-ui.md


title: Controls, Layout, and Adaptive UI priority: HIGH tags: controls, layout, adaptive-ui, responsive, forms, lists sources:

  • https://learn.microsoft.com/windows/apps/design/layout/responsive-design
  • https://learn.microsoft.com/windows/apps/design/basics/navigation-basics
  • https://github.com/microsoft/WinUI-Gallery

What This Reference Is For

Use this file when choosing controls, composing pages, or making a WinUI layout adapt well to different window sizes and input modes.

Prefer

  • Built-in WinUI controls first.
  • Native command surfaces such as CommandBar when the UI is grouping actions, toggles, and lightweight tool controls.
  • Standard controls for common tasks: TextBox, NumberBox, ComboBox, ListView, GridView, ContentDialog, InfoBar, TeachingTip, TabView, NavigationView.
  • Explicit scroll ownership for collection layouts. If the page already scrolls vertically, prefer giving a media shelf its own horizontal ScrollViewer and a simple horizontal panel.
  • Responsive techniques such as reposition, resize, reflow, and show/hide.
  • Layouts that remain usable when the window becomes narrow.
  • A real phone-width plan when the app may be resized that far: fewer columns, reduced padding, simplified controls, and stacked content instead of compressed desktop rails.

Avoid

  • Replacing standard WinUI controls with custom controls just to change appearance.
  • Building custom toolbar rows out of generic layout panels when a stock CommandBar would cover the grouping cleanly.
  • Hard-coded sizes that only look correct at one window width.
  • Dense desktop-only layouts that break touch or keyboard workflows.
  • Adding extra controls for local filtering or sorting when live updates and a simpler layout would better match the workflow.
  • Nesting a scroll-owning GridView inside an outer page ScrollViewer without deciding which control owns scrolling; this often produces a single vertical column or awkward scroll conflicts instead of a horizontal media shelf.
  • Wrapping list sections or card groups in an extra Border when the section header, spacing, and child surfaces already establish grouping.

Control Selection Guidance

  • Forms and settings:
    • Prefer native controls first; add Toolkit settings controls only if the experience clearly benefits.
  • Command surfaces:
    • Prefer CommandBar for grouped document, formatting, view, and page-level actions before composing a custom bar from Grid, StackPanel, Border, and loose buttons.
    • Prefer the CommandBar overflow model for secondary actions before splitting the command surface into multiple custom rows.
    • Fall back to a custom command layout only when a verified CommandBar limitation, an explicit product design requirement, or unusual content composition makes the native surface a poor fit.
  • Large collections:
    • Prefer controls with virtualization-friendly behavior.
    • Use GridView when it owns the collection surface and its scrolling behavior is part of the intended experience.
    • For poster rails or other horizontal shelves inside a vertically scrolling page, prefer a horizontal ScrollViewer containing an ItemsControl or ItemsRepeater with a horizontal panel instead of a nested GridView.
    • Consider ItemsRepeater when the layout is custom and performance matters.
  • Search and filtering:
    • Prefer a single search field with live updates for local or otherwise inexpensive filtering.
    • Add explicit apply, refresh, or mode-selection controls only when the underlying operation is expensive, remote, asynchronous, or semantically different.
  • Dialogs and transient guidance:
    • Use ContentDialog for modal decisions.
    • Use InfoBar for persistent status.
    • Use TeachingTip for contextual onboarding.

Adaptive Layout Guidance

  • Design with effective pixels, not fixed device assumptions.
  • Make the smallest supported layout fully usable.
  • Add density or multi-column views only when width allows.
  • Use visual states, adaptive triggers, or layout state changes intentionally.
  • Keep commands and primary content reachable after resize.
  • Verify collection orientation and scrolling behavior at runtime. A shelf that looks horizontal in XAML can still render as a vertical stack once nested scroll regions are involved.
  • When simplifying a dense section, remove redundant outer surfaces before adding more adaptive layout rules; fewer layers usually adapt more cleanly across breakpoints.
  • Define breakpoint intent explicitly. Typical questions: when does a shelf become a stacked list, when does a footer drop nonessential controls, and when does the page stop behaving like a desktop canvas and become a single-column phone layout?
  • Simplify as width shrinks. Prefer dropping secondary controls or moving them behind shell affordances over preserving every control at every breakpoint.
  • When a page contains desktop-oriented horizontal shelves, add a phone-width alternative that stacks items vertically instead of relying on clipped rails and horizontal scrolling everywhere.

WinUI Gallery Anchors

  • Control pages for built-in WinUI control usage
  • Gallery home and shell pages for adaptive layout ideas
  • Sample pages for title bar and system backdrop interactions with content layout

Review Checklist

  • Did you choose the simplest built-in control that fits?
  • Are search and filter controls no more complex than the data flow requires?
  • Does the page remain usable when narrow?
  • Can keyboard, mouse, and touch all reach the same core actions?
  • Are spacing and hierarchy consistent across breakpoints?
  • If the page mixes page scrolling with collection scrolling, is it obvious which control owns vertical scrolling and which one, if any, owns horizontal shelf scrolling?
  • Are section containers doing real layout or surface work, or are some outer borders now redundant?
  • At phone width, does the page read as a coherent single-column flow instead of a squeezed desktop layout?