Migrate to Sass modules #41512

mdo · 2025-06-02T18:47:07Z

This is a WIP effort to pull out the Sass module changes from my v6 branch to see how minimal we can make an earlier release to get folks onto newer versions of Dart Sass, Sass modules, etc. TBD if we do this, but wanted to try over the weekend. Still a few more things to bring in here, but it's getting close. I think the _maps and _variables-dark are my current biggest problems.

Update: Original comment contents are below. I'm merging this as the main Sass modules migration for now, and will start in on the rest in v6-dev in separate efforts.

This branch aims to:

Migrate to Dart Sass only, dropping the older and deprecated Node Sass.
Replace all @import with @use and @forward, including in our documentation.
Lightly reorganize the scss/ directory with additional subfolders.
Colocate Sass variables, loops, and mixins within each stylesheet that relies on them.
Minimally revamp our theme colors, functions, and some global configuration variables to avoid circular dependency imports with the move to Sass modules. More info coming here…
Restore flex grid alongside CSS grid, update grid bundle

Optional changes that feel within reason of a more focused v6 release:

Dropping jQuery interfaces
Bumping browser support slightly
Embrace logical properties exclusively, thereby dropping our RTL bundles
Utilities: migrate aspect ratio helper to utility, some additional and more modern utilities

What's not coming that would be moved to a faster v7 release:

CSS layers
Revamping the utility API to allow multiple selector types, removing !important for layers, streamlining keys
Nearly all utilities and helpers changes
More extensive changes to theming, color modes, and colors
Dropping flexbox grid system for CSS Grid system

Probably some other things to pull out too, but wanted to spike this out.

ajiho · 2025-06-15T15:26:31Z

I'm glad to have started considering this and look forward to updates

richware · 2025-06-21T01:07:05Z

I have just spent a week converting 5.3.3 to use namespace removing all @imports and using @use/@forward. I have created a 5.3.6 version (on my system) that I would be willing to share for those using the newest version of PhpStorm which advanced dart sass and deprecated @import.

This is a temporary fix until v6 is released and I would be willing to share.

scss/layout/index.scss

scss/layout/_grid.scss

ajiho · 2025-06-22T17:05:31Z

@raajtram

I think @mdo will soon complete the migration in this area, and I am also waiting for it

Replace all @import with @use and @forward, including in our documentation.

Just for this point, it seems like we don't need to release it in v6, right?
Could it be 5.4?

mdo · 2025-06-22T17:34:04Z

Just for this point, it seems like we don't need to release it in v6, right?
Could it be 5.4?

Not the way we want to do it. It requires changing all our imports, and to allow the new Dart Sass customization methods, it feels like the right approach to refactor some things now.

It was suggested to us that we could double the number of files we have and so some custom forwarding (I think Core UI did this with their Bootstrap fork), but that pollutes the codebase and makes things much less approachable. Making the dependencies and modules super clear feels right at this time.

julien-deramond · 2025-06-26T16:17:25Z

scss/helpers/_color-bg.scss

+@use "../colors" as *;
+@use "../config" as *;
+@use "../variables" as *;
+
 // All-caps `RGBA()` function used because of this Sass bug: https://github.com/sass/node-sass/issues/2251


Just to remember checking it, maybe we can switch to rgba() or color-mix() in this file and _colored-links.scss.

julien-deramond · 2025-06-26T16:30:55Z

site/src/content/docs/components/alerts.mdx

@@ -140,7 +140,7 @@ As part of Bootstrap’s evolving CSS variables approach, alerts now use local C

 <DeprecatedIn version="5.3.0" />


Since it's going to be a major version, we'll need to get rid (and probably document in the migration guide) all the things that were deprecated in v5.

mrholek · 2025-07-03T20:31:59Z

Just for this point, it seems like we don't need to release it in v6, right?
Could it be 5.4?

Not the way we want to do it. It requires changing all our imports, and to allow the new Dart Sass customization methods, it feels like the right approach to refactor some things now.

It was suggested to us that we could double the number of files we have and so some custom forwarding (I think Core UI did this with their Bootstrap fork), but that pollutes the codebase and makes things much less approachable. Making the dependencies and modules super clear feels right at this time.

@ajiho, as @mdo mentioned, the only way to maintain backward compatibility is to double the number of files by adding a *.import.scss scss file, which is not an elegant solution.

theodorejb · 2025-07-17T16:30:16Z

scss/_functions.scss

 }

-// Shade a color: mix a color with black
+// // Shade a color: mix a color with black


Why are extra slashes added to three of these comments?

Just to make sure it's really really commented out. Kidding aside, it's because I commented out large sections of code and then restored sub-sections one at a time. It'll get cleaned up eventually.

…io utility

* Reorganize scss folder * Migrate to Sass modules * Migrate docs to Sass modules, comment out docs grid CSS * Give helpers folder an index.scss, migrate ratio helper to aspect-ratio utility * Delete node sass Action * Modify Sass tests to pass for new Sass modules implementation * Don't disallow calc() * Move heading classes back to Reboot to prevent a dependency * Utilities, some helpers, and theme colors * Temporary fix of docs compilation * Temporary Bundlewatch fix * docs fix import to use * Restyle docs callouts * Fix docs colors * Revert typo * Reintroduce `css-lint-vars` npm script * Bump to Sass v1.90.x * Fixes * more * Remove --------- Co-authored-by: Julien Déramond <[email protected]>

mdo force-pushed the sass-modules-only branch from 2d6dd7b to bdcdc68 Compare June 17, 2025 17:00

mdo commented Jun 21, 2025

View reviewed changes

scss/layout/index.scss Outdated Show resolved Hide resolved

scss/layout/_grid.scss Outdated Show resolved Hide resolved

mdo force-pushed the sass-modules-only branch 2 times, most recently from 77b5a29 to a66964b Compare June 22, 2025 16:26

julien-deramond force-pushed the sass-modules-only branch 3 times, most recently from 03b0c2e to 3371816 Compare June 26, 2025 15:39

julien-deramond reviewed Jun 26, 2025

View reviewed changes

julien-deramond mentioned this pull request Jul 2, 2025

Docs: fix scss autorecompile in dev mode #41574

Merged

7 tasks

julien-deramond mentioned this pull request Jul 5, 2025

Drop node-sass support #41112

Closed

22 tasks

julien-deramond force-pushed the sass-modules-only branch from 1388120 to b93b4c4 Compare July 5, 2025 11:03

mdo force-pushed the sass-modules-only branch from b93b4c4 to 0174c06 Compare July 16, 2025 17:27

theodorejb reviewed Jul 17, 2025

View reviewed changes

XanderVertegaal mentioned this pull request Jul 21, 2025

fix: importing the project using modern CSS loaders UtrechtUniversity/UU-Bootstrap#22

Open

mdo force-pushed the sass-modules-only branch from 0174c06 to 740e53c Compare August 10, 2025 18:57

mdo changed the title ~~v6: Sass modules only~~ Migrate to Sass modules Aug 26, 2025

mdo force-pushed the sass-modules-only branch from 740e53c to 81dc426 Compare August 26, 2025 23:47

mdo changed the base branch from main to v6-dev August 26, 2025 23:48

mdo force-pushed the v6-dev branch from ef5ea87 to 25aa8cc Compare August 27, 2025 04:09

mdo force-pushed the sass-modules-only branch 2 times, most recently from 0d09ba6 to d445cdc Compare August 28, 2025 03:56

mdo marked this pull request as ready for review August 28, 2025 04:00

mdo requested review from a team as code owners August 28, 2025 04:00

mdo force-pushed the v6-dev branch from e20f61c to 7f8825f Compare August 28, 2025 04:01

mdo and others added 20 commits August 27, 2025 21:01

Reorganize scss folder

bae2d7c

Migrate to Sass modules

15df189

Migrate docs to Sass modules, comment out docs grid CSS

1009af7

Give helpers folder an index.scss, migrate ratio helper to aspect-rat…

7350fbf

…io utility

Delete node sass Action

d2bfc62

Modify Sass tests to pass for new Sass modules implementation

8a479c5

Don't disallow calc()

6d522f2

Move heading classes back to Reboot to prevent a dependency

efe8fd6

Utilities, some helpers, and theme colors

96d1820

Temporary fix of docs compilation

4763790

Temporary Bundlewatch fix

ea7a19e

docs fix import to use

5014d2f

Restyle docs callouts

89cf10b

Fix docs colors

9f53660

Revert typo

e44daa2

Reintroduce css-lint-vars npm script

12e7720

Bump to Sass v1.90.x

cfbc1f6

Fixes

d4dc9c6

more

1678a76

Remove

dea3775

mdo force-pushed the sass-modules-only branch from 661ba12 to dea3775 Compare August 28, 2025 04:01

mdo merged commit 5e5ea15 into v6-dev Aug 28, 2025
7 checks passed

mdo deleted the sass-modules-only branch August 28, 2025 04:15

mdo added css v6 labels Aug 28, 2025

mdo added this to v6.0.0 Aug 28, 2025

github-project-automation bot moved this to Inbox in v6.0.0 Aug 28, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Migrate to Sass modules #41512

Migrate to Sass modules #41512

Uh oh!

mdo commented Jun 2, 2025 •

edited

Loading

Uh oh!

ajiho commented Jun 15, 2025

Uh oh!

richware commented Jun 21, 2025

Uh oh!

Uh oh!

Uh oh!

ajiho commented Jun 22, 2025

Uh oh!

mdo commented Jun 22, 2025

Uh oh!

julien-deramond Jun 26, 2025 •

edited

Loading

Uh oh!

julien-deramond Jun 26, 2025

Uh oh!

mrholek commented Jul 3, 2025

Uh oh!

theodorejb Jul 17, 2025

Uh oh!

mdo Jul 17, 2025

Uh oh!

Uh oh!

Uh oh!

		@@ -140,7 +140,7 @@ As part of Bootstrap’s evolving CSS variables approach, alerts now use local C

		<DeprecatedIn version="5.3.0" />

Uh oh!

Migrate to Sass modules #41512

Migrate to Sass modules #41512

Uh oh!

Conversation

mdo commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ajiho commented Jun 15, 2025

Uh oh!

richware commented Jun 21, 2025

Uh oh!

Uh oh!

Uh oh!

ajiho commented Jun 22, 2025

Uh oh!

mdo commented Jun 22, 2025

Uh oh!

julien-deramond Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

julien-deramond Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

mrholek commented Jul 3, 2025

Uh oh!

theodorejb Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

mdo Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mdo commented Jun 2, 2025 •

edited

Loading

julien-deramond Jun 26, 2025 •

edited

Loading