Breaking Change: Color Functions

Certain color functions that were designed with the assumption that all colors were mutually compatible no longer make sense now that Sass supports all the color spaces of CSS Color 4.

Historically, all Sass color values covered the same gamut: whether the colors were defined as RGB, HSL, or HWB, they only covered the sRGB gamut and could only represent the colors that monitors could display since the mid-1990s. When Sass added its original set of color functions, they assumed that all colors could be freely converted between any of these representations and that there was a single unambiguous meaning for each channel name like "red" or "hue".

The release of CSS Color 4 changed all that. It added support for many new color spaces with different (wider) gamuts than sRGB. In order to support these colors, Sass had to rethink the way color functions worked. In addition to adding new functions like color.channel() and color.to-space(), a number of older functions were deprecated when they were based on assumptions that no longer held true.

Old Channel FunctionsOld Channel Functions permalink

Channel names are now ambiguous across color spaces. The legacy RGB space has a red channel, but so do display-p3, rec2020, and many more. This means that color.red(), color.green(), color.blue(), color.hue(), color.saturation(), color.lightness(), color.whiteness(), color.blackness(), color.alpha(), and color.opacity() will be removed. Instead, you can use the color.channel() function to get the value of a specific channel, usually with an explicit $space argument to indicate which color space you’re working with.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:color";

$color: #c71585;
@debug color.channel($color, "red", $space: rgb);
@debug color.channel($color, "red", $space: display-p3);
@debug color.channel($color, "hue", $space: oklch);

      
      Playground
    Sass Syntax@use "sass:color"

$color: #c71585
@debug color.channel($color, "red", $space: rgb)
@debug color.channel($color, "red", $space: display-p3)
@debug color.channel($color, "hue", $space: oklch)

Single-Channel Adjustment FunctionsSingle-Channel Adjustment Functions permalink

These have the same ambiguity problem as the old channel functions, while also already being redundant with color.adjust() even before Color 4 support was added. Not only that, it’s often better to use color.scale() anyway, because it’s better suited for making changes relative to the existing color rather than in absolute terms. This means that adjust-hue(), saturate(), desaturate(), lighten(), darken(), opacify(), fade-in(), transparentize(), and fade-out() will be removed. Note that these functions never had module-scoped counterparts because their use was already discouraged.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@use "sass:color";

$color: #c71585;
@debug color.adjust($color, $lightness: 15%, $space: hsl);
@debug color.adjust($color, $lightness: 15%, $space: oklch);
@debug color.scale($color, $lightness: 15%, $space: oklch);

      
      Playground
    Sass Syntax@use "sass:color"

$color: #c71585
@debug color.adjust($color, $lightness: 15%, $space: hsl)
@debug color.adjust($color, $lightness: 15%, $space: oklch)
@debug color.scale($color, $lightness: 15%, $space: oklch)

Transition PeriodTransition Period permalink

Dart Sass: since 1.79.0
LibSass: ✗
Ruby Sass: ✗

First, we’ll emit deprecation warnings for all uses of the functions that are slated to be removed. In Dart Sass 2.0.0, these functions will be removed entirely. Attempts to call the module-scoped versions will throw an error, while the global functions will be treated as plain CSS functions and emitted as plain strings.

You can use the Sass migrator to automatically migrate from the deprecated APIs to their new replacements.

Can I Silence the Warnings?Can I Silence the Warnings? permalink

Sass provides a powerful suite of options for managing which deprecation warnings you see and when.

Terse and Verbose ModeTerse and Verbose Mode permalink

By default, Sass runs in terse mode, where it will only print each type of deprecation warning five times before it silences additional warnings. This helps ensure that users know when they need to be aware of an upcoming breaking change without creating an overwhelming amount of console noise.

If you run Sass in verbose mode instead, it will print every deprecation warning it encounters. This can be useful for tracking the remaining work to be done when fixing deprecations. You can enable verbose mode using the --verbose flag on the command line, or the verbose option in the JavaScript API.

⚠️ Heads up!

When running from the JS API, Sass doesn’t share any information across compilations, so by default it’ll print five warnings for each stylesheet that’s compiled. However, you can fix this by writing (or asking the author of your favorite framework’s Sass plugin to write) a custom Logger that only prints five errors per deprecation and can be shared across multiple compilations.

Silencing Deprecations in DependenciesSilencing Deprecations in Dependencies permalink

Sometimes, your dependencies have deprecation warnings that you can’t do anything about. You can silence deprecation warnings from dependencies while still printing them for your app using the --quiet-deps flag on the command line, or the quietDeps option in the JavaScript API.

For the purposes of this flag, a "dependency" is any stylesheet that’s not just a series of relative loads from the entrypoint stylesheet. This means anything that comes from a load path, and most stylesheets loaded through custom importers.

Silencing Specific DeprecationsSilencing Specific Deprecations permalink

If you know that one particular deprecation isn’t a problem for you, you can silence warnings for that specific deprecation using the --silence-deprecation flag on the command line, or the silenceDeprecations option in the JavaScript API.