Material Design tokens: what they are and what they decide

A design token is a name for a style value, and design and code read that name from the same place. The Material Design guide calls design tokens the building blocks of all UI elements, used across designs, tools, and code. It defines a token as a code-like name plus an associated value, such as a name and a color.

What a token replaces

A hardcoded value explains nothing. You write a hex code, and whoever comes next has to guess what it is for. A token tells you why. The guide names each token for how or where it is used, and its example sets the container color of a floating action button.

The value can change while the name stays. The guide states that even if a token’s end value changes, its name and its use remain the same. Update one stored value, and every screen that reads the name picks up the change at once.

The guide also claims the practical gain. Using tokens instead of hardcoded values can simplify building, maintaining, and scaling a product with a design system. Read that as the guide’s own framing rather than a measured result.

The three classes the guide defines

Material splits tokens into three classes, and each answers a different question. Reference tokens hold all available tokens with associated values. They usually point at a static value and do not change based on context. System tokens hold the decisions and roles that give the design system its character, and this is where theming happens. Component tokens hold the design properties assigned to elements in a component, such as the color of a button icon.

The classes form a chain. The guide says a system token can point to different reference tokens depending on the context. A component token, in turn, should point to a system or reference token rather than contain hardcoded values. A button that gets its container color this way points at a hex value that can change without touching the token name.

What the name tells you

A token name is read left to right, from general to specific. The guide separates the parts with periods and runs from the most general information to the most specific. The first part names the system, “md” in the guide’s example. The second names the class: ref for reference, sys for system, and comp for component. The rest communicates the token’s purpose.

So the name works like a short sentence about intent. You can tell where a value is used without opening a stylesheet.

Where a color role becomes a value

Color is the clearest case, because the token is what connects a role to a number. The guide spreads color across 26 standard roles, grouped into six families that run from primary to outline. Each role becomes a token with a stable name, and the theme swaps only the value behind it. What each role means in the layout is in the post on color roles.

The pairing is a rule, not a suggestion. The guide states that the color system is built on accessible pairs with a minimum 3:1 contrast. It warns that combining colors outside the intended pairs may break the contrast needed for visual accessibility.

How the system produces those values

With dynamic color, one source color drives the whole scheme. The guide describes the path. A single source color generates five key colors, the system turns those into tonal palettes, and tones are then assigned to the 26 color roles in both light and dark themes.

The assignment follows tone, because tone decides contrast. The guide states that tone determines contrast, which is why it carries the accessible relationships, and that its color space holds tone steady while hue and chroma move. That is what lets the algorithm pair contrasting tones without a person checking every pair.

The scheme also carries contrast levels. The guide lists standard, medium, and high, where medium holds at least 3:1 and high reaches 7:1. It says a custom component supports those levels by using the appropriate roles, such as primary container with on primary container.

Getting the values

You don’t have to copy the starting set by hand. It comes ready to download. The guide ships a baseline theme with tokens and default values as a Design System Package. It pairs that with a Figma plugin that generates the same token set as styles you can apply to a layout.

When tokens aren’t worth it

Tokens pay off when a value repeats and the system has an owner. The guide names the conditions where they help less. Tokens matter less when an existing app uses hardcoded values and is unlikely to change within a year or two, and less when the product has no design system at all. Both describe one situation: little reuse, and nobody to keep the mapping current.

The common mistake

A token that only stores a value, without naming the decision behind it, is just a constant with a longer name. The guide points the other way. A component token should point to a system or reference token and not contain hardcoded values, and a system token should point to reference tokens rather than static values whenever possible. When the chain collapses into raw values, theming stops working, because there is nothing left to swap.

Where the guide leaves it open

The guide defines the classes and the shape of a name. It doesn’t say when a team should stop using a direct value inside a component. It doesn’t define how to version a broken contract between design and code. Those decisions stay with the team, and a token set doesn’t make them for you.

A second limit sits outside the guide. Nielsen Norman Group’s Design Systems 101 describes a design system as standards that need a dedicated team, and treats the system as something that keeps evolving. A token file is the recorded half of that, and it holds only while someone keeps the map true.

That is also why consistency is a property a team maintains instead of a state the files reach. It is also why design system maturity is not linear, with systems that regress after launch. None of those points is about tokens in particular, but each one decides whether a token set keeps working. Tokens are only one piece of a system that needs people looking after it.

Adopt tokens when a value repeats and someone owns the names. Skip them when the interface won’t change and no one will keep the mapping. That is the same test as owning a design system, which is the decision covered in the post on building or adopting one.

The tokens serve a system that is explained in the post on Material Design. That post covers where the system came from and how its versions differ. What keeps a system alive after launch, token set included, is in the post on design systems after launch.