Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 39 ยท Control Directives and Maps

Building Spacing, Color and Type Scales in Sass

A worked example that combines maps, loops, functions and color math: generate a spacing scale, a ten-step color palette and a modular type scale as CSS custom properties.

You now know variables, maps, functions, conditions and loops. This lesson puts them together in a small, realistic piece of design-system code: three scales generated from a handful of inputs. A scale is a short, ordered list of sizes or shades that a whole product agrees to use, so designers and developers stop arguing about whether a gap should be 13px or 14px. The inputs are a few !default settings, and the output is a block of CSS custom properties plus helper classes.

The plan

flowchart LR
  A["Inputs<br/>base size, ratio,<br/>brand color"] --> B["Maps and functions"]
  B --> C["@each loops"]
  C --> D[":root custom properties"]
  C --> E["Helper classes"]

A few settings go in; maps, functions and loops turn them into CSS.

Part 1: a spacing scale

Spacing works best on a grid unit. A base of 4px with a handful of named steps covers almost every layout:

SCSS
@use "sass:list";

$space-unit: 4px !default;
$space-steps: (1, 2, 3, 4, 6, 8, 12, 16) !default;

@function space($step) {
  @if not list.index($space-steps, $step) {
    @error "No spacing step #{$step}. Valid steps: #{$space-steps}.";
  }
  @return $space-unit * $step;
}

A single function (space(4) gives 16px) makes every file use the same scale, and the @error stops anyone from inventing space(5) by accident. To expose the scale to the browser, loop and emit custom properties:

SCSS
:root {
  @each $step in $space-steps {
    --space-#{$step}: #{space($step)};
  }
}

Both the property name and the value use interpolation: --space-#{$step} builds the name, and #{space($step)} is needed because custom property values are raw text.

A spacing scale as custom properties

The .w-* bars are sixteen pixels wide per step, so you can compare the steps visually. Try space(5) in the demo: it is not in the list, so the build stops with the @error message. That is exactly the early warning you want.

Part 2: a ten-step color scale

Design systems often name shades 50, 100, 200 ... 900 (light to dark). You can compute them from one brand color by mixing with white for the light half and black for the dark half:

SCSS
@use "sass:color";
@use "sass:map";

$brand: hsl(262 83% 58%) !default;

$tint-weights: (50: 92%, 100: 82%, 200: 66%, 300: 48%, 400: 24%);
$shade-weights: (600: 12%, 700: 28%, 800: 44%, 900: 60%);

@function build-scale($base) {
  $scale: (500: $base);
  @each $step, $weight in $tint-weights {
    $scale: map.set($scale, $step, color.mix(white, $base, $weight));
  }
  @each $step, $weight in $shade-weights {
    $scale: map.set($scale, $step, color.mix(black, $base, $weight));
  }
  @return $scale;
}

map.set creates a new map each time, and the loops reassign $scale, which updates the outer variable thanks to the control-flow scope rule. The weight is the share of white (or black) in the mix.

Now emit the properties:

SCSS
$brand-scale: build-scale($brand);

:root {
  @each $step, $value in $brand-scale {
    --brand-#{$step}: #{$value};
  }
}
A generated brand palette

Change $brand to another hsl() color and rerun: ten new shades appear, and nothing else changed. That is the payoff of describing the scale as data.

Part 3: a modular type scale

A modular scale multiplies a base font size by a fixed ratio for each step up or down, which gives type sizes that feel related. Common ratios are 1.2 (minor third), 1.25 (major third) and 1.333 (perfect fourth).

SCSS
@use "sass:math";

$type-base: 1rem !default;
$type-ratio: 1.25 !default;

@function type-size($step) {
  @return $type-base * math.pow($type-ratio, $step);
}

h1 { font-size: type-size(4); }   // 2.44140625rem
h2 { font-size: type-size(3); }
h3 { font-size: type-size(2); }
small { font-size: type-size(-1); }

Negative steps give sizes smaller than the base. Because you set $type-ratio in one place, a design review that moves from 1.25 to 1.2 is a single-character change.

Letting users configure the scales

Notice every input uses !default. When these settings live in a module, consumers can override them as they load it (covered in Module configuration and privacy):

SCSS
@use "scales" with ($space-unit: 8px, $brand: hsl(160 70% 35%), $type-ratio: 1.2);

The module generates the scales from their numbers, without anyone editing your file.

Pitfalls to avoid

  • Over-generating. Ten shades x many colors x hover variants adds up quickly. Generate only what your design uses.
  • Hidden magic. Document each scale with /// comments and show an example of the generated names.
  • Rounding surprises. math.pow can give long decimals; Sass prints up to ten digits. Round with math.div(math.round($n * 100), 100) if you want tidy numbers.
  • Mixing build-time and run-time. The Sass scale is fixed at compile time. If users should switch themes in the browser, output custom properties (as shown) and reference var(--brand-500) in components.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do the custom property values in :root use #{ }?

    Sass does not evaluate expressions inside custom property values. Interpolation inserts the computed value.
  2. 2. What does map.set($scale, 100, $color) return?

    Maps are immutable, so map.set returns a copy.
  3. 3. With a base of 1rem and ratio 1.25, what does type-size(-1) approximately give?

    1.25 to the power of -1 is 0.8, so the size is 0.8rem.
  4. 4. Why mark scale inputs with !default?

    !default only assigns when the variable is not already set, which allows configuration through @use ... with (...).

Summary

  • A scale is a small set of related values generated from a few inputs, which keeps a design consistent.
  • Spacing: a base unit multiplied by named steps, guarded with @error.
  • Color: color.mix with white and black builds tints and shades; map.set collects them in a map.
  • Type: a base size times a ratio raised to the step gives a modular scale.
  • Emit scales as CSS custom properties and mark inputs !default so others can configure them.

Next: Debugging with @warn, @error and @debug