Skip to content
Material Design 3
Main Navigation
v3
v2
v1

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

Appearance

Sidebar Navigation

Foundations

Accessibility

Overview: Principles

Overview: Assistive technology

Designing: Overview

Designing: Color contrast

Designing: Structure

Designing: Flow

Designing: Elements

Writing and text: Best practices

Writing and text: Text truncation

Writing and text: Text resizing

Building for all: User needs

Building for all: Co-design

Content design

Overview

Alt text

Global writing: Overview

Global writing: Word choice

Notifications

Style guide: UX writing best practices

Style guide: Word choice

Style guide: Grammar and punctuation

Customizing Material

Devices

Watches: Overview

Watches: Foundations

Watches: Styles

Watches: Layout

XR

Design: Overview

Design: Interaction

Design: Layout

Design: Accessibility

Components: Overview

Components: App bars

Components: Dialogs

Components: Nav bar

Components: Nav rail

Components: Toolbars

Design tokens: Overview

Design tokens: How to use tokens

Interaction

Gestures

Inputs

Selection

States: Overview

States: State layers

States: Applying states

Layout

Overview: Overview

Overview: Parts of layout

Overview: Adaptive design

Scaffold: Overview

Scaffold: Bars

Scaffold: Rails

Scaffold: Panes

Grids & spacing: Overview

Grids & spacing: Grids

Grids & spacing: Spacing

Grids & spacing: Density

Breakpoints: Overview

Breakpoints: Compact

Breakpoints: Medium

Breakpoints: Expanded

Breakpoints: Large & extra-large

Bidirectionality & RTL

Canonical examples: Overview

Canonical examples: Feed

Canonical examples: List-detail

Canonical examples: Supporting pane

Usability: Overview

Usability: Applying M3 Expressive

Material A-Z

Styles

Color

Color system: Overview

Color system: How the system works

Color roles

Color schemes

Choosing a scheme

Static: Baseline

Static: Custom brand

Dynamic: Choosing a source

Dynamic: User-generated source

Dynamic: Content-based source

Advanced: Overview

Advanced: Apply colors

Advanced: Define new colors

Advanced: Adjust existing colors

Color resources

Elevation: Overview

Elevation: Applying elevation

Elevation: Tokens

Icons: Overview

Icons: Designing icons

Icons: Applying icons

Motion

Motion physics system: How it works

Motion physics system: Specs

Easing and duration: Applying easing and duration

Easing and duration: Tokens & specs

Transitions: Transition patterns

Transitions: Applying transitions

Shape: Overview & principles

Shape: Corner radius scale

Shape: Shape morph

Spacing: Overview

Spacing: Applying spacing

Spacing: Tokens

Typography: Overview

Typography: Fonts

Typography: Type scale & tokens

Typography: Applying type

Typography: Editorial treatments

Components

App bars: Overview

App bars: Specs

App bars: Guidelines

App bars: Accessibility

Badges: Overview

Badges: Specs

Badges: Guidelines

Badges: Accessibility

Buttons

All buttons

Button groups: Overview

Button groups: Specs

Button groups: Guidelines

Button groups: Accessibility

Buttons: Overview

Buttons: Specs

Buttons: Guidelines

Buttons: Accessibility

Extended FABs: Overview

Extended FABs: Specs

Extended FABs: Guidelines

Extended FABs: Accessibility

FAB menu: Overview

FAB menu: Specs

FAB menu: Guidelines

FAB menu: Accessibility

FABs: Overview

FABs: Specs

FABs: Guidelines

FABs: Accessibility

Icon buttons: Overview

Icon buttons: Specs

Icon buttons: Guidelines

Icon buttons: Accessibility

Segmented buttons: Overview

Segmented buttons: Specs

Segmented buttons: Guidelines

Segmented buttons: Accessibility

Split button: Overview

Split button: Specs

Split button: Guidelines

Split button: Accessibility

Cards: Overview

Cards: Specs

Cards: Guidelines

Cards: Accessibility

Carousel: Overview

Carousel: Specs

Carousel: Guidelines

Carousel: Accessibility

Checkbox: Overview

Checkbox: Specs

Checkbox: Guidelines

Checkbox: Accessibility

Chips: Overview

Chips: Specs

Chips: Guidelines

Chips: Accessibility

Date & time pickers

Date pickers: Overview

Date pickers: Specs

Date pickers: Guidelines

Date pickers: Accessibility

Time pickers: Overview

Time pickers: Specs

Time pickers: Guidelines

Time pickers: Accessibility

Dialogs: Overview

Dialogs: Specs

Dialogs: Guidelines

Dialogs: Accessibility

Divider: Overview

Divider: Specs

Divider: Guidelines

Divider: Accessibility

Lists: Overview

Lists: Specs

Lists: Guidelines

Lists: Accessibility

Loading & progress

Loading indicator: Overview

Loading indicator: Specs

Loading indicator: Guidelines

Loading indicator: Accessibility

Progress indicators: Overview

Progress indicators: Specs

Progress indicators: Guidelines

Progress indicators: Accessibility

Menus: Overview

Menus: Specs

Menus: Guidelines

Menus: Accessibility

Navigation

Navigation bar: Overview

Navigation bar: Specs

Navigation bar: Guidelines

Navigation bar: Accessibility

Navigation drawer: Overview

Navigation drawer: Specs

Navigation drawer: Guidelines

Navigation drawer: Accessibility

Navigation rail: Overview

Navigation rail: Specs

Navigation rail: Guidelines

Navigation rail: Accessibility

Radio button: Overview

Radio button: Specs

Radio button: Guidelines

Radio button: Accessibility

Search: Overview

Search: Specs

Search: Guidelines

Search: Accessibility

Sheets

Bottom sheets: Overview

Bottom sheets: Specs

Bottom sheets: Guidelines

Bottom sheets: Accessibility

Side sheets: Overview

Side sheets: Specs

Side sheets: Guidelines

Side sheets: Accessibility

Sliders: Overview

Sliders: Specs

Sliders: Guidelines

Sliders: Accessibility

Snackbar: Overview

Snackbar: Specs

Snackbar: Guidelines

Snackbar: Accessibility

Switch: Overview

Switch: Specs

Switch: Guidelines

Switch: Accessibility

Tabs: Overview

Tabs: Specs

Tabs: Guidelines

Tabs: Accessibility

Text fields: Overview

Text fields: Specs

Text fields: Guidelines

Text fields: Accessibility

Toolbars: Overview

Toolbars: Specs

Toolbars: Guidelines

Toolbars: Accessibility

Tooltips: Overview

Tooltips: Specs

Tooltips: Guidelines

Tooltips: Accessibility

On this page

Color roles ​

There are 26 standard color roles organized into six groups: primary, secondary, tertiary, error, surface, and outline

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 schemeBaseline is the default static color scheme for Material products. It includes colors for both light and dark themes.More on baseline color or dynamic colorDynamic color takes a single color from a user's wallpaper or in-app content and creates an accessible color scheme assigned to elements in the UI.More on dynamic color. If your product contains custom components, they'll need to be properly mapped to this set of color roles.
  • Color roles ensure accessibility
    The color system is built on accessible color pairingsFor example, a dark surface color is algorithmically paired with a light text label color so the UI automatically meets contrast requirements.More on color relationships. These color pairs provide an accessible minimum 3:1 contrast.
  • Color roles are tokenized
    Roles are implemented in design and code through tokens. A design tokenDesign tokens are the building blocks of all UI elements. The same tokens are used in designs, tools, and code.More on design tokens represents a small, reusable design decision that's part of a design system's visual style.

Example color swatches for all 45 color roles including Primary, Secondary, Tertiary, Error, Surfaces, Inverse
Diagram of all Material color roles, including optional add-on roles for surface colors and fixed accent colors

General concepts ​

Here are helpful-to-know words 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 should not 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.

Pairing and layering colors

To ensure accessible visual contrast in your app, apply colors only in the intended pairs or layering orders described in the following sections.

Combining colors improperly may break contrast necessary for visual accessibility, particularly when colors are adjusted through dynamic colorDynamic color takes a single color from a user's wallpaper or in-app content and creates an accessible color scheme assigned to elements in the UI.More on dynamic color features such as user-controlled contrastUser-controlled contrast is a dynamic color feature enabling users to choose from one of three levels of color contrast: standard, medium, and high.More on user-controlled contrast.

Pair of buttons shown at three different contrast levels. At every level, the text on the button is legible because the correct color roles are used.
Do Pair and layer color roles as intended to ensure expected visual results and accessibility. In this example, the two buttons mapped with (1) primary, (2) on primary, (3) secondary container, and (4) on secondary container stay legible as the contrast level changes.
Pair of buttons shown at 3 different contrast levels. The text on the button becomes illegible because the color roles are improperly paired.
Don't Improper color mappings can produce unintended visual results and break accessibility. In this example, the two buttons mapped with (1) primary, (2) primary container, (3) secondary container, and (4) on surface become illegible as the contrast level changes.

Accent color roles ​

Accent color roles include primary, secondary, and tertiary. Assign them to elements in the UI based on importance and needed emphasis. Use caution when changing color roles for visual effect.

  • Primary roles are for important actions and elements needing the most emphasis, like a FAB to start a new message.
  • Secondary roles are for elements that don't need immediate attention and don't need emphasis, like the selected state of a navigation icon or a dismissive button.
  • Tertiary roles are for smaller elements that need special emphasis but don't require immediate attention, such as a badge or notification.
A mail app showing a mix of primary, secondary, and tertiary accent colors used across the screen.
  1. Primary colors are used for the most important elements, like a starred message and FAB to start a new message
  2. Tertiary colors are used for smaller emphasized elements, like a badge suggesting a follow up
  3. Secondary colors are used for less urgent elements, like the background of an inactive star icon and the selection state of an inbox icon

Primary ​

Use primary roles for the most prominent components across the UI, such as the FAB, high-emphasis buttons, and active states.

  • Primary: High-emphasis fills, texts, and icons against surface
  • On primary: Text and icons against primary
  • Primary container: Standout fill color against surface, for key components like FAB
  • On primary container: Text and icons against primary container
4 color swatches: primary, on primary, primary container and on primary container.
Primary color roles include primary and primary container, with their respective "On" colors
Primary color used for filled button, and "on primary" color used for the text within that button.
  1. On primary
  2. Primary
"Primary container" color used for FAB and "on primary container" color used for the text and icon within.
  1. On primary container
  2. Primary container

Secondary ​

Use secondary roles for less prominent components in the UI such as filter chips.

There are four secondary roles:

  • Secondary: Less prominent fills, text, and icons against surface
  • On secondary: Text and icons against secondary
  • Secondary container: Less prominent fill color against surface, for recessive components like tonal buttons
  • On secondary container: Text and icons against secondary container
4 color swatches: secondary, on secondary, secondary container, and on secondary container.
Secondary color roles include secondary and secondary container, with their respective "On" colors
An icon button using "secondary container" color, and an icon using "on secondary color."
  1. Icon: On secondary container
  2. Button: Secondary container

Tertiary ​

Use tertiary roles for contrasting accents that balance primary and secondary colors or bring heightened attention to an element such as an input field.

There are four tertiary roles:

  • Tertiary: Complementary fills, text, and icons against surface
  • On tertiary: Text and icons against tertiary
  • Tertiary container: Complementary container color against surface, for components like input fields
  • On tertiary container: Text and icons against tertiary container
4 color swatches: tertiary, on tertiary, tertiary container, and on tertiary container.
Tertiary color roles include tertiary and tertiary container, with their respective "On" colors

The tertiary color roles can be applied at the designer's discretion. They're intended to support broader color expression.

A selected element using Tertiary Container as a background color and On Tertiary Container for text.
  1. On tertiary container
  2. Tertiary container

Error ​

Use error roles to communicate error states, such as an incorrect password entered into a text field.

There are four error roles:

  • Error: Attention-grabbing color against surface for fills, icons, and text, indicating urgency
  • On error: Text and icons against error
  • Error container: Attention-grabbing fill color against surface
  • On error container: Text and icons against error container

Error is an example of a static color (it doesn't change even in dynamic color schemes). Error color roles are made static by default with any dynamic color scheme. They still adapt to light and dark theme.

4 color swatches: Error, On error, Error container and On error container roles.
Error color roles include error and error container with their respective "On" colors.

Surface ​

Use surface roles for more neutral backgrounds, and container colors for components like cards, sheets, and dialogs.

There are three surface roles:

  • Surface: Default color for backgrounds
  • On surface: Text and icons against any surface or surface container color
  • On surface variant: Lower-emphasis color for text and icons against any surface or surface container color
3 color swatches: Surface, On surface and On surface variant.
Surface and on surface roles in light theme

There are also five surface container roles named based on their level of emphasis:

  • Surface container lowest: Lowest-emphasis container color
  • Surface container low: Low-emphasis container color
  • Surface container: Default container color
  • Surface container high: High-emphasis container color
  • Surface container highest: Highest-emphasis container color

Surface container is the default role, but the others are especially helpful for creating hierarchy and nested containers in layouts for expanded screens.

The five surface container roles, shown in light and dark theme

The most common combination of surface roles uses surface for a background area and surface container for a navigation area.

Text and icons typically use on surface and on surface variant on all types of surfaces.

Email app using Surface for the main background color and Surface Container for the navigation bar background.
  1. Surface
  2. Surface container

All color mappings – but especially surface colors – should remain the same for layout regions across breakpointsBreakpoints are opinionated window sizes where a layout changes to match available space, device conventions, and ergonomics (previously window size classes).More on breakpoints. For example, the body area will use the surface color and the navigation area will use the surface container color on both mobile and tablet.

Mobile and tablet screens both using Surface for main background and surface container for navigation background.
  1. Surface
  2. Surface container

Depending on necessary hierarchy, feature area, and design logic, you can use add-on surface colors in larger window class sizes as long as colors are consistently applied.

In this example, the body and navigation regions have the same color roles across breakpoints (surface and surface container, respectively) with the addition of other surface container colors at larger sizes.

By default, neutral-colored components such as navigation bars, menus, or dialogs are mapped to specific surface container roles, but these roles can be remapped by makers to suit user needs.

Surface container low applied to an elevated button and card, surface container applied to the top and bottom app bars, surface container high applied to a navigation drawer, and surface container highest applied to a dialog.

Default surface container roles applied to components:

  1. Surface container low
  2. Surface container
  3. Surface container high
  4. Surface container highest

Inverse colors

Inverse roles are applied selectively to components to achieve colors that are the reverse of those in the surrounding UI, creating a contrasting effect.

  • Inverse surface: Background fills for elements which contrast against surface
  • Inverse on surface: Text and icons against inverse surface
  • Inverse primary: Actionable elements, such as text buttons, against inverse surface
3 color swatches: Inverse surface, inverse on surface and inverse primary roles.
Inverse surface, inverse on surface, and inverse primary roles in the color scheme, shown in light theme
Snackbar component using inverse surface for its background, inverse on surface for its text and inverse primary for its text button.

A snackbar which uses:

  1. Inverse surface for its background
  2. Inverse on surface for its text
  3. Inverse primary for its text button

Outline ​

There are two outline colors to be used against a surface:

  • Outline: Important boundaries, such as a text field outline
  • Outline variant: Decorative elements, such as dividers, and when other elements provide 4.5:1 contrast
2 color swatches: Outline and outline variant
Outline and outline variant roles in the color scheme, shown in light theme
Diagram comparing used of outline and outline variant.
  1. A text field which uses outline for its container border
  2. A list item which uses outline variant for its divider line
Outline color incorrectly used for dividers
Don't Don't use the outline color for dividers since they have different contrast requirements. Instead, use outline variant.
Outline color incorrectly used for cards.
Don't Don't use the outline color for components that contain multiple elements, such as cards. Instead, use outline variant.
Outline variant color incorrectly used for input and filter chips.
Don't Don't use the outline variant color to create visual hierarchy or define the visual boundary of targets. Instead, use the outline color or another color providing 3:1 contrast with the surface color.
Outline variant incorrectly color used for chips.
Caution The outline variant color can be used for the border of targets like chips and buttons, provided that those targets contain elements inside them that provide visual contrast. In this example of chips and buttons, the icons and text inside the targets meet 4.5:1 contrast.

Add-on color roles ​

Most products won't need to use these add-on color roles. However, some products require the greater flexibility and control that add-on roles provide. If you aren't sure whether your product should use the add-on roles, it probably shouldn't and you can ignore them.

Fixed accent colors

Primary fixed, secondary fixed, and tertiary fixed are fill colors used against surface. These colors maintain the same tone in light and dark themes, as opposed to regular container colors, which change in tone between these themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.

The primary fixed dim, secondary fixed dim, and tertiary fixed dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color. They may be used where a deeper color but the same fixed behavior is desired.

6 color swatches: Primary, secondary and tertiary fixed swatches, along with their darker Dim counterparts, shown in light and dark themes.
Fixed and fixed dim color roles for the primary, secondary, and tertiary color groups, shown in both light and dark themes. Note how the colors stay the same between themes.
FAB in light and dark theme, using the primary fixed role for its container fill color.
A FAB which uses primary fixed (1) for its container fill color, shown in light and dark themes. Note how the container color stays the same between themes.
FAB in light and dark theme, using the primary container role for its container fill color.
For comparison, a FAB which uses primary container (2) for its container fill color, shown in light and dark themes. Note how the container color changes tone between themes.
2 email app screens using primary fixed and primary fixed dim.

Examples of fixed and fixed dim colors in use:

  1. Primary fixed for a FAB container color
  2. Primary fixed dim for an icon button container
Permissions screen with Surface used for the background and Primary Fixed incorrectly used for the button fill.
Don't Fixed colors don't change based on light or dark theme, so they're likely to cause contrast issues. Avoid using them where contrast is necessary.
Permissions screen with Surface used for the background and Primary correctly used for the button fill.
Do Use primary, secondary, and tertiary roles for accent colors where contrast is needed

On fixed accent colors

On fixed colors are used for text and icons which sit on top of the corresponding Fixed color. For example, on primary fixed is used for text and icons against the primary fixed color. The same usage applies for the equivalent secondary and tertiary colors.

On fixed variant colors are used for text and icons needing lower emphasis against the corresponding fixed color. For example, on primary fixed variant is used for low emphasis text and icons against the primary fixed color. The same usage applies for the equivalent secondary and tertiary colors.

6 color swatches for on fixed and on fixed variant
On fixed and on fixed variant color roles for the primary, secondary, and tertiary accent groups, shown in both light and dark themes
Banner in a news app using on primary fixed variant and on primary fixed
A customized banner which uses on primary fixed variant (1) for its deemphasized text and (2) on primary fixed for its emphasized text

Bright and dim surface roles ​

There are two add-on surface roles:

  • Surface dim: Dimmest surface color in light and dark themes
  • Surface bright: Brightest surface color in light and dark themes

3 color swatches: Surface dim, surface, and surface bright
Surface dim, surface, and surface bright in light theme

3 color swatches: Surface dim, surface, and surface bright
Surface dim, surface, and surface bright in dark theme

While the default surface color automatically inverts between light and dark themes (it's a light color in light theme and it flips to a dark color in dark theme), the surface bright and surface dim colors invert in a slightly different way. More precisely, they keep their relative brightness across both light and dark theme.

For example, in an interface using the default surface role, the mapped area is the brightest in light theme and the dimmest in dark theme. In an interface using the surface bright role, the mapped area is the brightest in both light and dark theme.

UI with surface role applied to the body area and surface container applied to the navigation area, shown in light theme.
Light theme
  1. Surface
  2. Surface container
UI with surface role applied to the body area and surface container applied to the navigation area, shown in dark theme.
Dark theme
  1. Surface
  2. Surface container
UI with surface bright role applied to the body area and surface container applied to the navigation area, shown in light theme.
Light theme
  1. Surface bright
  2. Surface container
UI with surface bright role applied to the body area and surface container applied to the navigation area, shown in dark theme.
Dark theme
  1. Surface bright
  2. Surface container
Large screen chat UI. The surface dim role is applied to the left navigation rail and the surface bright role is applied to the chat window.
  1. Navigation rail with surface dim background
  2. Chat window with surface bright background
Pager
Previous pageColor system: How the system works
Next pageChoosing a scheme

Released under the Apache 2.0 or CC BY 4.0

Copyright © 2018-Present Google

https://m3.material.io/styles/color/roles

Released under the Apache 2.0 or CC BY 4.0

Copyright © 2018-Present Google