Semantic Tokens

Design Systems & Engineering • UX & Product Architecture

A semantic token is a design token whose name describes what a value is for, such as the color of link text. Teams can reuse the same role across components and assign it different values for light and dark themes.

How do semantic tokens work across themes?

A checkout link might use color.text.link. In a light theme, that role might point to color.blue.600. In a dark theme, it might point to color.blue.300. The link still asks for the color assigned to link text. The theme supplies the appropriate value.

Name What the name tells you
color.blue.600 A step in a base palette
color.text.link The role the color serves in the interface
button.primary.background A decision scoped to a specific component and variant

These names are illustrative. The palette step number is local to this system. Document how each role should be used and verify each foreground and background pairing in the actual interface.

Is a semantic token the same as an alias?

“Semantic” describes what the name means. An alias is a reference to another token. A semantic token can use an alias to reuse a palette value, or it can store a value directly. The reference is a mechanism for sharing the value.

How do you name and introduce semantic tokens?

  1. Start with a repeated purpose. Inspect where teams use a color or spacing decision. Identify the purpose those uses share.
  2. Name the role. Make the name useful when someone chooses a token. For example, link text and a selected background can use different roles even when they happen to share a value.
  3. Set values per theme and test them. Check representative components, states, and backgrounds in the contexts where people use them.
  4. Move consumers to the shared role. Review each use before replacing the original values. If a component needs its own change policy, document a component token for that decision.

Change the narrowest token that matches the intended scope. To update link text across checkout and settings, change the link text role. To update only one component, inspect whether it already has a dedicated token or setting.

Sources