Merge pull request #6638 from MicrosoftDocs/main

Auto Publish – main to live - 2026-04-15 05:00 UTC

Author: learn-build-service-prod[bot]

.openpublishing.redirection.json

@@ -1,5 +1,20 @@
 {
   "redirections": [
+    {
+      "source_path": "hub/apps/design/widgets/widgets-create-a-template.md",
+      "redirect_url": "/windows/apps/develop/widgets/widgets-create-a-template",
+      "redirect_document_id": true
+    },
+    {
+      "source_path": "hub/apps/design/style/sound.md",
+      "redirect_url": "/windows/apps/develop/ui/sound",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/design/app-settings/store-and-retrieve-app-data.md",
+      "redirect_url": "/windows/apps/develop/data/store-and-retrieve-app-data",
+      "redirect_document_id": true
+    },
     {
       "source_path": "uwp/audio-video-camera/camera-ui-features-for-mobile-devices.md",
       "redirect_url": "/previous-versions/windows/uwp/audio-video-camera/camera-ui-features-for-mobile-devices",

hub/advanced-settings/images/use-developer-features.png

@@ -1,18 +1,17 @@
 ---
-description: This article describes best practices for creating and displaying app settings.
+description: This article describes best practices for creating and displaying app settings in WinUI apps.
 title: Guidelines for app settings
-ms.assetid: 2D765E90-3FA0-42F5-A5CB-BEDC14C3F60A
 label: Guidelines
 template: detail.hbs
-ms.date: 09/24/2020
+ms.date: 04/08/2026
 ms.topic: article
-keywords: windows 10, uwp
+keywords: windows 11, winui
 ms.localizationpriority: medium
 ---
 
 # Guidelines for app settings
 
-App settings are the user-customizable portions of your Windows app accessed through an app settings page. For example, a news reader app might let the user specify which news sources to display or how many columns to display on the screen, while a weather app could let the user choose between Celsius and Fahrenheit. This article provides recommendations and best practices for creating and displaying app settings.
+App settings are the user-customizable portions of your Windows app, accessed through a dedicated settings page. For example, a news reader app might let the user specify which news sources to display or how many columns to display on the screen, while a weather app could let the user choose between Celsius and Fahrenheit. This article provides recommendations and best practices for creating and displaying app settings in WinUI apps.
 
 ## When to provide a settings page
 
@@ -28,7 +27,7 @@ Commands that are part of the typical app workflow (for example, changing the br
 
 - Keep settings pages simple and make use of binary (on/off) controls. A [toggle switch](../controls/toggles.md) is usually the best control for a binary setting.
 - For settings that let users choose one item from a set of up to 5 mutually exclusive, related options, use [radio buttons](../controls/radio-button.md).
-- Create an entry point for all app settings in your app setting's page.
+- Create an entry point for all app settings in your app's settings page.
 - Keep your settings simple. Define smart defaults and keep the number of settings to a minimum.
 - When a user changes a setting, the app should immediately reflect the change.
 - Don't include commands that are part of the common app workflow.
@@ -39,7 +38,7 @@ The way that users get to your app settings page should be based on your app's l
 
 **Navigation pane**
 
-For a nav pane layout, app settings should be the last item in the list of navigational choices and be pinned to the bottom:
+For a [NavigationView](../controls/navigationview.md) layout, app settings should be the last item in the list of navigational choices and be pinned to the bottom. `NavigationView` provides a built-in settings item for this purpose — set the [IsSettingsVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.navigationview.issettingsvisible) property to `true` to display a **Settings** entry at the bottom of the navigation pane automatically.
 
 ![app settings entry point for nav pane](images/appsettings-nav-settings.png)
 
@@ -49,88 +48,72 @@ If you're using a [command bar](../controls/command-bar.md) or tool bar, place t
 
 ![app settings entry point for command bar](images/appbar-overflow-icons.png)
 
-**Hub**
-
-If you're using a hub layout, the entry point for app settings should be placed inside the "More" overflow menu of a command bar.
-
-**Tabs/pivots**
+## Layout
 
-For a tabs or pivots layout, we don't recommend placing the app settings entry point as one of the top items within the navigation. Instead, the entry point for app settings should be placed inside the "More" overflow menu of a command bar.
+The app settings page should open full-screen and fill the whole window. Use a scrollable layout with a constrained max width (around 1000–1100 px) so content remains readable on wide displays. Group related settings under section headers using the **BodyStrong** text style.
 
-**List-details**
+Use the [SettingsCard and SettingsExpander](/dotnet/communitytoolkit/windows/settingscontrols/settingscard) controls from the [Windows Community Toolkit](https://aka.ms/toolkit/windows) to build your settings page. These controls provide a consistent, accessible layout with a header, description, icon, and an action control aligned to the right side of the card.
 
-Instead of burying the app settings entry point deeply within a list-details pane, make it the last pinned item on the top level of the list pane.
+For complete implementation examples, see the [WinUI Gallery settings page](https://github.com/microsoft/WinUI-Gallery/blob/main/WinUIGallery/Pages/SettingsPage.xaml) and the [Windows Community Toolkit SettingsControls sample](https://github.com/CommunityToolkit/Windows/blob/main/components/SettingsControls/samples/SettingsPageExample.xaml).
 
-## Layout
+![layout for app settings page on desktop](images/appsettings-layout-navpane-desktop.png)
 
+### SettingsCard
 
-The app settings window should open full-screen and fill the whole window. If your app settings menu has up to four top-level groups, those groups should cascade down one column.
+Use a [SettingsCard](/dotnet/communitytoolkit/windows/settingscontrols/settingscard) for individual settings. Each card has a **Header**, an optional **Description**, an optional **HeaderIcon**, and an action control (such as a `ToggleSwitch`, `ComboBox`, or `Button`) placed as the card's content. Setting the `IsClickEnabled` property to `true` makes the entire card clickable, which is useful for navigation-style entries.
 
-![layout for app settings page on desktop](images/appsettings-layout-navpane-desktop.png)
+### SettingsExpander
 
+Use a [SettingsExpander](/dotnet/communitytoolkit/windows/settingscontrols/settingsexpander) when a setting has sub-options that should be revealed on demand. The expander shows a primary action control on the header row and additional `SettingsCard` items inside the `Items` collection. This keeps the page compact while still surfacing advanced options. Avoid nesting expanders deeper than one level.
 
-## "Color mode" settings
+## App theme settings
 
+If your app allows users to choose the app's color mode, present these options using a [combo box](../controls/combo-box.md) inside a `SettingsCard`. The options should read:
 
-If your app allows users to choose the app's color mode, present these options using [radio buttons](../controls/radio-button.md) or a [combo box](../controls/combo-box.md) with the header "Choose an app mode". The options should read
 - Light
 - Dark
-- Windows default
+- Use system setting
 
-We also recommend adding a hyperlink to the Colors page of Windows Settings where users can access and modify the current default app mode. Use the string "Windows color settings" for the hyperlink text and `ms-settings:colors` for the URI.
+You may also want to add a hyperlink to the Colors page of Windows Settings where users can access and modify the current default app mode. Use the string "Windows color settings" for the hyperlink text and `ms-settings:colors` for the URI.
 
 !["Choose a mode" section](images/appsettings_mode.png)
 
-<!--
-<div class="microsoft-internal-note">
-Detailed redlines showing preferred text strings for the "Choose a mode" section are available on [UNI](https://uni/DesignDepot.FrontEnd/#/ProductNav/2543/0/dv/?t=Windows%7CControls%7CColorMode&f=RS2).
-</div>
--->
+## About section
 
-## About section and Feedback button
+We recommend placing an **About** section at the bottom of your settings page using a `SettingsExpander`. The collapsed header row should show your app name, icon, and version number. The expanded area can include:
 
-
-We recommend placing  "About this App" section in your app either as a dedicated page or in its own section. If you want a "Send Feedback" button, place that toward the bottom of the "About this App" page.
-
-Under a "Legal" subheader, place any "Terms of Use" and "Privacy Statement" (should be [hyperlink buttons](../controls/hyperlinks.md) with wrapping text) as well as additional legal information, such as copyright.
+- A link to your app's repository or website.
+- A link to file bugs or request features.
+- A list of dependencies and references as [HyperlinkButton](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.hyperlinkbutton) controls.
+- Legal information such as a copyright notice, Terms of Use, and Privacy Statement links.
 
 !["about this app" section with "give feedback" button](images/appsettings-about.png)
 
-
 ## Recommended page content
 
-
 Once you have a list of items that you want to include in your app settings page, consider these guidelines:
 
-- Group similar or related settings under one settings label.
+- Group similar or related settings under one section header.
 - Try to keep the total number of settings to a maximum of four or five.
-- Display the same settings regardless of the app context. If some settings aren't relevant in a certain context, disable those in the app settings flyout.
-- Use descriptive, one-word labels for settings. For example, name the setting "Accounts" instead of "Account settings" for account-related settings. If you only want one option for your settings and the settings don't lend themselves to a descriptive label, use "Options" or "Defaults."
-- If a setting directly links to the web instead of to a flyout, let the user know this with a visual clue, such as "Help (online)" or "Web forums" styled as a [hyperlink](../controls/hyperlinks.md). Consider grouping multiple links to the web into a flyout with a single setting. For example, an "About" setting could open a flyout with links to your terms of use, privacy policy, and app support.
-- Combine less-used settings into a single entry so that more common settings can each have their own entry. Put content or links that only contain information in an "About" setting.
-- Don't duplicate the functionality in the "Permissions" pane. Windows provides this pane by default and you can't modify it.
-
-- Add settings content to Settings flyouts
-- Present content from top to bottom in a single column, scrollable if necessary. Limit scrolling to a maximum of twice the screen height.
+- Display the same settings regardless of the app context. If some settings aren't relevant in a certain context, disable the `SettingsCard` by setting `IsEnabled` to `false`.
+- Use descriptive, one-word labels for settings headers. For example, name the setting "Accounts" instead of "Account settings" for account-related settings.
+- If a setting directly links to the web, use a clickable `SettingsCard` with `IsClickEnabled="True"` and an appropriate action icon to indicate external navigation.
+- Combine less-used settings into a `SettingsExpander` so that common settings can each have their own `SettingsCard`. Put content or links that only contain information in an "About" section.
+- Present content from top to bottom in a single column, scrollable if necessary.
 - Use the following controls for app settings:
 
     - [Toggle switches](../controls/toggles.md): To let users set values on or off.
     - [Radio buttons](../controls/radio-button.md): To let users choose one item from a set of up to 5 mutually exclusive, related options.
-    - [Text input box](../controls/text-block.md): To let users enter text. Use the type of text input box that corresponds to the type of text you're getting from the user, such as an email or password.
-    - [Hyperlinks](../controls/hyperlinks.md): To take the user to another page within the app or to an external website. When a user clicks a hyperlink, the Settings flyout will be dismissed.
-    - [Buttons](../controls/buttons.md): To let users initiate an immediate action without dismissing the current Settings flyout.
-- Add a descriptive message if one of the controls is disabled. Place this message above the disabled control.
-- Animate content and controls as a single block after the Settings flyout and header have animated. Animate content using the [**enterPage**](/previous-versions/windows/apps/br212672(v=win.10)) or [**EntranceThemeTransition**](/uwp/api/Windows.UI.Xaml.Media.Animation.EntranceThemeTransition) animations with a 100px left offset.
-- Use section headers, paragraphs, and labels to aid organize and clarify content, if necessary.
-- If you need to repeat settings, use an additional level of UI or an expand/collapse model, but avoid hierarchies deeper than two levels. For example, a weather app that provides per-city settings could list the cities and let the user tap on the city to either open a new flyout or expand to show the settings options.
-- If loading controls or web content takes time, use an indeterminate progress control to indicate to users that info is loading. For more info, see [Guidelines for progress controls](../controls/progress-controls.md).
-- Don't use buttons for navigation or to commit changes. Use hyperlinks to navigate to other pages, and instead of using a button to commit changes, automatically save changes to app settings when a user dismisses the Settings flyout.
-
-
+    - [Combo boxes](../controls/combo-box.md): To let users choose from a set of options in a compact dropdown.
+    - [Text input boxes](../controls/text-box.md): To let users enter text. Use the type of text input box that corresponds to the type of text you're getting from the user, such as an email or password.
+    - [Hyperlinks](../controls/hyperlinks.md): To take the user to another page within the app or to an external website.
+    - [Buttons](../controls/buttons.md): To let users initiate an immediate action.
+- Add a descriptive message if one of the controls is disabled. Use the `Description` property of `SettingsCard` to explain why the setting is unavailable.
+- When a user changes a setting, the app should immediately reflect the change — don't require a confirmation button.
 
 ## Related articles
 
+* [SettingsCard and SettingsExpander (Windows Community Toolkit)](/dotnet/communitytoolkit/windows/settingscontrols/settingscard)
 * [Command design basics](../basics/commanding-basics.md)
 * [Guidelines for progress controls](../controls/progress-controls.md)
-* [Store and retrieve app data](./store-and-retrieve-app-data.md)
-* [**EntranceThemeTransition**](/uwp/api/Windows.UI.Xaml.Media.Animation.EntranceThemeTransition)
+* [Store and retrieve app data](../../develop/data/store-and-retrieve-app-data.md)

hub/apps/design/app-settings/guidelines-for-app-settings.md

@@ -68,11 +68,6 @@ Use these fundamentals as a guide throughout your design process—whether you'r
     :::column-end:::
 :::row-end:::
 :::row:::
-    :::column:::
-       [![Sound icon](./images/tile-sound.png)](./style/sound.md)<br>
-        **[Sound](./style/sound.md)**<br>
-        Use audio cues to provide feedback, reinforce actions, and support accessibility.
-    :::column-end:::
     :::column:::
        [![Typography icon](./images/tile-typography.png)](./signature-experiences/typography.md)<br>
         **[Typography](./signature-experiences/typography.md)**<br>
@@ -83,19 +78,21 @@ Use these fundamentals as a guide throughout your design process—whether you'r
         **[Usability](./usability/index.md)**<br>
         Ensure your app is easy to use through intuitive interactions, clear affordances, and accessibility.
     :::column-end:::
-:::row-end:::
-
-:::row:::
     :::column:::
        [![Widgets icon](./images/tile-widgets.png)](./widgets/index.md)<br>
         **[Widgets](./widgets/index.md)**<br>
         Extend your app with glanceable, interactive surfaces that surface key information and actions.
     :::column-end:::
+:::row-end:::
+
+:::row:::
     :::column:::
        [![Writing icon](./images/tile-writing.png)](style/writing-style.md )<br>
         **[Writing](./style/writing-style.md )**<br>
         Use clear, concise, and helpful language to improve understanding and reduce cognitive load.
     :::column-end:::
     :::column:::
     :::column-end:::
+    :::column:::
+    :::column-end:::
 :::row-end:::

hub/apps/design/app-settings/images/appsettings-about.png

@@ -68,8 +68,6 @@ items:
           href: motion/directionality-and-gravity.md
     - name: Navigation
       href: basics/navigation-basics.md
-    - name: Sound
-      href: style/sound.md
     - name: Typography
       href: signature-experiences/typography.md
     - name: Usability
@@ -82,24 +80,20 @@ items:
               href: accessibility/accessibility-overview.md
             - name: Designing inclusive software
               href: accessibility/designing-inclusive-software.md
-        - name: App settings
-          items:
-            - name: Guidelines for app settings
-              href: app-settings/guidelines-for-app-settings.md
-            - name: Store and retrieve app settings and data
-              href: app-settings/store-and-retrieve-app-data.md
-        - name: Design your app for bidirectional text
-          href: globalizing/design-for-bidi-text.md
+    - name: Designing a settings page
+      href: app-settings/guidelines-for-app-settings.md
+    - name: Design your app for bidirectional text
+      href: globalizing/design-for-bidi-text.md
+    - name: In-app help
+      items:
+        - name: Guidelines for app help
+          href: in-app-help/guidelines-for-app-help.md
+        - name: Instructional UI
+          href: in-app-help/instructional-ui.md
         - name: In-app help
-          items:
-            - name: Guidelines for app help
-              href: in-app-help/guidelines-for-app-help.md
-            - name: Instructional UI
-              href: in-app-help/instructional-ui.md
-            - name: In-app help
-              href: in-app-help/in-app-help.md
-            - name: External help
-              href: in-app-help/external-help.md   
+          href: in-app-help/in-app-help.md
+        - name: External help
+          href: in-app-help/external-help.md
     - name: Widgets
       items:
         - name: Overview
@@ -110,8 +104,6 @@ items:
           href: widgets/widgets-states-and-ui.md
         - name: Interaction design guidance
           href: widgets/widgets-interaction-design.md
-        - name: Create a template with the Adaptive Card Designer
-          href: widgets/widgets-create-a-template.md
         - name: Integrate with the widget picker
           href: widgets/widgets-picker-integration.md
     - name: Writing

hub/apps/design/app-settings/images/appsettings-layout-navpane-desktop.png

@@ -179,7 +179,7 @@ App settings let you the user customize your app, optimizing it for their indivi
         <p>Best practices for creating and displaying app settings.</p>
     :::column-end:::
     :::column:::
-        <h3><a href="../app-settings/store-and-retrieve-app-data.md">Store and retrieve app data</a></h3>
+        <h3><a href="../../develop/data/store-and-retrieve-app-data.md">Store and retrieve app data</a></h3>
         <p>How to store and retrieve local, roaming, and temporary app data.</p>
     :::column-end:::
 :::row-end:::
@@ -201,7 +201,7 @@ App settings let you the user customize your app, optimizing it for their indivi
             <div class="cardPadding">
                 <div class="card">
                     <div class="cardText">
-<p><b><a href="../app-settings/store-and-retrieve-app-data.md">Store and retrieve app data</a></b><br/>How to store and retrieve local, roaming, and temporary app data.</p>
+<p><b><a href="../../develop/data/store-and-retrieve-app-data.md">Store and retrieve app data</a></b><br/>How to store and retrieve local, roaming, and temporary app data.</p>
                     </div>
                 </div>
             </div>