Breaking Change: Color Units

It’s important that we keep Sass’s implementation of hsl() consistent with the CSS spec, and that we keep other Sass functions that deal with colors consistent with hsl(). One notable place where Sass has historically differed from the spec is the way that hsl() (and other color functions) handled units.

For hue, CSS allows any angle unit (deg, grad, rad, or turn). It also allows a unitless number, which is interpreted as deg. Historically, Sass has allowed any unit, and interpreted it as deg. This is particularly problematic because it meant that the valid CSS expression hsl(0.5turn, 100%, 50%) would be allowed by Sass but interpreted entirely wrong.

For lightness and saturation, CSS only allows % units. Even unitless numbers aren’t allowed (unlike for the hue). Historically, Sass has allowed any unit, and interpreted it as %. You could even write hsl(0, 100px, 50s) and Sass would return the color red.

To fix this issue and bring Sass in line with the CSS spec, we’re making changes in multiple phases:

Phase 1 permalinkPhase 1

Compatibility:

Dart Sass

since 1.32.0

LibSass

✗

Ruby Sass

✗

To begin with, we’re just introducing deprecation warnings for behaviors that we plan to change. Specifically, Sass will emit a deprecation warning if you do any of the following:

• Pass a number with a unit other than deg as a hue to any function. Passing a unitless number is still allowed.

• Pass a unitless number as saturation or lightness to any function.

• Pass a number with a unit other than % as saturation or lightness to any function.

Of these warnings, the first is the most important one to deal with immediately specifically if you’re passing a number with unit grad, rad, or turn. This case will change behavior in Phase 2, which could change how your stylesheets render if you don’t update them.

Phase 2 permalinkPhase 2

Compatibility:

Dart Sass

✗

LibSass

✗

Ruby Sass

✗

At least three months after the launch of Phase 1, we’ll change the way angle units are handled for hue parameters to match the CSS spec. This means that numbers with grad, rad, or turn units will be converted to deg: 0.5turn will be converted to 180deg, 100grad will be converted to 90deg, and so on.

Because this change is necessary to preserve CSS compatibility, according to the Dart Sass compatibility policy it will be made with only a minor version bump. However, it changes as little behavior as possible to ensure that Sass interprets all valid CSS according to the CSS spec. All other deprecated behavior will remain in place until Phase 3.

Phase 3 permalinkPhase 3

Compatibility:

Dart Sass

✗

LibSass

✗

Ruby Sass

✗

Finally, we’ll remove all deprecated behavior by making color functions throw errors if they’re passed any units that produced deprecation warnings in Phase 1. Because this is a breaking change that’s not strictly necessary for CSS compatibility, we’ll land it as part of Dart Sass 2.0.0 (which we have no immediate plans to release).