Design Nomenclature / Systems & Spec
Semantic token
Also called alias token, decision token, primitive token, base token
A token named for its role rather than its value — `color.text.subtle`, not `gray.600` — pointing at a primitive token beneath it. The primitive layer holds the palette; the semantic layer holds the decisions. Only the semantic layer should ever appear inside a component.
In practice
The layer teams skip and then rebuild when dark mode lands: `gray.600` used directly can't be re-pointed, so every component changes instead of one alias.
Not to be confused with
- Design tokenA named, single-source value for a design decision — a colour, a step on a spacing scale, a duration — held in a format that transforms into CSS, iOS, Android, or Figma. The name is the contract; the value is free to change per theme, platform, or density without the name changing.
- VariableA platform's own named-value mechanism — a CSS custom property, a Figma variable, an iOS colour asset. It is where a token lands, not what a token is: a variable resolves at runtime in one platform's terms, while a token is a source entry meant to compile into all of them.