Architecture & Organization

The 7-1 Pattern

The 7-1 architecture organizes Sass into seven folder types plus one entry file. Abstracts (variables, functions, mixins), vendors, base, layout, components, pages, and themes — all imported by a single main.scss.

This pattern scales from medium projects to enterprise design systems. Each folder has a clear responsibility, making it easy for team members to find and modify styles.

• Each partial starts with underscore: _button.scss
• main.scss only contains @use/@forward statements
• One component per file in the components folder

sass/
├── abstracts/    # _variables, _mixins, _functions
├── vendors/      # Third-party overrides
├── base/         # _reset, _typography
├── layout/       # _header, _footer, _grid
├── components/   # _button, _card, _modal
├── pages/        # _home, _dashboard
├── themes/       # _dark, _light
└── main.scss     # Entry point

File Organization Principles

Group by component, not by property type. A _button.scss contains all button styles — base, variants, sizes, and states. Avoid splitting .btn { color } and .btn { padding } into separate files.

Co-locate component styles with their variants. When a designer adds a "ghost" button variant, everything lives in _button.scss.

// components/_button.scss
@use '../abstracts/variables' as *;
@use '../abstracts/mixins' as *;

.btn { /* base styles */ }
.btn--primary { /* variant */ }
.btn--ghost   { /* variant */ }
.btn--sm      { /* size */ }
.btn--lg      { /* size */ }

Naming Conventions

Consistent naming prevents conflicts and aids discovery. BEM (Block__Element--Modifier) is the most common convention in Sass projects. Prefix utility classes with u- and layout classes with l- or layout-.

Document naming rules in a CONTRIBUTING.md. Enforce them with Stylelint custom rules or regex patterns.

// Block
.card { }
// Element
.card__title { }
.card__body { }
// Modifier
.card--featured { }
.card--compact { }

Scalability Strategies

As projects grow, split monolithic component files into sub-files imported by an index. Use @forward in barrel files to maintain a clean public API.

Design tokens should live in abstracts and be the single source of truth. Components reference tokens, never hard-coded values. This makes global design changes a token update, not a find-and-replace.

• Limit file size to ~200 lines — split when larger
• Use git blame friendly file names matching component names
• Review CSS output size when adding new abstractions

// components/_index.scss
@forward 'button';
@forward 'card';
@forward 'modal';
@forward 'form';

Team Workflow

Establish a PR review checklist: no hard-coded colors, no nesting beyond 3 levels, all new components have a partial file. Use Stylelint with sass-specific plugins for automated enforcement.

Run sass --no-source-map --style=compressed in CI to catch compilation errors before merge. A broken Sass file should never reach production.

// .stylelintrc.json
{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "max-nesting-depth": 3,
    "scss/at-mixin-pattern": "^[a-z][a-z0-9-]+$"
  }
}