Color and design guides

Pair Primary and On Primary in Material 3

·

Start with the role a color plays. A Material 3 button uses its background role and the corresponding On role for content. Treat the pinned baseline as a reproducible reference when checking both appearances.

Material Design Colors

Compare the Primary pair in light and dark themes

Choose Color roles. In Light, search for Primary and inspect the Primary swatch. Select Use as background. Inspect On Primary and check that its sample text is white on #6750A4. The measured contrast is approximately 6.44:1.

Switch Appearance to Dark. Inspect Primary and set it as the background again, then inspect On Primary. You should see #381E72 text over #D0BCFF. Use the corresponding On Primary Container role if your component instead uses Primary Container.

Compare the Primary pair in light and dark themes
AppearancePrimaryOn Primary
Light#6750A4#FFFFFF
Dark#D0BCFF#381E72

Open Material Design ColorsMaterial Components Android 1.12.0 color tokensMaterial Components color role mappingW3C guidance on text contrast

Find which tones supply the two appearances

Clear the search and choose Tonal palettes. Choose the Primary category and inspect Primary 40 and Primary 80. They match the light and dark Primary roles, respectively. Tone values stay constant when you switch Appearance because the roles draw from the same reference palette.

Inspect a Fixed role to find a role intended to use the same value across appearances. Choose a semantic role for application controls when the theme can change.

Material Components Android 1.12.0 color tokensMaterial Components color role mapping

Export the roles for a fixed theme

Return to Color roles and choose the Primary category. Download CSS to get the visible role identifiers and their values for the active appearance. Download JSON to keep the original library version, appearance and source link.

Shadow and Scrim use tone zero from the neutral palette in the Material web token map. A wallpaper-derived scheme can use different values. Test the resolved pair in the app when it supports dynamic color.

Material Components Android 1.12.0 color tokensMaterial Color Utilities dynamic schemesOpen Material Design ColorsMaterial web token mapping for shadow and scrim

Common questions

Why does the surface color differ across Material libraries?

The reference uses Material Components for Android 1.12.0. Other releases may ship different baseline values. Dynamic color can also replace the baseline.

Should I use On Primary on Primary Container?

Use the matching On Primary Container role. The pair identifies the intended foreground and background together.

Sources

Put it into practice.

Related guides