Semantic Tokens and Design-System Foundations

A design token represents a reusable design decision such as a color, spacing value, font size, border radius, shadow, or motion duration.

Tokens can be organized into primitive and semantic layers. Primitive tokens represent raw values, while semantic tokens describe how those values are used. For example, a primitive color might be blue-600, while a semantic token might be color-action-primary.

Semantic naming makes themes and redesigns easier because components depend on intent rather than a specific color name. If the brand palette changes, the semantic mapping can change without rewriting every component.

Sass maps can store compile-time tokens, while CSS custom properties expose runtime values to the browser.

Primitive and Semantic Tokens

$palette: (
  blue-600: #2457c5,
  gray-900: #171717,
  gray-100: #f5f5f5
);

:root {
  --color-action-primary: #{map.get($palette, blue-600)};
  --color-text-primary: #{map.get($palette, gray-900)};
  --color-surface: #{map.get($palette, gray-100)};
}

.button-primary {
  background: var(--color-action-primary);
  color: white;
}

.page {
  color: var(--color-text-primary);
  background: var(--color-surface);
}

💡 This example uses map.get() to map primitive Sass colors to semantic CSS custom properties. It requires @use "sass:map"; at the beginning of the file. Components depend on semantic properties such as --color-action-primary. A new brand palette can be introduced by changing the token mapping rather than editing every component.

Knowledge Check

Why are semantic design tokens often more maintainable than using raw color names throughout components?

Semantic Tokens and Design-System Foundations

STAY UPDATED WITH BYTES!