Skip to content


[M3][Color] Update Color doc
Browse files Browse the repository at this point in the history
PiperOrigin-RevId: 532459188
  • Loading branch information
Material Design Team authored and imhappi committed May 16, 2023
1 parent a511501 commit d7f9a06
Showing 1 changed file with 115 additions and 0 deletions.
115 changes: 115 additions & 0 deletions docs/theming/
Expand Up @@ -615,3 +615,118 @@ or
ColorRoles colorRoles = MaterialColors.getColorRoles(color, /* isLightTheme= */ booleanValue);

## Content-based Dynamic Colors

Content-based color describes the color system’s capability to generate and
apply a color scheme based on in-app content. In-app content colors can be
derived from a range of sources, such as album artwork, a brand logo, or a video

##### *Use Content-based Dynamic Colors*

A single source color is extracted from a bitmap and then used to derive five
key colors. Specific tones are mapped into specific color roles that are then
mapped to Material components.

During this process, chroma fidelity enables Material colors to flex to
consistently achieve desired chroma, whether high or low. It maintains color
schemes’ integrity, so existing products will not break. A content scheme then
produces the range of tones needed for both light and dark theme applications.

We have provided the following two APIs in the `DynamicColorsOptions` class.

API Method | Description
------------------------------ | ---------------------------------------
#setContentBasedSource(Bitmap) | Provides a Bitmap from which a single source color is extracted as input
#setContentBasedSource(int) | Provides a single source color as input

An example usage for applying content-based dynamic colors to a specific
activity can be seen below. Since we are overriding color resources in xml at
runtime, make sure the method is invoked before you inflate the view to take

protected void onCreate(Bundle savedInstanceState) {
// Invoke before the view is inflated in your activity.
new DynamicColorsOptions.Builder()

An example usage for applying content-based dynamic colors to a specific

public View onCreateView(LayoutInflater layoutInflater, ViewGroup viewGroup, Bundle bundle) {
Context context = DynamicColors.wrapContextIfAvailable(
new DynamicColorsOptions.Builder()
return layoutInflater.cloneInContext(context).inflate(, viewGroup, false);

This method will return a context with a content-based dynamic colors theme
overlay applied, if Dynamic Colors are available on the device.

**Important:** Please note that this feature is only available for S+.

## Contrast Control

Tone quantifies the lightness or darkness of colors. It's one foundational
dimension of the Material color system and schemes. The difference in tone
between two colors creates visual contrast. A greater difference creates higher
contrast. Color contrast control allows users to adjust their UI contrast levels
in the system so they can comfortably see and use digital experiences.

##### *Use Contrast Control - non-Dynamic*

If you are not using dynamic colors and would like to use contrast control for
your branded or custom themes, we have created the following API in the
`ColorContrast` class that you can call manually.

*Apply contrast to all activities in the app*

In your application class’ `onCreate()` method, call:

new ColorContrastOptions.Builder()

Note that if you want contrast support for both light and dark theme, then for
`mediumContrastThemeOverlayResId` and `highContrastThemeOverlayResId`, you
should pass in a DayNight theme, which will help facilitate easy switching
between your app’s Light and Dark theme.

##### *Use Contrast Control - Custom Colors*

If you have custom colors in your app that would like to obey contrast changes
from the system, whether or not you are using dynamic colors, they should be
included in the abovementioned theme overlays for medium and high contrast
support. To make your custom colors obey contrast for all activities in the app,
please refer to the API from the section above.

0 comments on commit d7f9a06

Please sign in to comment.