Skip to content

Commit 7b72c17

Browse files
dsn5ftdsn5ft
committed
Add documentation for Dark Theming and Elevation Overlays
PiperOrigin-RevId: 244658145
1 parent c42eb1e commit 7b72c17

File tree

2 files changed

+153
-3
lines changed

2 files changed

+153
-3
lines changed

‎docs/theming.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,10 @@ Material Components for Android.
1919
For information on the individual Material Theming systems, take a look at the
2020
following guides:
2121

22-
* [Color Theming](theming/Color.md)
23-
* [Typography Theming](theming/Typography.md)
24-
* [Shape Theming](theming/Shape.md)
22+
* [Color Theming](theming/Color.md)
23+
* [Typography Theming](theming/Typography.md)
24+
* [Shape Theming](theming/Shape.md)
25+
* [Dark Theming](theming/Dark.md)
2526

2627
## Useful Links
2728
- [Getting Started](getting-started.md)

‎docs/theming/Dark.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
<!--docs:
2+
title: "Dark Theming"
3+
layout: detail
4+
section: theming
5+
excerpt: "Dark Theming"
6+
iconId: dark
7+
path: /theming/dark/
8+
-->
9+
10+
# Dark Theming
11+
12+
The Material Design Dark Theming system can be used to create a beautiful and
13+
functional Dark Theme for your app, which consists of dark background colors and
14+
light foreground colors for elements such as text an iconography.
15+
16+
Some of the most common benefits of a Dark Theme include conserving battery
17+
power for devices with OLED screens, reducing eye strain, and facilitating use
18+
in low-light environments.
19+
20+
## Design & API Documentation
21+
22+
- [AppCompat DayNight Documentation][appcompat-daynight-docs]
23+
<!--{: .icon-list-item.icon-list-item--spec }-->
24+
25+
### Setup
26+
27+
Using the latest `1.1.0` alpha version of the Material Android library, update
28+
your app theme to inherit from either `Theme.MaterialComponents` or
29+
`Theme.MaterialComponents.DayNight` (or one of their descendants). E.g.:
30+
31+
```xml
32+
<style name="Theme.MyApp" parent="Theme.MaterialComponents">
33+
<!-- ... -->
34+
</style>
35+
```
36+
37+
```xml
38+
<style name="Theme.MyApp" parent="Theme.MaterialComponents.DayNight">
39+
<!-- ... -->
40+
</style>
41+
```
42+
43+
The `Theme.MaterialComponents` theme is a static Dark Theme, whereas the
44+
`Theme.MaterialComponents.DayNight` theme will help facilitate easy switching
45+
between your app's Light and Dark Theme.
46+
47+
### Color Palette
48+
49+
The core of any Dark Theme is a color palette that uses dark background colors
50+
and light foreground colors. The Material Dark Themes make use of the
51+
[Material Color System](Color.md), in order to provide default Dark Theme values
52+
for neutral palette colors such as `colorBackground` and `colorSurface`.
53+
54+
The Material Dark Themes also provide adjusted defaults for the baseline branded
55+
palette, including `colorPrimary` and `colorSecondary`. Guidance for how you can
56+
adjust your brand colors for Dark Theme will be provided soon.
57+
58+
### Elevation Overlays
59+
60+
In addition to the color palette adjustments mentioned above, communicating the
61+
hierarchy of a UI via elevation requires some Dark Theme specific
62+
considerations.
63+
64+
Shadows are less effective in an app using a Dark Theme, because they will have
65+
less contrast with the dark background colors and will appear to be less
66+
visible. In order to compensate for this, Material surfaces in a Dark Theme
67+
become lighter at higher elevations, when they are closer to the implied light
68+
source.
69+
70+
This is accomplished via elevation overlays, which are semi-transparent white
71+
(`colorOnSurface`) overlays that are conceptually placed on top of the surface
72+
color. The semi-transparent alpha percentage is calculated using an equation
73+
based on elevation, which results in higher alpha percentages at higher
74+
elevations, and therefore lighter surfaces.
75+
76+
Note: we avoid overdraw with the elevation overlays by calculating a composite
77+
blend of the surface color with the overlay color and using that as the
78+
surface's background, instead of drawing another layer to the canvas.
79+
80+
#### Affected Components
81+
82+
The following is a list of Material components that support elevation overlays
83+
in Dark Theme, because they use `colorSurface` and can be elevated:
84+
85+
* Top App Bar
86+
* Bottom App Bar
87+
* Bottom Navigation
88+
* Tabs
89+
* Card
90+
* Dialog
91+
* Menu
92+
* Bottom Sheet
93+
* Navigation Drawer
94+
* Switch
95+
96+
#### Theme Attributes
97+
98+
In order to facilitate some orchestration around the elevation overlays, we have
99+
the following theme attributes:
100+
101+
Attribute Name |Description |Default Value
102+
-----------------------------|-------------------------------------------------------------------------------------|-------------
103+
`elevationOverlaysEnabled` |Whether the elevation overlay functionality is enabled. |`false` in Light Themes, `true` in Dark Themes
104+
`elevationOverlaysColor` |The color used for the elevation overlays, applied at an alpha based on elevation. |`colorOnSurface`
105+
106+
Note: If inheriting from the `Theme.MaterialComponents` theme or a descendant,
107+
you most likely do not have to set these attributes yourself because the
108+
Material themes already set up the above defaults.
109+
110+
#### Custom Views & Non-Material Components
111+
112+
If you would like to apply Dark Theme elevation overlays to your custom views or
113+
any non-Material views that are elevated surfaces, then you can use the
114+
`MaterialShapeDrawable` or `ElevationOverlayProvider` APIs.
115+
116+
##### MaterialShapeDrawable
117+
118+
The key to supporting elevation overlays in a custom view is creating a
119+
`MaterialShapeDrawable` with the overlay support enabled via
120+
`MaterialShapeDrawable#createWithElevationOverlay`, and setting it as the
121+
background of your view.
122+
123+
Next, override the `View#setElevation` method and forward the elevation passed
124+
in to your `MaterialShapeDrawable` background's `setElevation` method.
125+
126+
`MaterialShapeDrawable` is the preferred approach for custom views because it
127+
will keep track of the elevation value for you and factor that in to the overlay
128+
any time elevation changes, and you don't have to worry about incorrectly
129+
compounding the overlays multiple times.
130+
131+
##### ElevationOverlayProvider
132+
133+
If you have a case where the elevation value is more static and you would like
134+
to get the corresponding Dark Theme overlay color (perhaps to color an existing
135+
view), then you can use `ElevationOverlayProvider`.
136+
137+
If elevation overlays are enabled at the theme level, the
138+
`ElevationOverlayProvider#getSurfaceColorWithOverlayIfNeeded` method will return
139+
`colorSurface` with the overlay color blended in at an alpha level based on the
140+
elevation passed in. Otherwise, it will simply return `colorSurface`, so that
141+
you can use the result of this method in both Light and Dark Themes without
142+
needing any additional orchestration.
143+
144+
If you need to blend the overlays with an arbitrary color or an adjusted surface
145+
color, or get access to lower level values such as the overlay alpha
146+
percentages, take a look at the other `ElevationOverlayProvider` methods
147+
including `layerOverlayIfNeeded`, `layerOverlay`, and `calculateOverlayAlpha`.
148+
149+
[appcompat-daynight-docs]: https://medium.com/androiddevelopers/appcompat-v23-2-daynight-d10f90c83e94

0 commit comments

Comments
 (0)