Skip to content

Fix incorrect BasedOn guidance for WinUI 3 controls in xaml-styles.md - #6068

Draft
GrantMeStrength with Copilot wants to merge 2 commits into
docsfrom
copilot/restyling-controls-winui3
Draft

Fix incorrect BasedOn guidance for WinUI 3 controls in xaml-styles.md#6068
GrantMeStrength with Copilot wants to merge 2 commits into
docsfrom
copilot/restyling-controls-winui3

Conversation

Copilot AI commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

The "Avoid restyling controls" section incorrectly told WinUI 3 developers to omit BasedOn for Microsoft.UI.Xaml.Controls controls. In WinUI 3, omitting BasedOn completely replaces the default style—stripping rounded corners, theming, and all other WinUI 3 visual defaults (as the reporter's screenshots show).

Changes

  • Correct the BasedOn guidance: Replace the two-namespace paragraph split (which conflated WinUI 2/UWP with WinUI 3) with a single unambiguous rule: always use BasedOn="{StaticResource Default<ControlName>Style}" for Microsoft.UI.Xaml.Controls controls in WinUI 3.
  • Remove off-topic UWP/WinUI 2 paragraph: The Windows.UI.Xaml.Controls guidance was irrelevant to WinUI 3 apps and caused the namespace confusion the reporter hit.
  • Update code example to use Button/DefaultButtonStyle matching the reporter's scenario.
  • Update ms.date to reflect the substantive content change.
<!-- Correct: inherits WinUI 3 defaults (rounded corners, theming), overrides only Foreground -->
<Style TargetType="Button" BasedOn="{StaticResource DefaultButtonStyle}">
    <Setter Property="Foreground" Value="Blue"/>
</Style>

<!-- Wrong (old guidance): replaces the entire default style, loses rounded corners -->
<Style TargetType="Button">
    <Setter Property="Foreground" Value="Blue"/>
</Style>

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 3ad9c6b:

⚠️ Validation status: warnings

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copilot AI changed the title [WIP] Update button styles for WinUI3 controls Fix incorrect BasedOn guidance for WinUI 3 controls in xaml-styles.md Jul 30, 2026
Copilot AI requested a review from GrantMeStrength July 30, 2026 19:57
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 00889e7:

✅ Validation status: passed

File Status Preview URL Details
hub/apps/develop/platform/xaml/xaml-styles.md ✅Succeeded

For more details, please refer to the build report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

restyling controls on WinUI3

2 participants