Maps and loops for design systems

Next: SCSS maps and loops. The tools that turn a token list into generated utility classes, theme variants, or a spacing scale without copy-pasting.

Maps as structured tokens

A map is a key-value store. It groups related tokens:

$colors: (
  'text': #1a1a1a,
  'text-muted': #5c5c5c,
  'brand': #2563eb,
  'danger': #dc2626,
);

$spacing: (
  'xs': 0.5rem,
  'sm': 0.75rem,
  'md': 1rem,
  'lg': 1.5rem,
  'xl': 2rem,
);

Read values with map.get (module syntax) or map-get (legacy):

@use 'sass:map';

.alert {
  color: map.get($colors, 'danger');
  padding: map.get($spacing, 'md');
}

@each loops

Loop over a map to generate classes:

@each $name, $value in $spacing {
  .u-mt-#{$name} {
    margin-top: $value;
  }
}

Compiled output:

.u-mt-xs { margin-top: 0.5rem; }
.u-mt-sm { margin-top: 0.75rem; }
.u-mt-md { margin-top: 1rem; }
.u-mt-lg { margin-top: 1.5rem; }
.u-mt-xl { margin-top: 2rem; }

Interpolation #{} inserts the key into the selector name. Handy for utilities; easy to over-generate if the map is huge.

Nested maps for themes

$themes: (
  'light': (
    'bg': #ffffff,
    'text': #1a1a1a,
    'brand': #2563eb,
  ),
  'dark': (
    'bg': #121212,
    'text': #f5f5f5,
    'brand': #60a5fa,
  ),
);

@function theme($theme, $key) {
  $theme-map: map.get($themes, $theme);
  @return map.get($theme-map, $key);
}

We use this pattern properly in the theming tutorial. For now, notice how one data structure drives multiple outputs.

@for and @while

@for suits numeric scales:

@for $i from 1 through 6 {
  .heading-#{$i} {
    font-size: $font-size-base * (1 + ($i - 1) * 0.125);
  }
}

Use @while rarely – infinite loops compile forever (literally). Prefer @each over lists and maps you control.

Keep loops readable

• Put loop logic in partials named for their output (_utilities.scss, _theme-vars.scss).
• Cap utility generation – you do not need margin classes for every pixel.
• Comment what a loop produces so grep still finds individual classes in source.

Try it

• Define a $colors map and a color() function.
• Generate .text-{name} utilities with @each.
• Check compiled CSS size – if it doubled, trim the map or scope utilities to a layer.