How to @use() a Sass module in a file used in a quarto theme?

[xx02al]

Description

Hi quarto devs
I like many of the possibilities that quarto theming allows. One thing that is not yet clear to me is how to @use a Sass module, be it built-in or private (e.g., _companyfun.scss), in a .scss file that is a quarto theme argument value.
I would be very grateful to hear what you recommend as the preferred approach to get things work.

Below is a reprex, using quarto website, illustrating a few common use cases. I have not documented any potential solution attempts as I do not consider any of the numerous ones tried to be the one to share and I think it is most straightforward that way.

The discussion arguably nearest to link to was #11729, but I don’t think it does help here.

styles.scss

/*-- scss:defaults --*/
$pinkish: #e83e8c;

// What if we prefer to do: scale($pinkish, $lightness: 30%); where `scale()` is
// part of the Sass built-in module sass:color
$body-color: lighten($pinkish, 30%);

// What if we want to write the following function with functions that are
// not deprecated by Sass and part of sass:color, e.g., channel($color, "red")
// instead of red($color)
// https://github.com/quarto-dev/quarto-cli/blob/af454e8c07abe1c3570342c20e4fb62b33b907cb/src/resources/formats/html/_quarto-functions.scss#L6
@function colorToRGBA($color) {
    @return "rgba(" + red($color) + ", " + green($color) + ", " + blue($color) +
      ", " + alpha($color) + ")";
  }

/*-- scss:rules --*/

// And we would like to use our `colorToRGBA()` in the rules for example
h1 {
  // color: colorToRGBA($pinkish);
  color: $pinkish;
}

_quarto.yml

project:
  type: website

website:
  title: "website title"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - flatly
      - styles.scss
    toc: true

about.qmd

---
title: "About"
---

About this site

index.qmd

---
title: "Hi!"
---

This is a Quarto website.

To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

[mcanouil]

FYI / for reference purposes:

• How to use `import` for bootstrap in `scss` #11729

[xx02al]

Thanks for the quick reply @mcanouil, this is the discussion I linked to above and found it too little helpful, which is indeed my interpretation, and I would appreciate it if you could help me further

[mcanouil]

I know, but using list item makes it clearer and more accessible as the title of the issue appears in-text.
This was mostly/uniquely for accessibility reasons.
Regarding the main question, I don't have the answer.

[xx02al]

Alright, (do you think) someone else can help? And do you (as a closely involved dev person) have a few more words on what your thoughts on this are, as, in my view, it is essential that users can do such things in their custom Sass files and I would be happy to know how...!?

[cderv]

If you look at custom theme for HTML, you'll be directed to the design system for Quarto theme: https://quarto.org/docs/output-formats/html-themes-more.html

In there, you'll find the layering logic. and you'll see this

Uses
    Bootstrap
    cosmo           /*-- scss:uses --*/
    custom.scss     /*-- scss:uses --*/

It shows how the uses are layered and how you need to define them, using /*-- scss:uses --*/ so that they are inserted in the right place for them to be used.

Your custom them becomes

/*-- scss:defaults --*/
$pinkish: #e83e8c;

// What if we prefer to do: scale($pinkish, $lightness: 30%); where `scale()` is
// part of the Sass built-in module sass:color
$body-color: lighten($pinkish, 30%);

/*-- scss:uses --*/

// What if we want to write the following function with functions that are
// not deprecated by Sass and part of sass:color, e.g., channel($color, "red")
// instead of red($color)
// https://github.com/quarto-dev/quarto-cli/blob/af454e8c07abe1c3570342c20e4fb62b33b907cb/src/resources/formats/html/_quarto-functions.scss#L6
@function colorToRGBA($color) {
    @return rgba(red($color), green($color), blue($color), alpha($color));
  }

/*-- scss:rules --*/

// And we would like to use our `colorToRGBA()` in the rules for example
h1 {
  color: #{colorToRGBA($pinkish)};
}

and in the output you get

h1, .h1 {
    color: rgba(232, 62, 140, 1);
}

Note that I need to tweak your function and its usage so that the external double quotes are not in the output.

Hope it helps

[xx02al]

Hi @cderv, thanks a lot for your help. Yeah, the quarto layering is one thing that causes the troubles (this is one reason I linked to it in my question as well). Also because a stylesheet’s @use rules must come before any rules other than @forward, including style rules.

Interestingly, in your modification, it would even work to replace the, from Sass no longer recommended red(), green(), blue(), alpha(), as in my update below, without having @use 'sass:color'; anywhere in our custom .scss file.

I still do not get how to use Sass modules in general. Repeated: @use attempts error. I modified the example from above using your input, keeping the existing questions. I take the example of replacing the Sass deprecated lighten() by scale() from the Sass built-in module sass:color, but as said, it should generalize to using modules in the stylesheets.

/*-- scss:defaults --*/
$pinkish: #e83e8c;
$blueish: #1c4e8a;

// What if we prefer to do: scale($pinkish, $lightness: 30%); where `scale()` is
// part of the Sass built-in module sass:color
$body-color: lighten($pinkish, 30%);

/*-- scss:uses --*/
// Using the scss:uses functional comment we can replace the, by Sass no longer
// recommended, `red()`, `blue()`, `green()`, `alpha()` with `channel()` that is
// part of sass:color module.
// https://github.com/quarto-dev/quarto-cli/blob/af454e8c07abe1c3570342c20e4fb62b33b907cb/src/resources/formats/html/_quarto-functions.scss#L6
@function colorToRGBA($color) {
  @return rgba(
    channel($color, "red"), channel($color, "green"), channel($color, "blue"),
    channel($color, "alpha")
  );
}

/*-- scss:rules --*/
h1 {
  // We can use our `colorToRGBA()` in the rules for example
  color: #{colorToRGBA($pinkish)};
  // What if we prefer to do: scale($blueish, $lightness: 40%); where `scale()` is
  // part of the Sass built-in module sass:color
  background-color: lighten($blueish, 40%);
}

Can you please help further?

[cderv]

I am no SASS expert, so I needed to look into it further to understand what you want to do.

First, let's start by a reminder. Quarto is using Dart SASS 1.70.0. From Quarto check

[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK

Some documentation and behavior documented in the doc are for later version like
https://sass-lang.com/documentation/modules/color/#channel and some part of color.scale are also for later version https://sass-lang.com/documentation/modules/color/#scale

So color.channel() can't be used with Quarto as it was introduced in 1.79.0, per changelog of
https://github.com/sass/dart-sass/blob/e6589fe2c368715a987679194f7a4bbdea1eec68/CHANGELOG.md?plain=1#L277-L280

Another thing to understand is that some of the function are built-in SASS, and so @use sass:color is not need in older version of dart. And 1.70.0 is among them. So I think this is why it was kinda working without loading it. Also because colorToRGBA() is defined internally so it will be available to use.

However, this will change in the future, and @use "sass:color" is recommended, using color.<fun> namespace
Since 1.80.0, some deprecation warning are thrown: https://sass-lang.com/documentation/breaking-changes/import/#transition-period

That being said, let's try adapting your document using the correct layers. Using https://sass-lang.com/playground/ can also help you understand how to write SCSS.

Here is how to use color.scale

/*-- scss:defaults --*/
$pinkish: #e83e8c;
$blueish: #1c4e8a;

$body-color: color.scale($pinkish, $lightness: 30%);

/*-- scss:uses --*/
@use "sass:color";

/*-- scss:rules --*/

// And we would like to use our `colorToRGBA()` in the rules for example
h1 {
  color: #{colorToRGBA($pinkish)};
}

It works without refinding colorToRGBA because this function name is defined in Quarto itself, and it will be available through the function layer.

Does it help understand?

I'll open an issue to track update to newest DART SASS

[xx02al]

Thanks a lot @cderv for your efforts!

I must admit I missed looking up the Dart Sass version that quarto uses, and using the quarto familiar colorToRGBA() in the example was obviously unfortunate in that it is available via quarto layering. Sorry for these flaws. However, I think we have now a couple of important points together and in the few tries I made now, @use of modules (the Sass built-in ones up to 1.70.0; repeated here for completeness only) now works as I expected/wished.

I.e., for example:

/*-- scss:uses --*/
@use "sass:color";
@use "mymodule";

and the modules content is available for /*-- scss:defaults --*/, /*-- scss:rules --*/, etc. as expected.

I am looking forward to tackle my “real cases” tomorrow :)

Great that you opened an issue to update quarto to newest Dart Sass. I have set up a notification as I would like to stay on the pulse of these developments.

[cderv]

For your interest, in the next quarto release, dart has been updated to 1.85.1.

[xx02al]

Excellent!