Update Dark theme documentation

PiperOrigin-RevId: 245964758

Author: dsn5ft

docs/theming/Dark.md

@@ -1,19 +1,19 @@
 <!--docs:
-title: "Dark Theming"
+title: "Dark Theme"
 layout: detail
 section: theming
-excerpt: "Dark Theming"
+excerpt: "Dark Theme"
 iconId: dark
 path: /theming/dark/
 -->
 
-# Dark Theming
+# Dark Theme
 
-The Material Design Dark Theming system can be used to create a beautiful and
-functional Dark Theme for your app, which consists of dark background colors and
+The Material dark theme system can be used to create a beautiful and functional
+dark theme for your app, which generally consists of dark background colors and
 light foreground colors for elements such as text an iconography.
 
-Some of the most common benefits of a Dark Theme include conserving battery
+Some of the most common benefits of a dark theme include conserving battery
 power for devices with OLED screens, reducing eye strain, and facilitating use
 in low-light environments.
 
@@ -40,30 +40,40 @@ your app theme to inherit from either `Theme.MaterialComponents` or
 </style>
 ```
 
-The `Theme.MaterialComponents` theme is a static Dark Theme, whereas the
+The `Theme.MaterialComponents` theme is a static dark theme, whereas the
 `Theme.MaterialComponents.DayNight` theme will help facilitate easy switching
-between your app's Light and Dark Theme.
+between your app's `Light` and `Dark` theme.
+
+### Catalog
+
+To see how Material components adapt in a dark theme, build and run the
+[Catalog app](../catalog-app.md) on an Android 9 device. Then enable Night mode
+via `Settings > System > Developer options > Night mode`.
 
 ### Color Palette
 
-The core of any Dark Theme is a color palette that uses dark background colors
-and light foreground colors. The Material Dark Themes make use of the
-[Material Color System](Color.md), in order to provide default Dark Theme values
+At the core of any dark theme is a color palette that uses dark background
+colors and light foreground colors. The Material `Dark` themes make use of the
+[Material Color System](Color.md), in order to provide default dark theme values
 for neutral palette colors such as `colorBackground` and `colorSurface`.
 
-The Material Dark Themes also provide adjusted defaults for the baseline branded
-palette, including `colorPrimary` and `colorSecondary`. Guidance for how you can
-adjust your brand colors for Dark Theme will be provided soon.
+The Material `Dark` theme baseline background and surface colors are dark gray
+instead of black, which increases visibility for shadows and also reduces eye
+strain for light text.
+
+The Material `Dark` themes also provide adjusted defaults for the baseline
+branded palette, including `colorPrimary` and `colorSecondary`. Guidance for how
+you can adjust your brand colors for dark theme will be provided soon.
 
 ### Elevation Overlays
 
 In addition to the color palette adjustments mentioned above, communicating the
-hierarchy of a UI via elevation requires some Dark Theme specific
+hierarchy of a UI via elevation requires some dark theme specific
 considerations.
 
-Shadows are less effective in an app using a Dark Theme, because they will have
+Shadows are less effective in an app using a dark theme, because they will have
 less contrast with the dark background colors and will appear to be less
-visible. In order to compensate for this, Material surfaces in a Dark Theme
+visible. In order to compensate for this, Material surfaces in a dark theme
 become lighter at higher elevations, when they are closer to the implied light
 source.
 
@@ -80,7 +90,7 @@ surface's background, instead of drawing another layer to the canvas.
 #### Affected Components
 
 The following is a list of Material components that support elevation overlays
-in Dark Theme, because they use `colorSurface` and can be elevated:
+in dark theme, because they use `colorSurface` and can be elevated:
 
 *   Top App Bar
 *   Bottom App Bar
@@ -100,7 +110,7 @@ the following theme attributes:
 
 Attribute Name               |Description                                                                          |Default Value
 -----------------------------|-------------------------------------------------------------------------------------|-------------
-`elevationOverlaysEnabled`   |Whether the elevation overlay functionality is enabled.                              |`false` in Light Themes, `true` in Dark Themes
+`elevationOverlaysEnabled`   |Whether the elevation overlay functionality is enabled.                              |`false` in `Light` themes, `true` in `Dark` themes
 `elevationOverlaysColor`     |The color used for the elevation overlays, applied at an alpha based on elevation.   |`colorOnSurface`
 
 Note: If inheriting from the `Theme.MaterialComponents` theme or a descendant,
@@ -109,7 +119,7 @@ Material themes already set up the above defaults.
 
 #### Custom Views & Non-Material Components
 
-If you would like to apply Dark Theme elevation overlays to your custom views or
+If you would like to apply dark theme elevation overlays to your custom views or
 any non-Material views that are elevated surfaces, then you can use the
 `MaterialShapeDrawable` or `ElevationOverlayProvider` APIs.
 
@@ -131,14 +141,14 @@ compounding the overlays multiple times.
 ##### ElevationOverlayProvider
 
 If you have a case where the elevation value is more static and you would like
-to get the corresponding Dark Theme overlay color (perhaps to color an existing
+to get the corresponding dark theme overlay color (perhaps to color an existing
 view), then you can use `ElevationOverlayProvider`.
 
 If elevation overlays are enabled at the theme level, the
 `ElevationOverlayProvider#getSurfaceColorWithOverlayIfNeeded` method will return
 `colorSurface` with the overlay color blended in at an alpha level based on the
 elevation passed in. Otherwise, it will simply return `colorSurface`, so that
-you can use the result of this method in both Light and Dark Themes without
+you can use the result of this method in both `Light` and `Dark` themes without
 needing any additional orchestration.
 
 If you need to blend the overlays with an arbitrary color or an adjusted surface