Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Projects and Practice

Project: Build a Design System Stylesheet

Build a small Sass design system from scratch: tokens, helper functions, mixins, configurable buttons and alerts, an index file with @forward, and a main file that ties it together.

In this project you build the core of a design system: a set of tokens, helpers and components that a team can reuse across many pages and configure for different brands. It brings together almost everything from this tutorial: modules, configuration, built-in modules, tokens, and component patterns.

What you will build

A mini library with this structure:

TEXT
design-system/
  abstracts/
    _index.scss      forwards the three files below
    _tokens.scss     colors, spacing, radius, type (configurable)
    _functions.scss  color(), space(), contrast helper
    _mixins.scss     focus-ring, elevation
  components/
    _button.scss     variants and sizes generated from maps
    _alert.scss      status variants
  main.scss          loads and configures everything

Requirements:

  1. Every value comes from a token; nothing is hard-coded in components.
  2. A brand can override tokens with @use ... with (...).
  3. Unknown tokens fail the build with a clear message.
  4. Components are accessible: visible focus, enough contrast for text on colored backgrounds.
  5. The abstracts layer outputs no CSS.

Step 1: tokens

Tokens are configurable (!default) maps. Maps are replaced as a whole when configured, which is a good thing: a brand supplies its entire palette.

SCSS
// abstracts/_tokens.scss
$colors: (
  primary: #4f46e5,
  success: #15803d,
  danger: #b91c1c,
  warning: #b45309,
  ink: #1f2937,
  surface: #ffffff,
) !default;

$spacing: (1: 0.25rem, 2: 0.5rem, 3: 1rem, 4: 1.5rem) !default;
$radius: 8px !default;
$font-body: system-ui, sans-serif !default;

Step 2: functions

Lookups go through functions that validate:

SCSS
// abstracts/_functions.scss
@use "sass:map";
@use "sass:color";
@use "tokens";

@function color($name) {
  @if not map.has-key(tokens.$colors, $name) {
    @error "Unknown color `#{$name}`. Available: #{map.keys(tokens.$colors)}";
  }
  @return map.get(tokens.$colors, $name);
}

@function space($step) {
  @if not map.has-key(tokens.$spacing, $step) {
    @error "Unknown spacing step `#{$step}`. Available: #{map.keys(tokens.$spacing)}";
  }
  @return map.get(tokens.$spacing, $step);
}

@function tint($name, $amount: 88%) {
  @return color.mix(white, color($name), $amount);
}

tokens.$colors reads the current value, so a configured palette from main.scss is used by every function. Because _functions.scss loads tokens with a plain @use, the module is shared: the configuration given in the first @use applies everywhere.

Step 3: mixins

SCSS
// abstracts/_mixins.scss
@use "functions" as f;

@mixin focus-ring($name: primary) {
  &:focus-visible {
    outline: 3px solid f.tint($name, 55%);
    outline-offset: 2px;
  }
}

@mixin elevation($level: 1) {
  box-shadow: 0 #{$level * 2}px #{$level * 6}px rgb(0 0 0 / 0.14);
}

Step 4: the index file

SCSS
// abstracts/_index.scss
@forward "tokens";
@forward "functions";
@forward "mixins";

Components now write @use "../abstracts" as a; and use a.color(primary), a.space(3), @include a.focus-ring.

Step 5: components

Components are generated from maps, so adding a variant is one line:

SCSS
// components/_button.scss
@use "../abstracts" as a;

$variants: (primary, success, danger);
$sizes: (sm: 0.85rem, md: 1rem, lg: 1.2rem);

.button {
  display: inline-block;
  padding: a.space(2) a.space(3);
  border: 0;
  border-radius: a.$radius;
  font: inherit;
  color: white;
  cursor: pointer;
  @include a.focus-ring;

  @each $name in $variants {
    &--#{$name} { background: a.color($name); }
  }
  @each $name, $size in $sizes {
    &--#{$name} { font-size: $size; }
  }
}
SCSS
// components/_alert.scss
@use "../abstracts" as a;

.alert {
  padding: a.space(3);
  border-left: 4px solid;
  border-radius: a.$radius;

  @each $name in (success, danger, warning) {
    &--#{$name} {
      color: a.color($name);
      background: a.tint($name);
      border-color: a.color($name);
    }
  }
}

Try the whole system

The project below is the complete thing as one runnable set of files. Everything is loaded through mem: URLs; the layout matches the folders above.

The design system (all files)

This is the "brand" configuration: main.scss replaced the primary color and radius. Try these experiments:

  1. Remove the with (...) block. The system returns to the default indigo brand.
  2. In the button file, add info to $variants before adding the color. Read the @error message that lists the valid color names.
  3. Add info: #0369a1 to the palette in main.scss and to the button variants. A new button style appears with zero other changes.

Design decisions worth noticing

  • Whole-map configuration. Overriding $colors replaces the full map, so a brand must supply every key. If you prefer partial overrides, expose per-color variables or merge in _tokens.scss with map.merge(...).
  • Single source of truth. Components never contain a color literal. A rebrand touches one file (or one with).
  • Explicit public API. abstracts/_index.scss decides what components may use. Adding an internal helper to _functions.scss with a - prefix keeps it private.
  • Fail loudly. Typos fail at compile time with the list of valid names.
  • No CSS in abstracts. You can load the abstracts in any file at zero cost.

Extension ideas

  • Add a contrast check function that returns black or white text for a background (compute relative luminance with math.pow and color.channel) so every variant stays readable.
  • Generate CSS custom properties from tokens.$colors in a base/_root.scss file for runtime theming (design tokens).
  • Add a breakpoints map and a responsive up() mixin (breakpoints).
  • Publish it: compile with sass --style=compressed, ship the Sass source too so consumers can configure it, and document it with SassDoc comments (best practices).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the color() function read tokens.$colors inside the function body?

    The function looks up the shared module's variable, which includes any configuration applied on the first load.
  2. 2. What file lets components write a single @use "../abstracts"?

    An index file forwards the folder's modules so one @use exposes them all.
  3. 3. How does the brand override the radius and palette?

    !default variables can be configured at the first @use.
  4. 4. Why is a typo in a color name caught at build time?

    Lookup functions validate keys and stop compilation with a helpful message.
  5. 5. Which part of the system should produce no CSS?

    Abstracts hold only tokens, functions and mixins, so loading them is free.

Summary

  • A design system in Sass is tokens, validated lookup functions, mixins, an index file and components generated from maps.
  • Configure with !default tokens and @use ... with (...) in the entry file.
  • Keep abstracts free of CSS and components free of literals.
  • Fail loudly on unknown tokens and keep the public API small.

Next: Project: A Themed Dashboard Layout