Semantic tokens

Semantic tokens describe what a value means, not what it is: color-action-primary, color-feedback-error, space-stack-md. They sit between reference tokens (the raw values) and component tokens (the scoped ones), and they're the layer that makes theming and dark mode possible without rewriting components.

The trick to a good semantic layer is naming for purpose, not appearance — color-surface will survive a colour rebrand; color-light-grey will not. Most modern systems (Material, Polaris, Carbon) settle on similar conventions: a noun describing the role plus a modifier describing the state or hierarchy. Tools like Tokens Studio and Style Dictionary handle the alias chains in transformation.

Related: Design tokens · Reference tokens · Component tokens · Theming