SCSS Architecture for Large Projects

Popular SCSS Architecture Methodologies

1. The 7-1 Pattern

One of the most popular architectures for SCSS projects, the 7-1 pattern organizes code into 7 folders and 1 main file:

scss/
|
|– abstracts/            # Tools and helpers
|   |– _variables.scss   # Variables
|   |– _functions.scss   # Functions
|   |– _mixins.scss      # Mixins
|   |– _placeholders.scss # Placeholders
|
|– base/                 # Project foundation
|   |– _reset.scss       # Reset/normalize
|   |– _typography.scss  # Typography rules
|   |– _animations.scss  # Animations
|
|– components/           # Specific UI components
|   |– _buttons.scss     # Buttons
|   |– _carousel.scss    # Carousel
|   |– _dropdown.scss    # Dropdown
|
|– layout/               # Layout-related sections
|   |– _header.scss      # Header
|   |– _footer.scss      # Footer
|   |– _sidebar.scss     # Sidebar
|   |– _grid.scss        # Grid system
|
|– pages/                # Page-specific styles
|   |– _home.scss        # Home page
|   |– _about.scss       # About page
|
|– themes/               # Theme variations
|   |– _default.scss     # Default theme
|   |– _dark.scss        # Dark theme
|
|– vendors/              # Third-party CSS
|   |– _bootstrap.scss   # Bootstrap
|   |– _jquery-ui.scss   # jQuery UI
|
`– main.scss             # Main file that imports all other files

2. ITCSS (Inverted Triangle CSS)

ITCSS organizes code in layers of increasing specificity, from generic to explicit, far-reaching to localized:

3. SMACSS (Scalable and Modular Architecture for CSS)

SMACSS categorizes CSS rules into five types:

• Base: Default styles for HTML elements
• Layout: Major layout components (header, footer, grid)
• Module: Reusable, modular components
• State: Describes how modules look in different states
• Theme: Visual appearance (colors, typography)

Naming Conventions

BEM (Block, Element, Modifier)

BEM is a naming methodology that helps create reusable components and code sharing in front-end development:

/* Block component */
.card {
  background: #fff;
  border-radius: 4px;
  
  /* Element that depends on the block */
  &__header {
    padding: 1rem;
    border-bottom: 1px solid #eee;
    
    /* Modifier that changes the style of the element */
    &--highlighted {
      background-color: #fafafa;
    }
  }
  
  /* Element */
  &__body {
    padding: 1rem;
  }
  
  /* Modifier that changes the style of the block */
  &--featured {
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  }
}

BEMIT (BEM with ITCSS)

BEMIT combines BEM naming with namespaces inspired by ITCSS:

/* Component (from Components layer) */
.c-card { }
.c-card__header { }

/* Object (from Objects layer) */
.o-grid { }
.o-grid__item { }

/* Utility (from Utilities layer) */
.u-text-center { }

/* Theme (from Theme layer) */
.t-dark { }

/* State classes */
.is-active { }
.has-loaded { }

File Organization Strategies

Partials and Imports

Breaking SCSS into partials helps organize code and improves maintainability:

// main.scss - The entry point that imports all other files

// 1. Configuration and helpers
@import 'abstracts/variables';
@import 'abstracts/functions';
@import 'abstracts/mixins';

// 2. Vendors
@import 'vendors/normalize';

// 3. Base stuff
@import 'base/base';
@import 'base/typography';

// 4. Layout components
@import 'layout/header';
@import 'layout/footer';

// 5. Components
@import 'components/buttons';
@import 'components/cards';
@import 'components/forms';

// 6. Page-specific styles
@import 'pages/home';
@import 'pages/contact';

// 7. Themes
@import 'themes/default';

Index Files

Using index files in each folder can simplify imports:

// components/_index.scss
@import 'buttons';
@import 'cards';
@import 'forms';
@import 'modals';
@import 'navigation';

// main.scss
@import 'abstracts/index';
@import 'vendors/index';
@import 'base/index';
@import 'layout/index';
@import 'components/index';  // Imports all component files
@import 'pages/index';
@import 'themes/index';

Advanced Techniques for Large Projects

Component-Based Architecture

For large applications, especially those using modern frameworks like React, Vue, or Angular, a component-based architecture works well:

src/
|
|– components/
|   |– Button/
|   |   |– _button.scss    # Component-specific styles
|   |   |– Button.jsx      # Component logic
|   |   |– index.js        # Export
|   |
|   |– Card/
|   |   |– _card.scss
|   |   |– Card.jsx
|   |   |– index.js
|   |
|   |– ...
|
|– styles/
|   |– abstracts/          # Global variables, mixins, etc.
|   |– base/               # Global styles
|   |– themes/             # Theme configurations
|   |– _index.scss         # Main SCSS file that imports global styles
|
|– ...

Design System Integration

For enterprise applications, integrating with a design system provides consistency:

// design-system/_tokens.scss
$colors: (
  'primary': #0066cc,
  'secondary': #6c757d,
  'success': #28a745,
  'danger': #dc3545,
  'warning': #ffc107,
  'info': #17a2b8
);

$spacing: (
  'xs': 0.25rem,
  'sm': 0.5rem,
  'md': 1rem,
  'lg': 1.5rem,
  'xl': 3rem
);

$typography: (
  'family': ('sans-serif': 'Roboto, "Helvetica Neue", Arial, sans-serif'),
  'size': (
    'xs': 0.75rem,
    'sm': 0.875rem,
    'md': 1rem,
    'lg': 1.25rem,
    'xl': 1.5rem
  ),
  'weight': (
    'light': 300,
    'regular': 400,
    'medium': 500,
    'bold': 700
  )
);

// Using design tokens in components
.button {
  padding: map-get($spacing, 'sm') map-get($spacing, 'md');
  font-size: map-get(map-get($typography, 'size'), 'md');
  font-weight: map-get(map-get($typography, 'weight'), 'medium');
  
  &--primary {
    background-color: map-get($colors, 'primary');
  }
}

Feature-Based Organization

For very large applications, organizing by feature rather than type can be more efficient:

src/
|
|– features/
|   |– Authentication/
|   |   |– components/
|   |   |   |– LoginForm/
|   |   |   |– SignupForm/
|   |   |– styles/
|   |   |   |– _authentication.scss
|   |
|   |– Dashboard/
|   |   |– components/
|   |   |– styles/
|   |   |   |– _dashboard.scss
|   |   |   |– _widgets.scss
|   |
|   |– UserProfile/
|   |   |– components/
|   |   |– styles/
|   |
|   |– ...
|
|– shared/
|   |– components/
|   |– styles/
|   |   |– abstracts/
|   |   |– base/
|
|– styles/
|   |– main.scss

Best Practices for SCSS Architecture

Documentation

Document your architecture to help team members understand and follow it:

////
/// Button Component
/// @group Components
////

/// Button base styles
/// @example
///   Default Button
///   Primary Button
.button {
  // Button styles...
}

Style Guide Integration

Use tools like Storybook or Pattern Lab to create living documentation:

Code Reviews and Standards

• Establish coding standards for SCSS
• Use linters like Stylelint to enforce standards
• Include SCSS architecture review in code review process
• Regularly refactor to maintain architectural integrity

Performance Considerations

• Avoid deeply nested selectors (no more than 3 levels)
• Use mixins judiciously to prevent code bloat
• Consider code splitting for large applications
• Implement critical CSS strategies

Case Study: Refactoring a Large Codebase

Before: Problematic CSS

/* Disorganized CSS with specificity issues and duplication */
#header {
  background: #333;
}

.navigation ul li a {
  color: white;
  font-weight: bold;
}

.navigation ul li a:hover {
  color: #ccc;
}

.btn-blue {
  background: blue;
  color: white;
  padding: 10px 15px;
  border-radius: 4px;
}

.btn-red {
  background: red;
  color: white;
  padding: 10px 15px;
  border-radius: 4px;
}

/* Duplicated styles in different sections */
.sidebar .button {
  padding: 10px 15px;
  border-radius: 4px;
  background: green;
}

/* Inconsistent naming */
.userAvatar {
  border-radius: 50%;
}

.user_name {
  font-weight: bold;
}

After: Refactored with 7-1 Pattern and BEM

// abstracts/_variables.scss
$colors: (
  'primary': blue,
  'secondary': red,
  'tertiary': green,
  'dark': #333,
  'light': white,
  'muted': #ccc
);

$border-radius: 4px;
$padding-button: 10px 15px;

// components/_buttons.scss
.c-button {
  padding: $padding-button;
  border-radius: $border-radius;
  display: inline-block;
  
  &--primary {
    background: map-get($colors, 'primary');
    color: map-get($colors, 'light');
  }
  
  &--secondary {
    background: map-get($colors, 'secondary');
    color: map-get($colors, 'light');
  }
  
  &--tertiary {
    background: map-get($colors, 'tertiary');
    color: map-get($colors, 'light');
  }
}

// layout/_header.scss
.l-header {
  background: map-get($colors, 'dark');
}

// components/_navigation.scss
.c-navigation {
  &__link {
    color: map-get($colors, 'light');
    font-weight: bold;
    
    &:hover {
      color: map-get($colors, 'muted');
    }
  }
}

// components/_user.scss
.c-user {
  &__avatar {
    border-radius: 50%;
  }
  
  &__name {
    font-weight: bold;
  }
}

Implementation Strategy

1. Audit existing CSS to identify patterns and issues
2. Create the new architecture structure
3. Extract variables, mixins, and functions
4. Refactor components one by one
5. Implement gradually to avoid breaking changes
6. Add documentation and style guide

Resources and Further Reading

Books and Articles

• Sass Guidelines by Hugo Giraudel
• SMACSS by Jonathan Snook
• BEMIT by Harry Roberts
• ITCSS: Scalable and Maintainable CSS Architecture

Tools

• Stylelint - A powerful linter for enforcing SCSS conventions
• Storybook - Tool for developing UI components in isolation
• Dart Sass - The primary implementation of Sass

Example Repositories

• Sass Boilerplate - A boilerplate for Sass projects using the 7-1 pattern
• Bootstrap - Study how Bootstrap organizes its SCSS
• Foundation - Another example of SCSS architecture in a large framework