Creating an Organized SCSS File Structure Using Modern Practices

Table of Contents

• Understanding Modern SCSS
• The Modern 7-1 Pattern
• Modern File Structure
• The Index Files
• The Main File
• Using Namespaces
• Best Practices for Modern SCSS
• Migration Tips
• Performance Considerations
• Conclusion

As a frontend developer, maintaining a clean and organized SCSS file structure is crucial for scalable and manageable styling. While SCSS (Sassy CSS) has evolved, so have the best practices for organizing your files. This guide focuses on modern SCSS practices using @use and @forward instead of the deprecated @import.

Understanding Modern SCSS

Before diving into structure, let's understand the key modern SCSS features:

• @use loads mixins, functions, and variables from other stylesheets and provides an explicit namespace
• @forward makes the public members of another module available to stylesheets that use your module
• Members are private by default and must be marked with !default to be configurable

The Modern 7-1 Pattern

The 7-1 pattern remains a solid approach but needs adaptation for modern SCSS. It consists of seven folders plus one main file, with each folder containing an index file to manage its members.

Folder Structure

1. Abstracts: Global SCSS tools and helpers

   • Variables
   • Functions
   • Mixins
   • Placeholders

2. Components: Individual UI components

   • Buttons
   • Forms
   • Cards
   • Navigation

3. Layout: Major layout sections

   • Header
   • Footer
   • Grid system
   • Navigation layouts

4. Pages: Page-specific styles

   • Home
   • About
   • Contact

5. Themes: Visual themes

   • Light theme
   • Dark theme
   • Brand variations

6. Base: Global HTML element styles

   • Reset/Normalize
   • Typography
   • Base elements

7. Vendors: Third-party styles

   • Bootstrap
   • Select2
   • Datepicker

Optional:

1. States: State-specific styles
   • Active states
   • Loading states
   • Error states

Modern File Structure

scss/
├── abstracts/
│   ├── _index.scss        // Forwards all abstract members
│   ├── _functions.scss
│   ├── _mixins.scss
│   └── _variables.scss
├── base/
│   ├── _index.scss
│   ├── _reset.scss
│   └── _typography.scss
// ... (other folders follow same pattern)
└── main.scss

The Index Files

Each folder should have an _index.scss file that forwards its members. Here's how they should look:

// abstracts/_index.scss
@forward 'variables';
@forward 'functions';
@forward 'mixins';

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

The Main File

The main file now uses @use instead of @import:

// main.scss
@use 'abstracts' as *;         // Global access to variables/mixins
@use 'vendors' as vendors;     // Namespaced access
@use 'base' as base;
@use 'components' as comp;
@use 'layout' as layout;
@use 'pages' as pages;
@use 'themes' as themes;

Using Namespaces

Modern SCSS requires explicit namespacing. Here's how to use them:

// Using namespaced members
.button {
  // From abstracts (global)
  background-color: $primary-color;

  // From components
  @include comp.button-base;

  // From vendors
  @include vendors.bootstrap-spacing;
}

Best Practices for Modern SCSS

1. Use Index Files Effectively
   • Keep index files clean and focused
   • Use @forward with show or hide to control member visibility

   @forward 'variables' show $primary-color, $secondary-color;

1. Configure Defaults
   • Mark configurable variables with !default
   • Use configuration files when needed

   // _variables.scss
   $primary-color: blue !default;

1. Namespace Management

   • Use as * sparingly (primarily for abstracts)
   • Choose clear, consistent namespace aliases
   • Document namespace conventions in your styleguide

2. Module Organization

   • One component per file
   • Use clear, consistent naming
   • Keep dependencies explicit

3. Documentation

   • Comment your configurations
   • Document your module's public API
   • Include usage examples

Migration Tips

When moving from @import to @use/@forward:

1. Start with your abstracts folder
2. Update one folder at a time
3. Test thoroughly between updates
4. Update dependent files as needed
5. Don't mix @import with @use/@forward in the same file

Performance Considerations

Modern SCSS module system provides several performance benefits:

• Modules are only executed once
• Dead code elimination is more effective
• Better dependency tracking
• Clearer dependency graph

Conclusion

Modern SCSS file structure emphasizes clarity, maintainability, and explicit dependencies. By using @use and @forward, you create a more robust and maintainable stylesheet architecture. This approach scales well with your project while providing better encapsulation and clearer dependencies.

Remember to:

• Use explicit namespacing
• Maintain clear folder structure
• Keep your index files organized
• Document your module system
• Follow consistent naming conventions

With these modern practices in place, your SCSS will be more maintainable, scalable, and easier for teams to work with.

Comments

[Helena Plantin]

The Sass team recommends to stop using @import since it is deprecated and will not be supported from version 3.0. Instead, you should use @forward and @use.

sass-lang.com/documentation/at-rul...

[joachim kliemann]

Thank you very much for your comment. I have updated the article.

[Роман Уляшев]

Can you provide a working example? Followed your article, but keep getting an error - "Undefined variable".

[Flivian mwirigi]

Noted and its a well structered article with everything i needed. Thanks