# Semantic tokens

> A semantic token names a role, such as bg/weak-50 or text/strong-950, and points at a primitive token that holds the raw value. Components bind to the role, never to the primitive.

Page: https://www.appetiteui.com/academy/glossary/semantic-tokens. Semantic vs primitive tokens in a design system. Also called Primitive tokens, Alias tokens.

## At a glance

|  | iOS | Android (Material 3) | Appetite UI |
| --- | --- | --- | --- |
| Name | Semantic colors, such as label and systemBackground | Color roles, such as primary and surface-container | Color Tokens collection, roles such as brand/base and bg/weak-50 |

## In practice

Primitives are the palette, colors/blue/500 and the rest, and they never change meaning. Semantic tokens are the decisions made with them, and a rebrand or a dark mode swaps which primitive each role points at.

In Appetite UI every component and screen binds to semantic tokens. The finance screens, for example, bind every solid fill and stroke to a semantic variable and leave none unbound, so the dark row of screens is the light layout with one mode changed.

## Questions

### What is the difference between primitive and semantic tokens?

A primitive token holds a raw value, such as colors/blue/500. A semantic token names the job a value does, such as brand/base or bg/weak-50, and points at a primitive. Components bind to semantic tokens, so changing what a role points at restyles every component that uses it.

### Why bind components to semantic tokens and not to primitives?

Because dark mode and a rebrand change what a role points at, not the components. A button bound to brand/base follows a new brand color in light and dark; a button bound to colors/blue/500 has to be found and changed by hand.

## Sources

1. [Material Design 3: Color roles](https://m3.material.io/styles/color/roles)
2. [Apple Human Interface Guidelines: Color](https://developer.apple.com/design/human-interface-guidelines/color)

## Related

- Docs: [Colors](https://www.appetiteui.com/docs/colors)
- Docs: [Platform Bridge](https://www.appetiteui.com/docs/platform-bridge)
- Article: [Dark mode with Figma variables, not duplicate frames](https://www.appetiteui.com/blog/dark-mode-figma-variables)
- Article: [How to rebrand a mobile app in Figma with variables](https://www.appetiteui.com/blog/rebrand-mobile-app-figma-variables)
- Glossary: [Design tokens](https://www.appetiteui.com/academy/glossary/design-tokens)
- Glossary: [Variable modes](https://www.appetiteui.com/academy/glossary/variable-modes)
- Glossary: [Dark mode](https://www.appetiteui.com/academy/glossary/dark-mode)