Token systems (colour, space, type scales)

Design tokens in SCSS: named values for colour, spacing, typography, and radius that you reuse instead of scattering magic numbers. The goal is one place to change the brand blue, not twelve.

Variables are tokens (mostly)

You already use SCSS variables for colours and font sizes. A token system is that idea with naming discipline and scales – steps that relate to each other predictably.

Colour tokens

// abstracts/_variables.scss
$color-text: #1a1a1a;
$color-text-muted: #5c5c5c;
$color-surface: #ffffff;
$color-border: #d9d9d9;

$color-brand: #2563eb;
$color-brand-hover: #1d4ed8;
$color-danger: #dc2626;
$color-success: #16a34a;

Name by role (text, surface, brand), not by hex value. $blue tells you nothing about where it belongs.

Spacing scale

Pick a base unit (often 4px or 0.25rem) and derive steps:

$space-unit: 0.25rem;

$space-2xs: $space-unit;      // 4px at 16px root
$space-xs:  $space-unit * 2;   // 8px
$space-sm:  $space-unit * 3;   // 12px
$space-md:  $space-unit * 4;   // 16px
$space-lg:  $space-unit * 6;   // 24px
$space-xl:  $space-unit * 8;   // 32px
$space-2xl: $space-unit * 12;  // 48px

Components then use $space-md instead of 16px. When you tighten spacing site-wide, you adjust the scale.

Type scale

$font-family-sans: system-ui, sans-serif;
$font-family-mono: ui-monospace, monospace;

$font-size-sm: 0.875rem;
$font-size-base: 1rem;
$font-size-lg: 1.125rem;
$font-size-xl: 1.25rem;
$font-size-2xl: 1.5rem;
$font-size-3xl: 2rem;

$line-height-tight: 1.25;
$line-height-base: 1.5;
$line-height-loose: 1.75;

$font-weight-normal: 400;
$font-weight-medium: 500;
$font-weight-bold: 700;

CSS custom properties alongside SCSS

SCSS variables vanish at compile time. CSS custom properties survive in the browser – useful for theming and runtime changes. A common pattern: SCSS tokens emit CSS variables on :root:

// abstracts/_tokens.scss
$color-brand: #2563eb;

:root {
  --color-brand: #{$color-brand};
  --space-md: #{$space-md};
  --font-size-base: #{$font-size-base};
}

.button--primary {
  background: var(--color-brand);
  padding: var(--space-md);
  font-size: var(--font-size-base);
}

The #{} interpolation drops SCSS values into the output CSS. Components can use var() so a theme switch later only touches :root or a [data-theme] block.

Naming conventions

Pick one pattern and stay consistent:

• Category-role: $color-text-muted, $space-lg
• Semantic tiers: $surface-default, $surface-raised
• T-shirt sizes for steps: sm, md, lg (avoid ambiguous medium in code)

Document tokens in a comment block or README. Future you will forget whether $space-4 means 4px or step 4 on the scale.

Try it

• Define colour, spacing, and type tokens in abstracts/_variables.scss.
• Emit matching CSS custom properties on :root.
• Refactor one component to use tokens only – no raw hex or px except in the token file.