diff --git a/windows-apps-src/design/layout/depth-shadow.md b/windows-apps-src/design/layout/depth-shadow.md index 40db9e50d0..aadd0b18c8 100644 --- a/windows-apps-src/design/layout/depth-shadow.md +++ b/windows-apps-src/design/layout/depth-shadow.md @@ -2,7 +2,7 @@ description: Z-depth, or relative depth, and shadow are two ways to incorporate depth into your app to help users focus naturally and efficiently. title: Z-depth and shadow for Windows apps template: detail.hbs -ms.date: 09/24/2020 +ms.date: 06/24/2021 ms.topic: article ms.custom: 19H1 keywords: windows 10, uwp @@ -18,47 +18,51 @@ Creating a visual hierarchy of elements in your UI makes the UI easy to scan and Z-depth is a term used amongst 3D app creators to denote the distance between two surfaces along the z-axis. It illustrates how close an object is to the viewer. Think of it as a similar concept to x/y coordinates, but in the z direction. +Windows apps use shadows to express depth and add visual hierarchy. To achieve this, the z-axis provides an easy coding path. However, the shadows are emulated; they are not displayed in the true 3D sense. This is so that we can achieve the feeling of depth without sacrificing the performance of your app's UI. + ## Why use z-depth? -In the physical world, we tend to focus on objects that are closer to us. We can apply this spatial instinct to digital UI as well. For example, if you bring an element closer to the user, then the user will instinctively focus on the element. By moving UI elements closer in z-axis, you can establish visual hierarchy between objects, helping users complete tasks naturally and efficiently in your app. +In the physical world, we tend to focus on objects that are closer to us. We can apply this spatial instinct to digital UI as well. For example, if you bring an element closer to the user, then the user will instinctively focus on the element. By moving UI elements closer on the z-axis, you can establish visual hierarchy between objects, helping users complete tasks naturally and efficiently in your app. ## What is shadow? -Shadow is one way a user perceives elevation. Light above an elevated object creates a shadow on the surface below. The higher the object, the larger and softer the shadow becomes. Elevated objects in your UI don’t need to have shadows, but they help create the appearance of elevation. +Shadow is one way a user perceives elevation. Light above an elevated object creates a shadow on the surface below. The higher the object, the larger and softer the shadow becomes. Elevated objects in your UI don't need to have shadows, but they help create the appearance of elevation. In Windows apps, shadows should be used in a purposeful rather than aesthetic manner. Using too many shadows will decrease or eliminate the ability of the shadow to focus the user. -If you use standard controls, ThemeShadow shadows will be incorporated automatically into your UI. However, you can manually include shadows in your UI by using either the ThemeShadow or the DropShadow APIs. +If you use standard controls, shadows are already incorporated into your UI. However, you can manually include shadows in your UI by using either the [ThemeShadow](/uwp/api/windows.ui.xaml.media.themeshadow) or the [DropShadow](/uwp/api/windows.ui.composition.dropshadow) APIs. ## ThemeShadow -The [ThemeShadow](/uwp/api/windows.ui.xaml.media.themeshadow) type can be applied to any XAML element to draw shadows appropriately based on x, y, z coordinates. ThemeShadow also automatically adjusts for other environmental specifications: +The [ThemeShadow](/uwp/api/windows.ui.xaml.media.themeshadow) type can be applied to any XAML element to draw shadows appropriately based on x, y, z coordinates. -- Adapts to changes in lighting, user theme, app environment, and shell. -- Applies shadows to elements automatically based on their z-depth. -- Keeps elements in sync as they move and change elevation. -- Keeps shadows consistent throughout and across applications. +- It applies shadows to elements based on z-depth value, emulating depth. +- It keeps shadows consistent throughout and across applications thanks to built in shadow aesthetics. -Here is how ThemeShadow has been implemented on a MenuFlyout. MenuFlyout has a built in experience where the main surface is elevated to 32px and each additional cascading menu is opened +8px above the menu it opens from. +Here is how ThemeShadow has been implemented on a MenuFlyout. MenuFlyout has a built in shadow with a depth of 32px applied to the main menu and all nested menus. -![A screen shot of ThemeShadow applied to a MenuFlyout with three open, nested menus. The first menu is elevated 32px and each subsequent menu that opens from the previous menu is elevated 8px more such that it leaves a distinct shadow on the background.](images/elevation-shadow/themeshadow-menuflyout.png) +![A screen shot of ThemeShadow applied to a MenuFlyout with three open, nested menus.](images/elevation-shadow/themeshadow-menuflyout.png) ### ThemeShadow in common controls The following common controls will automatically use ThemeShadow to cast shadows from 32px depth unless otherwise specified: - [Context menu](../controls-and-patterns/menus.md), [Command bar](../controls-and-patterns/app-bars.md), [Command bar flyout](../controls-and-patterns/command-bar-flyout.md), [MenuBar](../controls-and-patterns/menus.md#create-a-menu-bar) -- [Dialogs and flyouts](../controls-and-patterns/dialogs-and-flyouts/index.md) (Dialog at 64px) +- [Dialogs and flyouts](../controls-and-patterns/dialogs-and-flyouts/index.md) (Dialog at 128px) - [NavigationView](../controls-and-patterns/navigationview.md) - [ComboBox](../controls-and-patterns/combo-box.md), [DropDownButton, SplitButton, ToggleSplitButton](../controls-and-patterns/buttons.md) - [TeachingTip](../controls-and-patterns/dialogs-and-flyouts/teaching-tip.md) -- [AutoSuggestBox](../controls-and-patterns/auto-suggest-box.md) +- [AutoSuggestBox](../controls-and-patterns/auto-suggest-box.md) - [Calendar/Date/Time pickers](../controls-and-patterns/date-and-time.md) - [Tooltip](../controls-and-patterns/tooltips.md) (16px) +- [Number Box](../controls-and-patterns/number-box.md) +- [TabView](../controls-and-patterns/tab-view.md) - [Media transport control](../controls-and-patterns/media-playback.md#media-transport-controls), [InkToolbar](../controls-and-patterns/inking-controls.md) +- [BreadcrumbBar](../controls-and-patterns/breadcrumbbar.md) - [Connected animation](../motion/connected-animation.md) -Note: Flyouts will only apply ThemeShadow when compiled against Windows 10 version 1903 or a more recent SDK. +> [!NOTE] +> ThemeShadow was introduced in Windows 10 version 1903 (SDK 18362). It is updated in Windows 11 to to use ninegrid shadow instead of projected shadow for better performance. ### ThemeShadow in Popups @@ -106,6 +110,9 @@ If the default shadow doesn't look correct on your control's content then you ca ### ThemeShadow in other elements +> [!NOTE] +> Starting with Windows 11, if the app targets the Windows 11 SDK or later, the Receivers collection is ignored. However there will be no errors and the shadow continues to function. + In general we encourage you to think carefully about your use of shadow and limit its use to cases where it introduces meaningful visual hierarchy. However, we do provide a way to cast a shadow from any UI element in case you have advanced scenarios that necessitate it. To cast a shadow from a XAML element that isn't in a Popup, you must explicitly specify the other elements that can receive the shadow in the `ThemeShadow.Receivers` collection. Receivers cannot be an ancestor of the caster in the visual tree. @@ -136,31 +143,24 @@ Rectangle2.Translation += new Vector3(120, 0, 32); ![Two turquoise rectangles next to each other, both with shadows.](images/elevation-shadow/SharedShadow.png) -### Performance best practices for ThemeShadow - -1. The system sets a limit of 5 caster-receiver pairs, and will turn off shadow if this is exceeded. Stick to the system-enforced limit of 5 caster-receiver pairs. - -2. Limit the number of custom receiver elements to the minimum necessary. - -3. If multiple receiver elements are at the same elevation, try to combine them by targeting a single parent element instead. - -4. If multiple elements will cast the same type of shadow onto the same receiver elements then add the shadow as a shared resource and reuse it. - ## Drop shadow -DropShadow is not automatically responsive to its environment and does not use light sources. For example implementations, see the [DropShadow Class](/uwp/api/windows.ui.composition.dropshadow). +DropShadow does not provide built in shadow values and you need to specify them yourself. For example implementations, see the [DropShadow](/uwp/api/windows.ui.composition.dropshadow) class. + +> [!TIP] +> Starting with Windows 11, if the app targets the Windows 11 SDK or later, ThemeShadow will behave like a drop shadow. If you are using DropShadow, you might consider using ThemeShadow instead. ## Which shadow should I use? | Property | ThemeShadow | DropShadow | | - | - | - | -| **Min SDK** | Windows 10 version 1903 | 14393 | +| **Min SDK** | SDK 18362 | SDK 14393 | | **Adaptability** | Yes | No | | **Customization** | No | Yes | -| **Light source** | Automatic (global by default, but can override per app) | None | -| **Supported in 3D environments** | Yes | No | +| **Light source** | None | None | +| **Supported in 3D environments** | Yes (_While it works in a 3D environment, the shadows are emulated._) | No | - Keep in mind that the purpose of shadow is to provide meaningful hierarchy, not as a simple visual treatment. -- Generally, we recommend using ThemeShadow, which adapts automatically to its environment. +- Generally, we recommend using ThemeShadow, which provides consistent shadow values. - For concerns about performance, limit the number of shadows, use other visual treatment, or use DropShadow. - If you have more advanced scenarios to achieve visual hierarchy, consider using other visual treatment (for example, color). If shadow is needed, then use DropShadow.