Using global color tokens directly in component code
Referencing `color.teal.500` in components instead of `color.text.brand` collapses the semantic layer and locks components to specific palette values.
The wrong way
Skipping the semantic layer and referencing a raw global color directly inside a component.
.callout {
color: var(--color-teal-700);
background-color: var(--color-teal-50);
}Why
The two-tier token system exists for a reason. Global tokens (`teal.500`, `red.700`) describe values; semantic tokens (`text.brand`, `surface.error`) describe purpose. Skipping the semantic layer means when you re-skin a product, fix a contrast issue, or ship dark mode, every component breaks. Globals are the ingredient pantry — components should consume from the recipe shelf.
The right way
Reference the appropriate semantic token. Propose a new one through governance if no existing semantic fits.
.callout {
color: var(--color-text-brand);
background-color: var(--color-surface-brand);
}Related
See also: Hardcoded hex values in component code