How to migrate SCSS March 2025

May 21, 2025

Migrating from Legacy Sass to Modern Sass

With recent changes to the Sass ecosystem, it’s important to modernize your project to ensure long-term maintainability and compatibility. This guide outlines the most important updates and provides recommendations for upgrading from legacy Sass.

1. `@import` is Deprecated

The old @import rule is no longer used. You should now use:

@use — to load and access a file’s variables, mixins, or functions.
@forward — to re-export content from one file through another (e.g., via an index.scss file).

This new system improves modularity and prevents naming collisions through namespacing.

2. Explicit Imports Are Required

In modern Sass, nothing is globally available by default. If you want to use a variable, mixin, or function, you must import it using @use in every file where it’s needed.

// Instead of relying on global scope
@use "../styles/mixins" as mixins;

.button {
  @include mixins.rounded();
}

3. Mixins Live With Components

The old global mixins folder is gone. Each mixin should now be defined alongside the component it belongs to. This encourages better encapsulation and keeps component logic self-contained.

4. Container Values Live in Vars

All container-related values should now reside in the vars file. There is no longer a split between vars and CSS declarations — this centralizes layout configuration.

5. Define Project Paths in One Place

Use the shared src/scss/_paths.scss file to define reusable project paths. This simplifies maintenance and provides a single source of truth for path configuration.

6. Foundations → Utilities

The following items are no longer considered foundations and are now classified as utilities:

aspect-ratio

order

spacing (e.g., f—mt-2)

This helps simplify the role of foundations and separates layout utilities from core style definitions.

7. sections Are Deprecated

The sections category is no longer used. If needed in a specific project, you can define them manually, but they’re not part of the new default architecture.

Working with Maps

Map access has changed with the module system. You now need to explicitly import the sass:map module where needed:

@use "sass:map";

$color: map.get($color-options, g);

Color Functions via sass:color

@use "sass:color";

// Adjust a color’s lightness by a fixed amount
background-color: color.adjust(map.get($color-options, g), $lightness: 30%);

// Override specific properties of a color
background-color: color.change(map.get($color-options, g), $lightness: 80%);

// Scale a color’s lightness proportionally
background-color: color.scale(map.get($color-options, g), $lightness: 30%);

By following this guide, you’ll ensure that your Sass projects are clean, modern, and aligned with the latest best practices. Transitioning may take some effort, but it will lead to more scalable and maintainable code in the long run.