Upgrading to Modern Sass

Aug

2026

by: Jason Gonzalez

Posted in Categories: Tutorials, Web Design/Development, WordPress

In this case, Sass stands for Syntactically Awesome Style Sheets.

This tutorial is a direct follow-up to the previous tutorial Upgrading from Gulp 4 to Gulp 5, thus that one is a prerequisite. It is a prerequisite if you were using Gulp alongside Sass. However, it can be adapted for those who haven’t updated Sass but are using another build tool.

For some, Sass might be considered a legacy tool, but it is still relevant and should be updated for legacy projects.

Shall we get started?

Introduction

As mentioned in the Gulp upgrade tutorial, this is a WordPress based tutorial. You can find information on how to install WordPress for a few scenarios in that tutorial.

In the last tutorial, we left off with an adapted version of our theme the-m-x-080526, placed in a directory outside of WordPress. Will use the example as if it was placed in home/username/Development/the-m-x-080526.

It can be in any other folder, especially if you using an operating system other than Linux. Also, if you are just upgrading for your own project, you can ignore this section.

Open a terminal and navigate to wherever you stored the project:

cd ~/Development/the-m-x-080526

Let’s check the version of Sass currently used:

sass --version

We want to confirm that we are running Dart Sass.

Replacing @import syntax

In the terminal let’s run our style task.

gulp style

Upon running the above command, you will get the warning “Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.”.

Import vs. Use

Let’s take a crack at fixing this. Open the file at sass/style.scss in a text editor.

Sass no longer uses @import syntax. The reason is that every variable, mixin and function is global. On the @import page, it states “This makes it very difficult for people (or tools) to tell where anything is defined.”

The new @use syntax is the way forward, as it loads stylesheets as modules, meaning they are only loaded once per stylesheet. With the import system before, it was possible to load one stylesheet multiple times. In addition, @use uses namespaces to differentiate between one name and another, as we will see later on.

In our style.scss file, the error referenced @import "variables-site/variables-site". We can search for this term in our file.

Let’s change this to @use "variables-site/variables-site".

Re-run gulp style and you will notice the import statement error for the variables-site partial is now gone.

Since we don’t want to do this for each and every @import statement, we can do a search and replace in your text editor of choice, searching for @import and replacing with @use. Done.

We will be running gulp style quite a few times, so let’s run it once more.

@use statement order

This time we get the error @use rules must be written before any other rules. Since I wasn’t clear on how to answer, I asked Google’s AI this question:

In sass, what does the error @use rules must be written before any other rules mean?

The answer simply means that our section with the comment # Common Classes and IDs and the .hide{} style rule need to be relocated below the @use statements.

After saving, re-run gulp style to see that error disappear.

Separating CSS variables into their own module

Since stylesheets with @use are now modules, we should separate our color variables into their own module, as they will be used in many places.

Cut (Ctrl-X) the # CSS Variables comment and the entire :root { … } style rule from style.scss
Create a new file in sass/variables-site named _css-vars.scss
Paste (Ctrl-V) the root style rule into this file and Save it
In the variables-site/_variables-site.scss file, change the @import statements to @use and add @use "css-vars"; to the top
Re-run gulp style

Removing the pixel fallback from the font mixin

After this, I asked the AI “do rem CSS units need a pixel fallback nowadays?” It answered:

No, CSS rem units absolutely do not need a pixel fallback anymore.

So let’s open sass/mixins/_mixins.scss in the text editor. From there, we can remove the pixel fallback in the font-size mixin.

@mixin font-size($sizeValue: 1) {
  font-size: ($sizeValue * 16) * 1px;
  font-size: $sizeValue * 1rem;
}

Eventually, we will remove the entire mixin, as it doesn’t make sense to convert 1 to 1rem when we can type it directly. I will make this fix later.

As a matter of fact, we will fix this for one style rule as an example. Let’s open sass/typography/_headings.scss and replace the mixin reference with its direct rem value.

h1 {
  font-weight: typography.$font__weight-normal;
  @include font-size(4.5);
  font-size: 4.5rem;
  letter-spacing: -0.016rem;
}

Using @use syntax with a variable

At the top of the _headings.scss file, we now need to add an @use statement to bring in our typography CSS file. This must go before anything else.

@use "../variables-site/typography";

Within the h1 {} style rule, let’s change $font__weight-normal to typography.$font__weight-normal. This is an example of the namespacing mentioned earlier. The last part of the path in the @use statement is what we namespace our variables or mixins with. If we were importing a variable with the same name from an external sass file elsewhere, for instance, it can be used alongside ours.

Using @use syntax with a mixin

Let us now open the file sass/site/primary/_post-formats.scss. This time, we are going to import the _mixins.scss file (via use):

@use "../../mixins/mixins";

The style rule .single .format-image.has-post-thumbnail .entry-title {} uses a mixin, so let’s adjust that:

.single .format-image.has-post-thumbnail .entry-title {
  @include mixins.large-centered-text;
  top: -3.765rem;
}

Pretty easy. Now we can save the files.

Adjusted Files to Save Time

Fixing each file this way would become rapidly tedious, so I am including an updated sass directory specifically for this tutorial. Look for the mx-sass.zip file in Tutorial Resources under updating-to-modern-sass. From here, click the file name, then View Raw to download.

Once downloaded, you can extract (unzip) from your Downloads folder, delete the existing sass folder from the parent theme, and replace with the newly extracted sass folder.

This updated sass folder has the changes mentioned in the tutorial, but for every file that needed changes.

I would still advise to review the above code to learn how the new Sass handles things internally. Changing the code manually is still needed for those who are simply updating their non Gulp project.

Changing the Gulp Sass syntax

One extra change we can make in the gulpfile.js file is to change the syntax for our sass pipe. Expanded is now the standard output style and the other options have been removed. For instance in the style function…

function style() {
  return (
    gulp
      .src([
        ...
      ])
      ...
      .pipe(
        sass({
          indentType: "tab",
          indentWidth: 1,
          outputStyle: "expanded",
        })
      )
      .pipe(sass())
      ...
      .pipe(gulp.dest("./build"))
      ...
  );
}

We need to change this for the gridStyle() and wcStyle() functions, as well.

Conclusion

After updating both Gulp and Sass, we can now build our themes with our existing tools and not have to learn a whole new system. We are just learning the most recent versions of the ones we are using.

In this way, we can still easily work with our legacy projects. Thanks for reading and following along.

Featured image by 200 Degrees from Pixabay

Tags for this post: Sass, The M.X., WordPress