SCSS Standards

File organisation, code style, and authoring practices that support OOCSS and maintainable stylesheets.

File structure

Writing style

Selectors

Only class and element selectors are used for styling; never ID or attribute selectors.
// Bad – independent rules .media { display: flex; gap: 1rem; } .media-img { flex-shrink: 0; } .media-body { flex: 1; } // Good – nested .media { display: flex; .img { ... } // uses descendant selector }
For skins, write standalone rules that apply directly:

.primary {
  background-color: var(--color-primary);
  color: #fff;
}

.muted {
  color: var(--color-text-muted);
}

Placeholder selectors for objects (optional)

Define structural objects as silent placeholders (%) when you want to share the base structure without emitting an unused class. Extend them in concrete classes.

.media-object {
  display: flex;
  gap: 1rem;
}

.media {
  @extend .media-object;
}

.grid {
  @extend .media-object; // example of reusing structure
}

Prefer this over extending regular classes, because it keeps the compiled CSS clean and avoids unwanted grouping.

Mixins vs `@extend`

Use mixins for reusable chunks that require parameters (e.g., breakpoint helpers, responsive widths).
For sharing base structural styles statically, @extend on placeholders is acceptable.
Avoid @extend across unrelated components – it can cause selector bloat and source‑order surprises.

Variables and design tokens

All values come from CSS custom properties (or SCSS variables). No “magic numbers” or raw colour codes.

.primary {
  background-color: clr.$surface-primary;
}

Media queries

Place media queries inside the selector they affect, keeping the layout and its responsive behaviour together.

.grid {
  display: block;

  @include mq(lg) {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
  }
}

Performance and output

Compile to a flat, single‑class selector CSS. Avoid chains like .card .card-header – use a single .card-header class instead.
Skins are applied as additional classes, so they add minimal extra specificity and can be combined freely.
Unused placeholders and skin classes can be easily removed from the output by only importing what is required, keeping the final bundle lean.

10 August 2026