# Semantic vs Primitive Design Tokens

> A semantic token is named for its purpose, not its value: --color-text-danger rather than --color-red-600. It points at a primitive token.

- Source: https://flashdsm.com/glossary/semantic-token
- Site: Flash DS (https://flashdsm.com)
- Updated: 2026-08-06

---

## Definition

A semantic token is a design token named for the job it does rather than the value it holds, such as `--color-text-danger` rather than `--color-red-600`. It usually references a primitive token, which lets the underlying value change without renaming anything that uses it.

Also written as: Semantic design token, Alias token

## The two layers

Most mature token systems have at least two tiers.

**Primitive tokens** (also called raw, global or core tokens) hold the actual values. They are named descriptively:

```
--red-600: #DC2626;
--blue-500: #2563EB;
--space-4: 16px;
```

**Semantic tokens** hold decisions about where those values are used. They are named by role:

```
--color-text-danger: var(--red-600);
--color-action-primary: var(--blue-500);
--space-card-padding: var(--space-4);
```

Components reference the semantic layer. Almost nothing should reference a primitive directly.

## Why the indirection earns its keep

**Rebranding stops being a rewrite.** Change what `--color-action-primary` points at and every button follows. If components referenced `--blue-500`, you would be editing every component, and the ones that used blue for a reason unrelated to actions would break.

**Themes become possible.** Dark mode is the same semantic names pointing at different primitives. Without the semantic layer there is nothing to repoint.

**The code says what it means.** `--color-text-danger` tells a reader why the value is there. `--red-600` tells them nothing, which matters most when someone has to decide whether changing it is safe.

## The usual mistake

Teams skip the semantic layer because it feels like bureaucracy on day one, when there are eleven colours and everyone remembers what they are for.

The cost shows up at the first rebrand, the first dark mode, or the first accessibility pass, and by then the primitives are referenced in hundreds of places. Retrofitting a semantic layer is mechanical but tedious work that nobody schedules.

## A third tier

Larger systems add component-level tokens: `--button-primary-background` pointing at `--color-action-primary` pointing at `--blue-500`.

This helps when a component genuinely needs to diverge, and it costs indirection when it does not. Two tiers is the right default; add the third when a real case appears rather than in advance.

## Where this fits with Flash DS

Generated systems come with both tiers already in place: primitive scales, and semantic roles for text, background, border and status that reference them, in light and dark.

## Related terms

- https://flashdsm.com/glossary/design-token
- https://flashdsm.com/glossary/dark-mode-tokens
- https://flashdsm.com/glossary/design-system