Material color roles: applying them without losing the brand

A color role is a name for a job in the interface. It answers where a color goes, not which color it is. The Material Design guide defines 26 standard roles across six groups: primary, secondary, tertiary, error, surface, and outline. The guide compares the roles to numbered areas on a paint-by-number canvas, as a way to describe the link between an element and its color.

What a color role decides

Roles describe a position in the layout. Surface is the role for backgrounds and large, low-emphasis areas. A role that starts with “on” marks text and icons over its paired parent color. A container role fills elements like buttons and is not meant for text or icons. A variant role is a lower-emphasis alternative to its non-variant pair.

Why the guide separates role from value

The role stays the same when the value changes. The guide states that color role mappings stay the same across dynamic color schemes while the colors underneath change. Roles are also implemented through design tokens, so the name carries the decision and the number lives elsewhere. A brand refresh edits the source colors, and every screen that reads the role takes the new value.

The main roles and where they appear

Accent roles carry emphasis, and the guide assigns them by how much attention an element needs. Primary covers the most prominent actions and elements, such as a floating action button. Secondary covers elements that do not need immediate attention, like the selected state of a navigation icon. Tertiary covers smaller elements that need emphasis without urgency, like a badge.

Error marks a state such as an incorrect password, and the guide keeps it static even under a dynamic scheme. Surface and its container roles take the neutral regions of a screen, with five container levels for hierarchy. Outline handles important boundaries such as a field border, while outline variant takes decorative marks like dividers.

Contrast inside the scheme, and where a pairing fails

The guide builds the scheme on accessible color pairs with a minimum 3:1 contrast. Combining colors outside the intended order can break the contrast that visual accessibility needs, especially once a contrast setting moves the values.

That floor isn’t the only number in play. Nielsen Norman Group reports that WCAG asks for at least 4.5:1 for body text and 3:1 for large text. A pairing can clear the guide’s floor and still fail for body text at a small size.

Contrast carries meaning as well as legibility. NN/g notes that a low-contrast treatment risks signaling that an option is unavailable, because dimming is the usual way to show a disabled control.

Brand color over the scheme

A static scheme keeps its colors regardless of user input or in-app content, and the guide ships a baseline scheme with default assignments. A custom brand scheme is hand-picked by the team to match the brand color.

The guide doesn’t hide the cost. Brand-based schemes are created and maintained entirely by the team, which it calls a larger investment of time and effort. The Material Theme Builder turns a brand hex value into a full custom color scheme, and the role names stay in place.

The brand color fits into the roles instead of overriding them. A brand accent mapped to primary still has to work with text and icons over its paired fill.

Dynamic and content-based schemes

Dynamic color builds an accessible scheme from one source color. The source can be a user’s wallpaper or in-app content. The guide recommends designing on the baseline scheme first, so the right roles are mapped to the right components before the colors start to move. What you don’t get is the same UI colors on every device.

The common mistake: an accent as a text background

An accent role is a fill, and its paired role is the text that sits on it. Using primary as the background of body text puts a fill where a container should go. The guide reserves the “on” roles for text and icons over their parent color.

NN/g reports that color alone is not enough to separate states, so a contrast test on the real pair beats a guess from a swatch. The same article suggests turning the design gray to see whether it still reads. NN/g also warns that colors of similar brightness are hard to tell apart for colorblind users.

What the guide doesn’t settle

The guide derives a scheme from a source color and defines the pairs that hold. It doesn’t set the final contrast of a brand. It also gives no fixed number for brand text over a brand fill, and that call stays with the product team.

A brand palette needs its own test rather than trust in the theme file. NN/g suggests keeping the palette to a small number of colors, since a wide set weakens hierarchy and the accent loses its job.

The roles here extend the post on Material Design and the post on design tokens. The contrast side of a scheme connects to the post on dark mode and contrast.