Stay organized with collections
Save and categorize content based on your preferences.
The Wear Material 3 Expressive color system employs three accent layers
(primary, secondary, tertiary) for key components and two neutral surface
layers. Each role offers a range of values with consistent contrast, enabling
expressive yet accessible color combinations for a unified experience across any
theme.
An example of a color theme with roles.
What are color roles?
Color roles are like the "numbers" in a paint-by-number canvas. They're the
connective tissue between elements of the UI and what color goes where.
Color roles are mapped to Material components: You'll use these color
roles whether you're using the static baseline scheme or dynamic color. If
your product contains custom components, they'll need to be properly mapped
to this set of color roles.
Color roles support accessibility: The color system is built on more
accessible color pairings. These color pairs provide a minimum of 3:1 color
contrast.
Color roles are tokenized: Roles are implemented in design and code
through tokens. A design token represents a small, reusable design decision
that's part of a design system's visual style.
Essential terms
Here are key terms you'll see in the names of color roles:
Surface: A role used for backgrounds and large, low-emphasis areas of
the screen.
Primary, Secondary, Tertiary: Accent color roles used to emphasize or
de-emphasize foreground elements.
Container: Roles used as a fill color for foreground elements like
buttons. They shouldn't be used for text or icons.
On: Roles starting with this term indicate a color for text or icons on
top of its paired parent color. For example, on primary is used for text and
icons against the primary fill color.
Variant: Roles ending with this term offer a lower-emphasis alternative
to its non-variant pair. For example, outline variant is a less emphasized
version of the outline color.
Primary roles
Primary roles are used for key components across the UI, such as the Edge
Hugging buttons, prominent buttons, active states, and icons on the tonal button
styles.
Primary
Primary
On-Primary
Use the Primary role for the most important actions in the UI, like primary
buttons or calls to action. This color should stand out and be instantly
recognizable to guide the user toward key interactions.
Primary-Dim
Primary-Dim
On-Primary
Dim roles are typically used for elements that need to be visually distinct from
the primary action but don't require immediate user attention or interaction.
Primary-Container
Primary-Container
On-Primary-Container
Apply Primary Container for background elements like cards or modals to
highlight sections or selected states. It helps draw attention to important
content or ongoing activities within the UI.
Secondary roles
Secondary roles are used for key components across the UI, which are not as
important as the primary role, but still need to stand out. Primary and
secondary can be used together in layouts to create differentiation and focus.
Secondary
Secondary
On-Secondary
Use the Secondary role for supporting actions in areas with dense UI, such as
secondary buttons or complementary actions. It maintains visibility without
overshadowing primary elements in complex layouts.
Secondary-Dim
Secondary-Dim
Secondary
The Secondary-Dim role offers a muted contrast for passive elements in dense
areas. It complements the secondary color while adding subtle depth, keeping the
UI clean and helping users navigate.
Secondary-Container
Secondary-Container
On-Secondary-Container
Apply Secondary-Container for organizing secondary elements in dense layouts. It
creates structure and separation, ensuring secondary content is distinguishable
but not dominant.
Tertiary roles
Tertiary roles are used for contrasting accents to balance primary and secondary
colors or bring heightened attention to an element such as an input field.
Tertiary roles can also help indicate when content changes or should stand out,
such as a goal being reached.
Tertiary
Tertiary
On-Tertiary
The Tertiary role is used for drawing attention to key elements. Tertiary roles
are particularly effective for components that need to stand out, such as
badges, stickers, or special action elements.
Tertiary-Dim
Tertiary-Dim
Tertiary
Use the Tertiary Dim role for buttons or actions that are related to tertiary
actions yet don't require immediate focus.
Tertiary-Container
Tertiary-Container
On-Tertiary-Container
Apply Tertiary-Container for backgrounds that group tertiary-related content,
like collections of badges or stickers. It emphasizes tertiary elements while
maintaining balance and structure in the UI.
Semantic roles
Error-Red is used to indicate critical issues as error, delete, and anything
related to emergency. It is designed to draw immediate attention to problems or
warnings, ensuring users can quickly identify areas that need corrective action.
The tone of Error-Red should maintain sufficient contrast against backgrounds to
meet accessibility standards, ensuring it is clearly visible and is
distinguishable from other status colors like warnings or success messages.
Error
Error
On-Error
A semantic, yet slightly theme-tinted red, which indicates remove, delete, close
or dismiss actions, such as Swipe to Reveal. Added as a container alternative
that is slightly less alarming and urgent than the error-dim color.
Error-Dim
Error-Dim
On-Error
A semantic, yet slightly theme-tinted red, which indicates high priority errors
or emergency actions, such as safety alerts, failed dialog overlays or stop
buttons.
Error-Container
Error-Container
On-Error-Container
Less prominent container color, for components using the error state. Can also
indicate an active error state which feels less interactive than a filled state,
such as an active emergency sharing button or card, or on a failed overlay
dialog.
Surface containers and elevation
Surface containers are key in defining depth and elevation within the UI,
providing structure and hierarchy through color, helping to differentiate
components based on their importance and interaction.
Surface-Container-Low
Surface-Container-Low
On-Surface
On-Surface-Variant
Great for an expanded container that needs to sit below Surface-Container, such
as an expanded card in the Notification. Can also be used for non-interactive
cards, where content still benefits from containment.
Surface-Container
Surface-Container
On-Surface
On-Surface-Variant
The default container color for most elements. It provides a neutral, moderate
elevation, making it suitable for general UI components.
Surface-Container-High
Surface-Container-High
On-Surface
On-Surface-Variant
Ideal for high-emphasis components that need to sit on top of, or in combination
with Surface-Container. This color helps bring focus and hierarchy to critical
areas in the UI.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-05-20 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-05-20 UTC."],[],[],null,["# Color roles and tokens\n\nThe Wear Material 3 Expressive color system employs three accent layers\n(primary, secondary, tertiary) for key components and two neutral surface\nlayers. Each role offers a range of values with consistent contrast, enabling\nexpressive yet accessible color combinations for a unified experience across any\ntheme.\nAn example of a color theme with roles.\n\nWhat are color roles?\n---------------------\n\nColor roles are like the \"numbers\" in a paint-by-number canvas. They're the\nconnective tissue between elements of the UI and what color goes where.\n\n- **Color roles are mapped to Material components:** You'll use these color roles whether you're using the static baseline scheme or dynamic color. If your product contains custom components, they'll need to be properly mapped to this set of color roles.\n- **Color roles support accessibility:** The color system is built on more accessible color pairings. These color pairs provide a minimum of 3:1 color contrast.\n- **Color roles are tokenized:** Roles are implemented in design and code through tokens. A design token represents a small, reusable design decision that's part of a design system's visual style.\n\nEssential terms\n---------------\n\nHere are key terms you'll see in the names of color roles:\n\n- **Surface:** A role used for backgrounds and large, low-emphasis areas of the screen.\n- **Primary, Secondary, Tertiary:** Accent color roles used to emphasize or de-emphasize foreground elements.\n- **Container:** Roles used as a fill color for foreground elements like buttons. They shouldn't be used for text or icons.\n- **On:** Roles starting with this term indicate a color for text or icons on top of its paired parent color. For example, on primary is used for text and icons against the primary fill color.\n- **Variant:** Roles ending with this term offer a lower-emphasis alternative to its non-variant pair. For example, outline variant is a less emphasized version of the outline color.\n\nPrimary roles\n-------------\n\n\nPrimary roles are used for key components across the UI, such as the Edge\nHugging buttons, prominent buttons, active states, and icons on the tonal button\nstyles. \n\n\u003cbr /\u003e\n\n\n**Primary**\n\n1. Primary\n2. On-Primary\n\nUse the Primary role for the most important actions in the UI, like primary\nbuttons or calls to action. This color should stand out and be instantly\nrecognizable to guide the user toward key interactions. \n\n**Primary-Dim**\n\n1. Primary-Dim\n2. On-Primary\n\nDim roles are typically used for elements that need to be visually distinct from\nthe primary action but don't require immediate user attention or interaction. \n\n**Primary-Container**\n\n1. Primary-Container\n2. On-Primary-Container\n\nApply Primary Container for background elements like cards or modals to\nhighlight sections or selected states. It helps draw attention to important\ncontent or ongoing activities within the UI.\n\n\u003cbr /\u003e\n\nSecondary roles\n---------------\n\n\nSecondary roles are used for key components across the UI, which are not as\nimportant as the primary role, but still need to stand out. Primary and\nsecondary can be used together in layouts to create differentiation and focus. \n\n\u003cbr /\u003e\n\n\n**Secondary**\n\n1. Secondary\n2. On-Secondary\n\nUse the Secondary role for supporting actions in areas with dense UI, such as\nsecondary buttons or complementary actions. It maintains visibility without\novershadowing primary elements in complex layouts. \n\n**Secondary-Dim**\n\n1. Secondary-Dim\n2. Secondary\n\nThe Secondary-Dim role offers a muted contrast for passive elements in dense\nareas. It complements the secondary color while adding subtle depth, keeping the\nUI clean and helping users navigate. \n\n**Secondary-Container**\n\n1. Secondary-Container\n2. On-Secondary-Container\n\nApply Secondary-Container for organizing secondary elements in dense layouts. It\ncreates structure and separation, ensuring secondary content is distinguishable\nbut not dominant.\n\n\u003cbr /\u003e\n\nTertiary roles\n--------------\n\n\nTertiary roles are used for contrasting accents to balance primary and secondary\ncolors or bring heightened attention to an element such as an input field.\nTertiary roles can also help indicate when content changes or should stand out,\nsuch as a goal being reached. \n\n\u003cbr /\u003e\n\n\n**Tertiary**\n\n1. Tertiary\n2. On-Tertiary\n\nThe Tertiary role is used for drawing attention to key elements. Tertiary roles\nare particularly effective for components that need to stand out, such as\nbadges, stickers, or special action elements. \n\n**Tertiary-Dim**\n\n1. Tertiary-Dim\n2. Tertiary\n\nUse the Tertiary Dim role for buttons or actions that are related to tertiary\nactions yet don't require immediate focus. \n\n**Tertiary-Container**\n\n1. Tertiary-Container\n2. On-Tertiary-Container\n\nApply Tertiary-Container for backgrounds that group tertiary-related content,\nlike collections of badges or stickers. It emphasizes tertiary elements while\nmaintaining balance and structure in the UI.\n\n\u003cbr /\u003e\n\nSemantic roles\n--------------\n\n\nError-Red is used to indicate critical issues as error, delete, and anything\nrelated to emergency. It is designed to draw immediate attention to problems or\nwarnings, ensuring users can quickly identify areas that need corrective action.\nThe tone of Error-Red should maintain sufficient contrast against backgrounds to\nmeet accessibility standards, ensuring it is clearly visible and is\ndistinguishable from other status colors like warnings or success messages. \n\n\u003cbr /\u003e\n\n\n**Error**\n\n1. Error\n2. On-Error\n\nA semantic, yet slightly theme-tinted red, which indicates remove, delete, close\nor dismiss actions, such as Swipe to Reveal. Added as a container alternative\nthat is slightly less alarming and urgent than the error-dim color. \n\n**Error-Dim**\n\n1. Error-Dim\n2. On-Error\n\nA semantic, yet slightly theme-tinted red, which indicates high priority errors\nor emergency actions, such as safety alerts, failed dialog overlays or stop\nbuttons. \n\n**Error-Container**\n\n1. Error-Container\n2. On-Error-Container\n\nLess prominent container color, for components using the error state. Can also\nindicate an active error state which feels less interactive than a filled state,\nsuch as an active emergency sharing button or card, or on a failed overlay\ndialog.\n\n\u003cbr /\u003e\n\nSurface containers and elevation\n--------------------------------\n\n\nSurface containers are key in defining depth and elevation within the UI,\nproviding structure and hierarchy through color, helping to differentiate\ncomponents based on their importance and interaction. \n\n\u003cbr /\u003e\n\n\n**Surface-Container-Low**\n\n1. Surface-Container-Low\n2. On-Surface\n3. On-Surface-Variant\n\nGreat for an expanded container that needs to sit below Surface-Container, such\nas an expanded card in the Notification. Can also be used for non-interactive\ncards, where content still benefits from containment. \n\n**Surface-Container**\n\n1. Surface-Container\n2. On-Surface\n3. On-Surface-Variant\n\nThe default container color for most elements. It provides a neutral, moderate\nelevation, making it suitable for general UI components. \n\n**Surface-Container-High**\n\n1. Surface-Container-High\n2. On-Surface\n3. On-Surface-Variant\n\nIdeal for high-emphasis components that need to sit on top of, or in combination\nwith Surface-Container. This color helps bring focus and hierarchy to critical\nareas in the UI.\n\n\u003cbr /\u003e"]]
