Sass Design Tokens

What Are Design Tokens?

A design token is a single named value representing a design decision, primary-color, spacing-md, font-size-lg, that gets reused everywhere that decision applies. Sass variables and maps are a natural way to define tokens directly in code, ready to consume from mixins, functions, and components.

$tokens: (
  color: (
    primary: #2563eb,
    danger: #dc2626,
  ),
  spacing: (
    sm: 8px,
    md: 16px,
    lg: 24px,
  ),
);

Grouping tokens by category inside one map keeps related values organized and gives you a single source of truth to update.

Accessing Nested Design Tokens

@use 'sass:map';

map.get($tokens, color, primary);
map.get($tokens, spacing, md);

• map.get() supports multiple keys to reach into nested maps directly.
• A small wrapper function (like token()) makes token lookups shorter and more readable at call sites.
• Grouping tokens by category (color, spacing, typography) keeps a large token set organized.
• Tokens defined with !default can be overridden by a consuming project through with().

Design Tokens Cheatsheet

Common token categories and how to model them in Sass.

Writing a Token Accessor Function

Wrapping map.get() in a small custom function gives every token lookup a consistent, short syntax and a place to add validation, like erroring on a typo'd token name.

@use 'sass:map';

@function token($category, $name) {
  $group: map.get($tokens, $category);
  @if not $group or not map.has-key($group, $name) {
    @error "Unknown token: #{$category}.#{$name}";
  }
  @return map.get($group, $name);
}

.button {
  background: token(color, primary);
  padding: token(spacing, md);
}

Tokens and CSS Custom Properties

Sass tokens are compile-time only. For tokens that need to change at runtime (like a user-toggled theme), generate matching CSS custom properties from your Sass token map, covered in more depth in the CSS Custom Properties lesson.

@each $name, $value in map.get($tokens, color) {
  :root {
    --color-#{$name}: #{$value};
  }
}

Keeping Tokens as a Single Source of Truth

The core benefit of design tokens is consistency: every component references the same map instead of hardcoding its own values, so a single change (like adjusting the brand color) propagates everywhere automatically.

• Never hardcode a raw color or spacing value directly inside a component partial.
• Always reference the token map (directly or through an accessor function) instead.
• Review new components for hardcoded values during code review, not just for typos.

Common Mistakes

• Hardcoding raw values in components instead of referencing the central token map, defeating the purpose of having tokens at all.
• Building an overly deep, many-level-nested token map that becomes tedious to query without helper functions.
• Forgetting that Sass tokens never reach the browser directly, they need to be output as CSS custom properties if runtime theming is required.
• Not validating token lookups, letting a typo'd token name silently return null instead of erroring clearly.

Key Takeaways

• Design tokens are named values representing design decisions, colors, spacing, typography, breakpoints.
• Sass maps are a natural way to model tokens, especially grouped by category.
• A small accessor function improves token lookup readability and can validate token names.
• For runtime theming, generate CSS custom properties from your Sass token map.