Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 39 ยท Real-world Patterns

Design Tokens and Theming with Sass

Build a design token system in Sass: store colors and spacing in maps, generate CSS custom properties with @each, validate tokens with @error, and ship light and dark themes.

A design token is a named design decision: color-primary, space-3, radius-card. Tokens keep a site consistent, because every button, card and form reads the same value from the same place. Sass is a natural home for tokens: variables and maps hold them, functions look them up safely, and loops turn them into CSS.

The most important modern idea is to use Sass for what it is good at (organizing, generating, validating at build time) and CSS custom properties for what they are good at (changing at runtime, such as a dark theme). This lesson combines the two.

Tokens in maps

A single map per category keeps related values together and is easy to loop over:

SCSS
$colors: (
  primary: #4f46e5,
  success: #16a34a,
  danger: #dc2626,
  ink: #1f2937,
);

$space: (1: 0.25rem, 2: 0.5rem, 3: 1rem, 4: 1.5rem, 5: 3rem);
$radius: (sm: 4px, md: 8px, pill: 999px);

You can also nest everything in one map, $tokens, and read it with map.get($tokens, "color", "primary"), which walks down the keys.

A token function that fails loudly

A typo like map.get($colors, primray) returns null, and the CSS silently loses a declaration. Wrap lookups in a function that stops the build with a clear message:

SCSS
@use "sass:map";

$tokens: (color: (primary: #4f46e5, ink: #1f2937), space: (1: 0.25rem, 2: 0.5rem));

@function token($group, $name) {
  @if not map.has-key($tokens, $group) {
    @error "Unknown token group `#{$group}`. Groups: #{map.keys($tokens)}";
  }
  $values: map.get($tokens, $group);
  @if not map.has-key($values, $name) {
    @error "No `#{$name}` in `#{$group}`. Available: #{map.keys($values)}";
  }
  @return map.get($values, $name);
}

.card { color: token(color, ink); padding: token(space, 2); }

Now a misspelled token fails at compile time with the list of valid names. This one habit prevents a whole class of design bugs.

Generating custom properties

Loops can publish every token as a CSS variable:

SCSS
:root {
  @each $name, $value in $colors { --color-#{$name}: #{$value}; }
  @each $name, $value in $space  { --space-#{$name}: #{$value}; }
}

Two details matter. The property name needs interpolation: --color-#{$name}. The value needs it as well: #{$value}. Custom property values are treated as raw text, so Sass does not evaluate them unless you interpolate.

Components can then use the variables, which means a runtime change to --color-primary retints every component without recompiling:

SCSS
.button { background: var(--color-primary); padding: var(--space-2) var(--space-4); }
Tokens to custom properties

Add a color to the $colors map and reference it in a badge variant. Then misspell a name inside color() to see the @error.

Light and dark themes

Define each theme as a map of the same semantic keys, then turn one theme into variables on a selector. Semantic names (surface, text, accent) describe role, not hue, which is what lets themes swap values.

SCSS
@use "sass:map";

$themes: (
  light: (bg: #ffffff, surface: #f3f4f6, text: #1f2937, accent: #4f46e5),
  dark:  (bg: #0f172a, surface: #1e293b, text: #e5e7eb, accent: #818cf8),
);

@mixin theme-vars($name) {
  color-scheme: $name;
  @each $token, $value in map.get($themes, $name) {
    --#{$token}: #{$value};
  }
}

:root { @include theme-vars(light); }

[data-theme="dark"] { @include theme-vars(dark); }

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { @include theme-vars(dark); }
}

The three rules give you: light by default, dark when the operating system asks for it, and an explicit override with data-theme on the <html> element (which a toggle button sets and remembers).

Duplicating the dark values in two places is just a call to the same mixin, so there is no copy-paste in the source. The compiled CSS repeats the declarations, which is a few hundred bytes after gzip.

A theme switcher

Mixing Sass values and CSS variables

Sass functions work at compile time and need real values. They cannot read var(--accent): color.adjust(var(--accent), $lightness: -10%) is an error because the browser has not picked a value yet. Two ways around it:

  1. Compute variants in Sass for each theme and publish them as extra tokens: --accent-hover, --accent-soft.
  2. Use CSS color functions that run in the browser: color-mix(in srgb, var(--accent) 85%, black) or relative colors.
SCSS
@mixin theme-vars($name) {
  $t: map.get($themes, $name);
  @each $token, $value in $t { --#{$token}: #{$value}; }
  --accent-hover: #{color.adjust(map.get($t, accent), $lightness: -8%)};
}

Rule of thumb: if the value is known when you build, calculate it in Sass; if it changes in the browser, let CSS handle it.

A modular type and spacing scale

Sass math builds a consistent scale from one ratio:

SCSS
@use "sass:math";

$base: 1rem;
$ratio: 1.25;

:root {
  @for $i from -1 through 5 {
    --step-#{$i}: #{math.pow($ratio, $i) * $base};
  }
}

That emits --step--1, --step-0 ... --step-5, each 25% larger than the last. Change $ratio once and the entire scale updates. (A negative exponent gives steps smaller than the base.)

Organizing token files

Keep tokens in abstracts/_tokens.scss and forward them from the abstracts index (see project architecture). Put the code that emits the custom properties in base/_root.scss, because it outputs CSS. Keep maps and functions in the abstracts so any file can look values up without outputting anything.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why interpolate the value in --color-primary: #{$value};?

    Without #{ }, the literal text $value would reach the CSS.
  2. 2. What is the main advantage of CSS custom properties over Sass variables for theming?

    Sass variables disappear at build time; custom properties live in the browser and can be changed per element or theme.
  3. 3. Why wrap a map lookup in a function with @error?

    A plain map.get returns null for a typo, which silently drops the declaration.
  4. 4. Can color.adjust(var(--accent), $lightness: -10%) compile?

    var(--accent) is a CSS value Sass cannot evaluate; compute the variant per theme or use color-mix() in CSS.
  5. 5. What should theme maps share?

    Semantic names such as surface and text let one set of component rules work in every theme.

Summary

  • Store tokens in maps; look them up with a function that raises @error for unknown names.
  • Publish tokens as CSS custom properties with @each and interpolation.
  • Themes are maps with the same semantic keys, applied by a mixin to :root, [data-theme] and prefers-color-scheme.
  • Sass functions cannot see runtime custom properties: compute per theme or use CSS color functions.
  • Generate modular scales with a ratio and math.pow.

Next: Responsive Breakpoint System