color-units.md.erb

---
title: "Breaking Change: Color Units"
introduction: >
  In CSS, saturation and lightness parameters always require `%` units and hue
  parameters allow any angle unit. Sass has historically ignored units for these
  functions. We're in the process of changing that.
---

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.

[`hsl()`]: ../modules#hsl

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.

[angle unit]: https://drafts.csswg.org/css-values-4/#angles

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

<% impl_status dart: '1.32.0', libsass: false, ruby: false %>

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

<% impl_status dart: false, libsass: false, ruby: false %>

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.

[Dart Sass compatibility policy]: https://github.com/sass/dart-sass#compatibility-policy

## Phase 3

<% impl_status dart: false, libsass: false, ruby: false %>

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).