Pair Primary and On Primary in Material 3
Admin ·
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.
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.
| Appearance | Primary | On 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.