[Develop/UI] (#6337)

niels9001 · jwmsft · web-flow · commit 81011a2aa8b0 · 2026-03-04T14:06:01.000-07:00
Co-authored-by: Jim Walker &lt;jimwalk@microsoft.com&gt;
diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json
@@ -1,5 +1,10 @@
 {
   "redirections": [
+    {
+      "source_path": "hub/apps/windows-app-sdk/system-backdrop-controller.md",
+      "redirect_url": "/windows/apps/develop/ui/system-backdrops",
+      "redirect_document_id": true
+    },
     {
       "source_path": "hub/apps/winui/winui3/testing/index.md",
       "redirect_url": "/windows/apps/develop/testing/",
diff --git a/hub/apps/design/layout/boxpanel-example-custom-panel.md b/hub/apps/design/layout/boxpanel-example-custom-panel.md
@@ -3,7 +3,7 @@ description: Learn to write code for a custom Panel class, implementing ArrangeO
 MS-HAID: dev\_ctrl\_layout\_txt.boxpanel\_example\_custom\_panel
 MSHAttr: PreferredLib:/library/windows/apps
 Search.Product: eADQiWindows 10XVcnh
-title: BoxPanel, an example custom panel (Windows apps)
+title: "Tutorial: Create a custom panel"
 ms.assetid: 981999DB-81B1-4B9C-A786-3025B62B74D6
 label: BoxPanel, an example custom panel
 template: detail.hbs
@@ -13,9 +13,7 @@ ms.topic: article
 keywords: windows 10, uwp
 ms.localizationpriority: medium
 ---
-# BoxPanel, an example custom panel
-
- 
+# "Tutorial: Create a custom panel
 
 Learn to write code for a custom [**Panel**](/uwp/api/Windows.UI.Xaml.Controls.Panel) class, implementing [**ArrangeOverride**](/uwp/api/windows.ui.xaml.frameworkelement.arrangeoverride) and [**MeasureOverride**](/uwp/api/windows.ui.xaml.frameworkelement.measureoverride) methods, and using the [**Children**](/uwp/api/windows.ui.xaml.controls.panel.children) property. 
 
diff --git a/hub/apps/design/style/acrylic.md b/hub/apps/design/style/acrylic.md
@@ -90,7 +90,7 @@ It's important to ensure that any text your app presents to users meets contrast
 
 ## Apply acrylic in your app
 
-To learn how to apply background acrylic or in-app acrylic in your app, including how to create custom acrylic brushes, see [Apply Mica or Acrylic materials in desktop apps for Windows 11](/windows/apps/windows-app-sdk/system-backdrop-controller).
+To learn how to apply background acrylic or in-app acrylic in your app, including how to create custom acrylic brushes, see [Apply Mica or Acrylic materials in desktop apps for Windows 11](/windows/apps/develop/ui/system-backdrops).
 
 ## Do's and don'ts
 
diff --git a/hub/apps/design/style/mica.md b/hub/apps/design/style/mica.md
@@ -126,14 +126,14 @@ You can use Mica in UWP apps that use WinUI for UWP, or in apps that use Windows
 
 ### Use Mica with the Windows App SDK
 
-To use Mica in a WinUI XAML app, see [Apply Mica or Acrylic materials in desktop apps for Windows 11](../../windows-app-sdk/system-backdrop-controller.md).
+To use Mica in a WinUI XAML app, see [Apply Mica or Acrylic materials in desktop apps for Windows 11](../../develop/ui/system-backdrops.md).
 
 To use Mica in a Win32 app, see [Apply Mica in Win32 desktop apps for Windows 11](../../desktop/modernize/ui/apply-mica-win32.md).
 
 ## Related articles
 
 - [Materials](../signature-experiences/materials.md)
 - [Layering and Elevation](../signature-experiences/layering.md)
-- [Apply Mica or Acrylic materials in desktop apps for Windows 11](../../windows-app-sdk/system-backdrop-controller.md)
+- [Apply Mica or Acrylic materials in desktop apps for Windows 11](../../develop/ui/system-backdrops.md)
 - [Apply Mica in Win32 desktop apps for Windows 11](../../desktop/modernize/ui/apply-mica-win32.md)
 - [NavigationView](../controls/navigationview.md)
diff --git a/hub/apps/develop/motion/motion-in-practice.md b/hub/apps/develop/motion/motion-in-practice.md
@@ -9,7 +9,7 @@ doc-status: Published
 ms.localizationpriority: medium
 ms.custom: RS5
 ---
-# Bringing it together
+# Animations in Windows app
 
 Timing, easing, directionality, and gravity work together to form the foundation of Fluent motion. Each has to be considered in the context of the others, and applied appropriately in the context of your app.
 
diff --git a/hub/apps/develop/toc.yml b/hub/apps/develop/toc.yml
@@ -559,6 +559,10 @@ items:
       items:
       - name: Overview
         href: user-interface.md
+      - name: Alignment, margin, and padding
+        href: ui/alignment-margin-padding.md
+      - name: Colors and themes
+        href: ui/theming.md  
       - name: Controls
         items:
         - name: Overview
@@ -747,39 +751,39 @@ items:
           href: ui/controls/title-bar.md
         - name: "Tutorial: Build XAML templated controls"
           href: ../winui/winui3/xaml-templated-controls-winui-3.md
-      - name: Shadows
-        href: ui/shadows.md
-      - name: Colors and themes
-        href: ui/theming.md
-      - name: Alignment, margin, and padding
-        href: ui/alignment-margin-padding.md
-      - name: Layout panels
-        href: ui/layout-panels.md
-      - name: Responsive layouts
-        href: ui/layouts-with-xaml.md
-      - name: Materials (Acrylic / Mica)
-        href: ../windows-app-sdk/system-backdrop-controller.md
       - name: Layout
         items:
-        - name: Custom panels
-          href: ../design/layout/custom-panels-overview.md
-        - name: 'Custom panel example: BoxPanel'
-          href: ../design/layout/boxpanel-example-custom-panel.md
-        - name: Attached Layout
+        - name: Panels
+          items:
+          - name: Layout panels
+            href: ui/layout-panels.md
+          - name: Custom panels
+            href: ../design/layout/custom-panels-overview.md
+          - name: "Tutorial: Create a custom panel"
+            href: ../design/layout/boxpanel-example-custom-panel.md
+        - name: Attached layouts
           href: ../design/layout/attached-layouts.md
         - name: Transforms
           href: platform/xaml/transforms.md
         - name: 3-D perspective effects
           href: platform/xaml/3-d-perspective-effects.md
       - name: Navigation
         items:
-        - name: Basic page navigation
-          href: ui/navigation/navigate-between-two-pages.md
         - name: Navigation history and backwards navigation
           href: ui/navigation/navigation-history-and-backwards-navigation.md
+        - name: "Tutorial: Implement navigation between two pages"
+          href: ui/navigation/navigate-between-two-pages.md
+      - name: Materials
+        items:
+        - name: Overview
+          href: ui/materials.md
+        - name: System backdrops (Mica/Acrylic)
+          href: ui/system-backdrops.md
+        - name: In-app acrylic
+          href: ui/in-app-acrylic.md
       - name: Motion
         items:
-        - name: Motion in practice
+        - name: Overview
           href: motion/motion-in-practice.md
         - name: Page transitions
           href: motion/page-transitions.md
@@ -796,6 +800,10 @@ items:
               href: motion/storyboarded-animations.md
             - name: Key-frame and easing function animations
               href: motion/key-frame-and-easing-function-animations.md
+      - name: Responsive layouts
+        href: ui/layouts-with-xaml.md
+      - name: Shadows
+        href: ui/shadows.md   
       - name: Windowing
         items:
         - name: Overview
diff --git a/hub/apps/develop/ui/in-app-acrylic.md b/hub/apps/develop/ui/in-app-acrylic.md
@@ -0,0 +1,86 @@
+---
+title: In-app acrylic
+description: Learn how to use AcrylicBrush to apply in-app acrylic effects to UI elements in your WinUI app.
+ms.topic: how-to
+ms.date: 02/27/2026
+keywords: windows, windows app development, Windows App SDK, Acrylic, AcrylicBrush, materials
+ms.localizationpriority: medium
+---
+
+# In-app acrylic
+
+You can apply in-app acrylic to your app's surfaces using a XAML [AcrylicBrush](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) or predefined `AcrylicBrush` theme resources.
+
+> [!div class="nextstepaction"]
+> [Open the WinUI Gallery app and see Acrylic in action](winui3gallery://item/Acrylic)
+
+WinUI includes a collection of brush theme resources that respect the app's theme and fall back to solid colors as needed. To paint a specific surface, apply one of the theme resources to element backgrounds just as you would apply any other brush resource.
+
+```xaml
+<Grid Background="{ThemeResource AcrylicInAppFillColorDefaultBrush}">
+```
+
+> [!NOTE]
+> You can view these resources in the [AcrylicBrush theme resources file, in the microsoft-ui-xaml GitHub repo](https://github.com/microsoft/microsoft-ui-xaml/blob/6aed8d97fdecfe9b19d70c36bd1dacd9c6add7c1/dev/Materials/Acrylic/AcrylicBrush_19h1_themeresources.xaml#L11).
+
+## Custom acrylic brush
+
+You may choose to add a color tint to your app's acrylic to show branding or provide visual balance with other elements on the page. To show color rather than grayscale, you need to define your own acrylic brushes using the following properties.
+
+- **TintColor**: the color/tint overlay layer.
+- **TintOpacity**: the opacity of the tint layer.
+- **TintLuminosityOpacity**: controls the amount of saturation that is allowed through the acrylic surface from the background.
+- **FallbackColor**: the solid color that replaces acrylic in Battery Saver. For background acrylic, fallback color also replaces acrylic when your app isn't in the active desktop window.
+
+![Light theme acrylic swatches](../../design/style/images/custom-acrylic-swatches-light-theme.png)
+
+![Dark theme acrylic swatches](../../design/style/images/custom-acrylic-swatches-dark-theme.png)
+
+![Luminosity opacity compared to tint opacity](../../design/style/images/luminosity-vs-tint.png)
+
+To add an acrylic brush, define the three resources for dark, light, and high contrast themes. In high contrast, we recommend that you use a [SolidColorBrush](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.solidcolorbrush) with the same `x:Key` as the dark/light AcrylicBrush.
+
+> [!NOTE]
+> If you don't specify a `TintLuminosityOpacity` value, the system will automatically adjust its value based on your TintColor and TintOpacity.
+
+```xaml
+<ResourceDictionary.ThemeDictionaries>
+    <ResourceDictionary x:Key="Default">
+        <AcrylicBrush x:Key="MyAcrylicBrush"
+            TintColor="#FFFF0000"
+            TintOpacity="0.8"
+            TintLuminosityOpacity="0.5"
+            FallbackColor="#FF7F0000"/>
+    </ResourceDictionary>
+
+    <ResourceDictionary x:Key="HighContrast">
+        <SolidColorBrush x:Key="MyAcrylicBrush"
+            Color="{ThemeResource SystemColorWindowColor}"/>
+    </ResourceDictionary>
+
+    <ResourceDictionary x:Key="Light">
+        <AcrylicBrush x:Key="MyAcrylicBrush"
+            TintColor="#FFFF0000"
+            TintOpacity="0.8"
+            TintLuminosityOpacity="0.5"
+            FallbackColor="#FFFF7F7F"/>
+    </ResourceDictionary>
+</ResourceDictionary.ThemeDictionaries>
+```
+
+The following sample shows how to declare an AcrylicBrush in code.
+
+```csharp
+AcrylicBrush myBrush = new AcrylicBrush();
+myBrush.TintColor = Color.FromArgb(255, 202, 24, 37);
+myBrush.FallbackColor = Color.FromArgb(255, 202, 24, 37);
+myBrush.TintOpacity = 0.6;
+
+grid.Fill = myBrush;
+```
+
+## Related articles
+
+- [Materials overview](materials.md)
+- [System backdrops (Mica/Acrylic)](system-backdrops.md)
+- [Acrylic design guidance](../../design/style/acrylic.md)
diff --git a/hub/apps/develop/ui/layouts-with-xaml.md b/hub/apps/develop/ui/layouts-with-xaml.md
@@ -63,10 +63,6 @@ The default column width is "*", so you don't need to explicitly set this value
 </Grid>
 ```
 
-In the Visual Studio XAML designer, the result looks like this.
-
-![A 4 column grid in the Visual Studio designer](../../design/layout/images/xaml-layout-grid-in-designer.png)
-
 To get the size of an element at runtime, use the read-only [**ActualHeight**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.actualheight) and [**ActualWidth**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.actualwidth) properties instead of Height and Width.
 
 **Size constraints**
@@ -135,11 +131,11 @@ To apply a visual state from code, you call the [**VisualStateManager.GoToState*
 Here, a [**VisualStateGroup**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.visualstategroup) contains two VisualState definitions. The first, `DefaultState`, is empty. When it's applied, the values defined in the XAML page are applied. The second, `WideState`, changes the [**DisplayMode**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.splitview.displaymode) property of the [**SplitView**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.splitview) to **Inline** and opens the pane. This state is applied in the SizeChanged event handler if the window width is greater than 640 effective pixels.
 
 > [!NOTE]
-> Windows doesn't provide a way for your app to detect the specific device your app is running on. It can tell you the device family (desktop, etc) the app is running on, the effective resolution, and the amount of screen space available to the app (the size of the app's window). We recommend defining visual states for [screen sizes and break points](../../design/layout/screen-sizes-and-breakpoints-for-responsive-design.md).
+> Windows doesn't provide a way for your app to detect the specific device your app is running on. It can tell you the effective resolution, and the amount of screen space available to the app (the size of the app's window). We recommend defining visual states for [screen sizes and break points](../../design/layout/screen-sizes-and-breakpoints-for-responsive-design.md).
 
 ```xaml
 <Page ...
-    SizeChanged="CurrentWindow_SizeChanged">
+    SizeChanged="Page_SizeChanged">
     <Grid>
         <VisualStateManager.VisualStateGroups>
             <VisualStateGroup>
@@ -182,7 +178,7 @@ Here, a [**VisualStateGroup**](/windows/windows-app-sdk/api/winrt/microsoft.ui.x
 ```
 
 ```csharp
-private void CurrentWindow_SizeChanged(object sender, Windows.UI.Core.WindowSizeChangedEventArgs e)
+private void Page_SizeChanged(object sender, Microsoft.UI.Xaml.SizeChangedEventArgs e)
 {
     if (e.Size.Width > 640)
         VisualStateManager.GoToState(this, "WideState", false);
@@ -193,10 +189,10 @@ private void CurrentWindow_SizeChanged(object sender, Windows.UI.Core.WindowSize
 
 ```cppwinrt
 // YourPage.h
-void CurrentWindow_SizeChanged(winrt::Windows::Foundation::IInspectable const& sender, winrt::Windows::UI::Xaml::SizeChangedEventArgs const& e);
+void Page_SizeChanged(winrt::Windows::Foundation::IInspectable const& sender, winrt::Microsoft::UI::Xaml::SizeChangedEventArgs const& e);
 
 // YourPage.cpp
-void YourPage::CurrentWindow_SizeChanged(IInspectable const& sender, SizeChangedEventArgs const& e)
+void YourPage::Page_SizeChanged(IInspectable const& sender, SizeChangedEventArgs const& e)
 {
     if (e.NewSize.Width > 640)
         VisualStateManager::GoToState(*this, "WideState", false);
diff --git a/hub/apps/develop/ui/materials.md b/hub/apps/develop/ui/materials.md
@@ -0,0 +1,32 @@
+---
+title: Materials overview
+description: Learn about materials in Windows apps, including Mica, Acrylic, and in-app acrylic brushes.
+ms.topic: concept-article
+ms.date: 02/27/2026
+keywords: windows, windows app development, Windows App SDK, Mica, Acrylic, materials
+ms.localizationpriority: medium
+---
+
+# Materials in Windows apps
+
+[Materials](../../design/signature-experiences/materials.md) are visual effects applied to UX surfaces that resemble real life artifacts. They play a key role in creating depth, hierarchy, and visual interest in your app's interface.
+
+Windows provides two primary material types:
+
+- [**Mica**](../../design/style/mica.md) — An opaque material that incorporates the user's theme and desktop wallpaper to create a highly personalized appearance. Mica is designed for performance as it only captures the background wallpaper once to create its visualization, making it ideal for the foundation layer of your app, especially in the title bar area.
+
+- [**Acrylic**](../../design/style/acrylic.md) — A semi-transparent material that replicates the effect of frosted glass. Acrylic can be used as a system backdrop for transient, light-dismiss surfaces (such as flyouts and context menus), or as an in-app brush applied directly to UI elements.
+
+## How to use materials
+
+There are two ways to use materials in your WinUI apps:
+
+- **[System backdrops (Mica/Acrylic)](system-backdrops.md)** — Apply Mica or Desktop Acrylic as the background of your app window or transient UI surfaces like flyouts and popups. This is set via the `SystemBackdrop` property on `Window`, `Flyout`, `Popup`, and other elements.
+
+- **[In-app acrylic](in-app-acrylic.md)** — Apply acrylic effects directly to UI elements within your app using `AcrylicBrush` theme resources or custom acrylic brushes. This is useful for panels, sidebars, and other content areas where you want a translucent effect.
+
+## Related articles
+
+- [Materials in Windows 11](../../design/signature-experiences/materials.md)
+- [Mica design guidance](../../design/style/mica.md)
+- [Acrylic design guidance](../../design/style/acrylic.md)
diff --git a/hub/apps/develop/ui/navigation/navigate-between-two-pages.md b/hub/apps/develop/ui/navigation/navigate-between-two-pages.md
@@ -1,6 +1,6 @@
 ---
 description: Learn how to enable peer-to-peer navigation between two basic pages in an Windows app.
-title: Peer-to-peer navigation between two pages
+title: "Tutorial: Implement navigation between two pages"
 ms.assetid: 0A364C8B-715F-4407-9426-92267E8FB525
 label: Peer-to-peer navigation between two pages
 template: detail.hbs
@@ -13,7 +13,7 @@ dev_langs:
 - cppwinrt
 ---
 
-# Implement navigation between two pages
+# Tutorial: Implement navigation between two pages
 
 Learn how to use a frame and pages to enable basic peer-to-peer navigation in your app.
 
@@ -36,7 +36,7 @@ To create a blank app in Visual Studio:
 1. To set up your development computer, see [Start developing Windows apps](../../../get-started/start-here.md).
 1. From the Microsoft Visual Studio start window, select **Create a new project**, OR, on the Visual Studio menu, choose **File** > **New** > **Project**.
 1. In the **Create a new project** dialog's drop-down filters, select **C#** or **C++**, **Windows**, and **WinUI**, respectively.
-1. Select the **Blank App, Packaged (WinUI in Desktop)** project template, and click **Next**. That template creates a desktop app with a WinUI-based user interface.
+1. Select the **WinUI Blank App (Packaged)** project template, and click **Next**. That template creates a desktop app with a WinUI-based user interface.
 1. In the **Project name** box, enter `BasicNavigation`, and click **Create**.
 1. To run the program, choose **Debug** > **Start Debugging** from the menu, or press F5. Build and run your solution on your development computer to confirm that the app runs without errors. A blank page is displayed.
 1. To stop debugging and return to Visual Studio, exit the app, or click **Stop Debugging** from the menu.
@@ -116,7 +116,7 @@ To add a new item to your app:
 
 1. In **Solution Explorer**, right-click the `BasicNavigation` project node to open the context menu.
 1. Choose **Add** > **New Item** from the context menu.
-1. In the **Add New Item** dialog box, select the **WinUI** node in the left pane, then choose **Blank Page (WinUI)** in the middle pane.
+1. In the **Add New Item** dialog box, select the **WinUI** node in the left pane, then choose **Blank Page** in the middle pane.
 1. In the **Name** box, enter `MainPage` and press the **Add** button.
 1. Repeat steps 1-4 to add the second page, but in the **Name** box, enter `Page2`.
 
diff --git a/hub/apps/develop/ui/shadows.md b/hub/apps/develop/ui/shadows.md
@@ -28,6 +28,10 @@ Here is how ThemeShadow has been implemented on a MenuFlyout. MenuFlyout has a b
 
 ![A screen shot of ThemeShadow applied to a MenuFlyout with three open, nested menus.](../../design/layout/images/elevation-shadow/themeshadow-menuflyout.png)
 
+> [!div class="nextstepaction"]
+> [Open the WinUI Gallery app and see ThemeShadow in action](winui3gallery:/item/ThemeShadow)
+
+
 ### ThemeShadow in common controls
 
 The following common controls will automatically use ThemeShadow to cast shadows from 32px depth unless otherwise specified:
@@ -46,9 +50,6 @@ The following common controls will automatically use ThemeShadow to cast shadows
 - [BreadcrumbBar](controls/breadcrumbbar.md)
 - [Connected animation](../../design/motion/connected-animation.md)
 
-> [!NOTE]
-> ThemeShadow was introduced in Windows 10 version 1903 (SDK 18362). It is updated in Windows 11 to use ninegrid shadow instead of projected shadow for better performance.
-
 ### ThemeShadow in Popups
 
 It is often the case that your app's UI uses a popup for scenarios where you need user's attention and quick action. These are great examples when shadow should be used to help create hierarchy in your app's UI.
@@ -153,4 +154,4 @@ DropShadow does not provide built in shadow values and you need to specify them
 ## Related articles
 
 - [Elevation and layering in Windows](../../design/signature-experiences/layering.md)
-- [Materials (Acrylic / Mica)](../../windows-app-sdk/system-backdrop-controller.md)
+- [Materials (Acrylic / Mica)](system-backdrops.md)
diff --git a/hub/apps/develop/ui/system-backdrops.md b/hub/apps/develop/ui/system-backdrops.md
diff --git a/hub/apps/develop/ui/theming.md b/hub/apps/develop/ui/theming.md
diff --git a/hub/apps/develop/ui/windowing-overview.md b/hub/apps/develop/ui/windowing-overview.md
diff --git a/hub/apps/develop/user-interface.md b/hub/apps/develop/user-interface.md
diff --git a/hub/apps/get-started/windows-developer-faq.md b/hub/apps/get-started/windows-developer-faq.md

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,10 @@`
`1`	`1`	`{`
`2`	`2`	`"redirections": [`
	`3`	`+ {`
	`4`	`+ "source_path": "hub/apps/windows-app-sdk/system-backdrop-controller.md",`
	`5`	`+ "redirect_url": "/windows/apps/develop/ui/system-backdrops",`
	`6`	`+ "redirect_document_id": true`
	`7`	`+ },`
`3`	`8`	`{`
`4`	`9`	`"source_path": "hub/apps/winui/winui3/testing/index.md",`
`5`	`10`	`"redirect_url": "/windows/apps/develop/testing/",`