Organising a real project

The previous lessons introduced the parts one by one. Here they come together into the structure of the small site from this course: tokens, functions and mixins in abstracts/, components in their own files, and one main.scss that only connects them.

The folder tree

styles/
├── abstracts/
│   ├── _index.scss       ← @forward of the three files below
│   ├── _tokens.scss
│   ├── _functions.scss
│   └── _mixins.scss
├── base/
│   ├── _index.scss
│   └── _base.scss
├── components/
│   ├── _index.scss
│   ├── _buttons.scss
│   └── _cards.scss
├── utilities/
│   ├── _index.scss
│   └── _spacing.scss
└── main.scss

Each folder has an _index.scss, so other files can load the whole folder by its name.

abstracts — tools without output

The index file gathers all tools into one module:

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

To keep the example short, each of the three files holds one member:

// styles/abstracts/_tokens.scss
$primary: #2563eb;

// styles/abstracts/_functions.scss
@function space($step) {
  @return $step * 4px;
}

// styles/abstracts/_mixins.scss
@mixin card-shadow {
  box-shadow: 0 2px 8px rgb(0 0 0 / 0.15);
}

Components

Every component file starts with the same line and then uses tools through the short namespace a:

// styles/components/_buttons.scss
@use "../abstracts" as a;
 
.btn {
  padding: a.space(2) a.space(4);
  color: white;
  background: a.$primary;
}

// styles/components/_cards.scss
@use "../abstracts" as a;
 
.card {
  padding: a.space(4);
  @include a.card-shadow;
}

The components index only lists the files:

// styles/components/_index.scss
@use "buttons";
@use "cards";

Here it uses @use, not @forward: the goal is to include the CSS of the components, not to pass on their members.

The other folders and main.scss

The base and utilities folders are built the same way: an index with @use lines and the files with rules.

// styles/base/_index.scss
@use "base";

// styles/base/_base.scss
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}

// styles/utilities/_index.scss
@use "spacing";

// styles/utilities/_spacing.scss
.mt-0 {
  margin-top: 0;
}

The main file contains no rules. It sets the order of the layers — from general to specific:

// styles/main.scss
@use "base";
@use "components";
@use "utilities";

body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
 
.btn {
  padding: 8px 16px;
  color: white;
  background: #2563eb;
}
 
.card {
  padding: 16px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
}
 
.mt-0 {
  margin-top: 0;
}

Base styles come first, components override them, and utility classes come last so they win over components.

Rules that keep the project tidy

Rule	Why
One component — one file	Easy to find and delete
`abstracts/` prints no CSS	Any file can load it safely
`main.scss` has only `@use`	The order of layers is visible at a glance
Values come from tokens	One change updates the whole site
Nesting up to three levels	Selectors stay short

Common mistake

Files of a folder are not loaded automatically. If you create components/_forms.scss but forget to add @use "forms"; to components/_index.scss, its styles are simply missing from main.css — without any error. After creating a file, add it to the index right away.

Thanks for reading!