Material You has redefined customization on Android Since Android 12, we've been bringing system color and theme to a much more expressive and coherent level. This practical and detailed guide shows you how to change the theme and dynamic palette, how color extraction works, and how to properly integrate it at both the system and app levels.
In addition to delving into the dynamic colors, movement and widgets, you'll learn how to prepare your app for Material Design 3, how to use Material Theme Builder for Figma, and what changes to make in Android 12 and 13. You'll also find answers to frequently asked questions, recommendations for OEMs, and keynotes for developers.
What is Material You and why does it matter?
Material You (Material Design 3) It's the design language that focuses on expression, fluidity, and consistency across the ecosystem. It maintains a minimalist approach (fewer shadows, cleaner fonts, softer shapes) and provides each user with a unique experience that adapts to their context and preferences.
This approach doesn't stop with the Pixels; It extends to mobile phones from Samsung, OnePlus, OPPO, Vivo, realme, and Xiaomi., tablets, watches, and other devices. Its goal is to combine deep customization with accessibility, visual consistency, and a modern motion system.
Dynamic color: the centerpiece
Dynamic color is at the heart of Material You: extracts a source color from the wallpaper or a chosen color, expands it to 5 tonal palettes with 13 shades each (65 colors in total) and applies it harmoniously across the system and apps.
To ensure consistency, It is recommended to use the unmodified AOSP extraction logic and maintain alignment with the 65 color attributes. This way, users and developers find a stable and powerful customization experience on any Android device.
How Dynamic Color Flow Works
The complete flow consists of four steps very clear, with color extraction and propagation at the center of the process:
- The user changes the wallpaper or selects a theme from the OEM's theme selector. That trigger activates the palette recomputation.
- The user chooses between different options: device theme (Android automatically selects a valid seed color) or new wallpaper and theme (AOSP extracts the seed color from the wallpaper).
- AOSP takes the single seed color and expands it into 5 tonal palettes (A1, A2, A3, N1, N2), each with 13 levels, thus propagating the 65 color attributes by the system.
- The system UI and apps apply those 65 attributes consistently. Recommendation: Use the same palette in both SysUI and OEM apps for a cohesive experience.
Algorithm details: tones, chromas and consistency
Material You uses CAM16-based transformations to ensure harmony and contrast. The seed color must have a minimum chroma of 5 in CAM16 (to prevent very dark tones from ruining the tonal expansion). You can read/write CAM16 with utilities like Cam#fromInt or Cam#getInt.
Specific chroma and tone rules apply to each tonal palette: accent1 (chroma 40 at 0, 10, 50 and 100; 48 in the rest, tone equal to that of the seed), accent2 (chroma 16, same tone), accent3 (chroma 32, hue rotated +60 degrees), neutral1 (chroma 4) and neutral2 (chroma 8), with the same tone as the seed.
Compatibility, Testing, and AOSP
Android 12L and later now include dynamic color as standard.Android 12 integrates the necessary patches to support end-to-end logic (fetching and propagating to the 65 APIs). The CTS validates luminance and hue; you can run it with atest SystemPalette.
If your device does not support wallpaper extraction, you can disable flag_monet and offer a theme selector with predefined palettes, ensuring customization without dynamic color.
AOSP ThemePicker: Custom Colors and APK Stub
If you use the AOSP ThemePicker, the color section appears if flag_monet is enabled and there's a system stub APK declared in the themes_stub_package value. The stub only contains the resources for the basic colors and their names.
The stub structure includes an XML in res/xml with the array of color packages (e.g. color1, color2, etc.) and bundle_name_colorX strings. Additionally, you must define the values ​​for each basic color as primary/secondary pairs (for example, color_primary_color1 and color_secondary_color1) and both must be the same color.
Recommended integration steps
Step 1: User Theme Experience
Offers a theme or wallpaper selector tailored to your product. With the wallpaper selector, extraction is active by default., but you can add more options for the user if you wish.
Step 2: Seed color extraction
In Android 12, the activation route in SysUI is ThemeOverlayController (mOnColorsChangedListener) via WallpaperManager#onWallpaperColorsChanged. Use ColorScheme#getSeedColors to expose multiple seeds on the selector, not just the highest frequency.
Requires CAM16 chroma ≥ 5 for the seed color to be valid. If there are no valid seeds, use a backup one according to the guide. and preserves consistency of tone and contrast.
Step 3: Expand to 65 APIs
With the seed color, Android generates the 5 palettes and 13 tonal steps per palette (0, 10, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000). Apply Android 12 patch logic to properly expand and comply with CTS and CDD.
Step 4: Use in apps and system UI
Integrate Material You into your own apps and SysUI. Material guides explain how to map roles and tokens so that components adopt dynamic colors, maintaining accessibility and readability.
Step 5: Options in WallpaperPicker (Android 13+)
Since Android 13, accent_color is no longer available and android.theme.customization.theme_style was added, with styles like TONAL_SPOT, VIBRANT, EXPRESSIVE, and SPRITZ. At least 'android.theme.customization.system_palette' is sent in the Settings.Secure.THEME_CUSTOMIZATION_OVERLAY_PACKAGES JSON.
Configuration example: { 'android.theme.customization.system_palette':'B1611C', 'android.theme.customization.theme_style':'EXPRESSIVE' }. In Android 12 and earlier, 'system_palette' and 'accent_color' were used with the same seed color code.
Step 6: Add to the allowed list
Submit a ticket with your Build.MANUFACTURER so that apps based on Material Components can recognize the availability of dynamic palettes on your devices. This ensures a consistent experience for third parties.
System theme styles and tonal palettes
Android 13 adds algorithm variations for contrast and expression needs: TONAL_SPOT (default), VIBRANT (high subtle intensity), EXPRESSIVE (high intensity with unexpected accents), SPRITZ (low intensity, desaturated appearance), RAINBOW y FRUIT SALAD (designed for static themes, not recommended for extraction from wallpaper).
Dynamic tonal palettes are exposed as resources in R.color with names like system_accent1_10 up to 13 indices. The system generates the hue and chroma at runtime from the seed.
Mappings of roles and topic attributes
Material 3 defines a set of roles that are assigned to Android theme attributes, with variations for light and dark themeSome key examples (summarized):
| Role | Attribute | Clear | Dark |
|---|---|---|---|
| Home | colorPrimary | system_accent1_600 | system_accent1_200 |
| On main | colorOnPrimary | system_accent1_0 | system_accent1_800 |
| Secondary | colorSecondary | system_accent2_600 | system_accent2_200 |
| On secondary | colorOnSecondary | system_accent2_0 | system_accent2_800 |
| Background | android:colorBackground | system_neutral1_10 | system_neutral1_900 |
| On background | colorOnBackground | system_neutral1_900 | system_neutral1_100 |
| In total area | colorSurface | system_neutral1_10 | system_neutral1_900 |
| On the surface | colorOnSurface | system_neutral1_900 | system_neutral1_100 |
There is also state attributes (e.g., colorPrimaryStateContent, colorOnSurfaceVariantStateLayer) that are derived from the same roles, ensuring consistency across pressed, focused, or disabled states.
Movement: displacement and wave
Fluid motion brings a premium product feel. Android 12 debuted a overscroll with stretch that reacts when trying to scroll beyond the limit of a list.
Consistency Guidelines: On devices with ActivityManager.isHighEndGfx() true, uses non-linear stretching; on more modest hardware, it simplifies to linear stretching to reduce load.
To support horizontal scrolling in custom views, updates the libraries latest: androidx.recyclerview:recyclerview 1.3.0-alpha01, androidx.core 1.7.0-alpha01 (NestedScrollView and EdgeEffectCompat), and androidx.viewpager 1.1-alpha01.
In designs with EdgeEffect, while stretching the view, you should not interact with the content; capturing the animation and manipulating the stretch is done with EdgeEffectCompat.getDistance() and onPullDistance(). In nested pulls, the stretch must first consume the gesture to avoid unwanted movement.
La tactile wave (Ripple) on Android 12 is smoother and more subtle. It doesn't require additional integration, but it's worth checking for device-specific regressions.
Widgets: APIs and Updates
Widgets are key in Android, and with Android 12, APIs for size, layout, and parameters such as corner radiusYour OS must properly expose these APIs and allow resizing and configuring widgets.
In your own apps, take advantage of the new features to update or create widgetsPrioritizing them according to the platform guidelines improves consistency with Material You.
Design with Material Theme Builder and tokens
Material Theme Builder (Figma and web version) makes it easy to create accessible branding themes and combine them with dynamic color. It allows you to define key colors (primary, secondary, tertiary, neutral) and generates light/dark tonal palettes, tokens, and code exports.
Los design tokens replace static values ​​with semantic names, creating a common language between design and development. You can extend the scheme with custom colors (e.g., Custom0) for specific semantics or products, without breaking the system.
Color hierarchy matters: More saturated tones attract more attention, so reserve the primary for calls to action, and use secondary/tertiary to balance and direct the eye.
Figma Codelab: Essential Steps
Log in or create an account in Figma, duplicate the lab file and Install the Material Theme Builder pluginThe document is organized into sections with sequential concepts and exercises; follow the order to understand the roles, tokens, and application of the topic.
Enter your brand's primary color; the other colors will follow. Add secondary and tertiary for more color expression. Assign neutrals to surfaces and text. Switch to the theme in the plugin panel and apply styles to custom components if needed.
To expand beyond the central outline, add custom colors (Custom#) from the plugin modal. You can rename them in Figma's Styles panel and assign them to specific tags or components.
Update an Android app to Material 3
Before applying dynamic color, updates dependencies (com.google.android.material in recent versions), and use compileSdkVersion/targetSdkVersion 31 or higher. Change the base theme from Theme.MaterialComponents.* to Theme.Material3.*.
Check that the inherited attributes still make sense and migrate custom styles which now exist as standard in M3. You can generate a complete theme with Material Theme Builder and copy values/colors.xml and values-night/themes.xml, adjusting the theme name.
If you're targeting Android 12, remember to declare android:exported explicitly in your main AndroidManifest activity, to meet system requirements.
Apply dynamic color in the app
With the Material 3 theme in use, enable dynamic colors globally with DynamicColors.applyToActivitiesIfAvailable in your Application class. This registers ActivityLifecycleCallbacks and applies the system-generated ThemeOverlay.
If you need to force brand nuances, define a theme overlap (ThemeOverlay.Material3.DynamicColors.Light/Dark/DayNight) assigning colorPrimary, onPrimary, primaryContainer and onPrimaryContainer to your shades, and passing it as the second parameter to applyToActivitiesIfAvailable.
For custom attributes (e.g., your own iconColor), reference system palettes like @android:color/system_accent2_600 in your overlay. Place resources in -v31 folders if your minSdk is less than 31.
Seed color sources and accessibility
The seed can come from the wallpaper (quantization), the content of your app, or a color chosen by the user. The system manipulates tone and chroma to generate five key colors and their palettes. The goal is to maintain high contrast and legibility, including support for dark mode and varying contrast levels.
If you already have very defined brand colors, you can enter them in Theme Builder to generate accessible and consistent palettes with M3. There's also a viewer to check results with different images.
Ecosystem compatibility and tools
Google confirmed the arrival of the dynamic colors to layers like One UI, OxygenOS, ColorOS, OriginOS, and MIUI, offering a consistent experience across manufacturers. Even Gmail adapts its look across several flagship models.
If you don't have a compatible device on hand, try dynamic themes in the browser With Material Theme Builder, you can upload your own background to see the resulting palette.
Practical note: some third-party theming tools may conflict with the system paletteIf your custom theme disables or forces a palette option, check overlay priorities and OEM settings.
FAQs
Does color extraction activate automatically when changing the wallpaper? With Android 12 patches, yes: ThemeOverlayController#mOnColorsChangedListener via WallpaperManager handles the event automatically.
What about live or video backgrounds? Extraction is applied when setting the wallpaper or after a screen power cycle; the latest WallpaperColors event It is applied upon restart.
Can I display multiple seeds in the picker? Yes, use ColorScheme#getSeedColors to list options other than the most frequent one.
What about thematic icons? They were not part of Android 12 stable. They were not included in the patches mentioned for that version.
Can I use the Google Wallpaper app with color preview? Yes, following the indicated integration. WallpaperPicker2 and Launcher3 render the preview; WallpaperSectionController manages the display, and GridCustomizationsProvider exposes data via ContentProvider.
Foldable Devices: Design Considerations
With foldable screens, ergonomics change: The top 25% can be difficult to reach When deployed, it distributes content based on convenient reach and relevance.
Avoid placing critical controls on the center hingeIt is suggested to reserve about 48 dp around that area so as not to hinder interaction.
In landscape, place the main navigation on the left and distribute content in two columns, adjusting the hinge spacing. In portrait, prioritize a wide column to preserve legibility.
Implementation keys in Android 13 and 12
On Android 13, set Settings.Secure.THEME_CUSTOMIZATION_OVERLAY_PACKAGES to system_palette and, optionally, the theme_style (TONAL_SPOT, VIBRANT, EXPRESSIVE, SPRITZ, or others oriented to static themes).
On Android 12 and earlier, if you use a custom theme picker, send the same setting a JSON with system_palette and accent_color equal to skip the extraction in step 2 and expand directly to step 3.
Material You allows for deep, yet controlled, customizationYou can choose automatic extraction from the background or from brand colors, always ensuring contrast, legibility, and consistency. Properly integrated (AOSP/CTS/overlays), dynamic color improves the UX without disrupting the visual identity and opens the door to more personal experiences across the Android ecosystem. Share the guide and more users will know how to use Material You to customize Android..