Merge branch 'main' into port-docs-mixin-function-extend

.eslintignore

@@ -6,7 +6,7 @@
 .yarnrc.yml
 /.language/
 /_site/
-/data/
+/old_data/
 /old_source/
 /source/_data/versionCache.json
 /source/assets/dist/

.prettierignore

@@ -6,7 +6,7 @@
 .yarnrc.yml
 /.language/
 /_site/
-/data/
+/old_data/
 /old_source/
 /source/_data/versionCache.json
 /source/assets/dist/

.stylelintignore

@@ -6,7 +6,7 @@
 .yarnrc.yml
 /.language/
 /_site/
-/data/
+/old_data/
 /old_source/
 /source/_data/versionCache.json
 /source/assets/dist/

package.json

@@ -42,8 +42,8 @@
     "@11ty/eleventy": "^2.0.1",
     "@11ty/eleventy-plugin-rss": "^1.2.0",
     "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.0",
-    "@babel/core": "^7.21.8",
+    "@babel/core": "^7.22.1",
-    "@babel/preset-env": "^7.21.5",
+    "@babel/preset-env": "^7.22.2",
     "@babel/preset-typescript": "^7.21.5",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-commonjs": "^25.0.0",
@@ -57,9 +57,9 @@
     "@types/markdown-it-attrs": "^4.1.0",
     "@types/node": "^16",
     "@types/prismjs": "^1.26.0",
-    "@typescript-eslint/eslint-plugin": "^5.59.6",
+    "@typescript-eslint/eslint-plugin": "^5.59.7",
-    "@typescript-eslint/parser": "^5.59.6",
+    "@typescript-eslint/parser": "^5.59.7",
-    "cheerio": "1.0.0-rc.12",
+    "cheerio": "^1.0.0-rc.12",
     "date-fns": "^2.30.0",
     "deep-equal": "^2.2.1",
     "eslint": "^8.41.0",

source/_data/documentation.yml

@@ -69,6 +69,7 @@ toc:
       - <code>-moz-document</code>: /documentation/breaking-changes/moz-document/
       - Extending Compound Selectors: /documentation/breaking-changes/extend-compound/
       - CSS Variable Syntax: /documentation/breaking-changes/css-vars/
+      - Duplicate Variable Flags: /documentation/breaking-changes/duplicate-var-flags/
   - Command Line: /documentation/cli/
     :children:
       - Dart Sass: /documentation/cli/dart-sass/

source/_redirects

@@ -4,8 +4,14 @@
 /download             /install
 /try                  https://www.sassmeister.com
 /about                /
+
 /blog/posts/560719    /blog/dropping-support-for-old-ruby-versions
 /blog/posts/1305238   /blog/dart-sass-is-on-chocolatey
 /blog/posts/1404451   /blog/sass-and-browser-compatibility
 /blog/posts/1909151   /blog/dart-sass-is-in-beta
 /blog/posts/7081811   /blog/ruby-sass-is-deprecated
+
+/d/random-with-units  /documentation/breaking-changes/function-units
+/documentation/breaking-changes/random-with-units   /documentation/breaking-changes/function-units
+/d/color-units        /documentation/breaking-changes/function-units
+/documentation/breaking-changes/color-units         /documentation/breaking-changes/function-units

source/assets/sass/visual-design/_theme.scss

@@ -64,6 +64,6 @@ pre {
 }
 
 pre {
-  background: rgba(brand.$sl-color--midnight-blue, 0.0625);
+  background: var(--sl-color--code-background);
   border: var(--sl-border--small) solid #ebebeb;
 }

source/documentation/breaking-changes/bogus-combinators.liquid

@@ -0,0 +1,68 @@
+---
+title: 'Breaking Change: Invalid Combinators'
+introduction: >
+  Sass has historically been very permissive about the use of leading, trailing,
+  and repeated combinators in selectors. These combinators are being deprecated
+  except where they're useful for nesting.
+---
+
+{% markdown %}
+Sass has historically supported three invalid uses of combinators:
+
+* Leading combinators, as in `+ .error {color: red}`.
+
+* Trailing combinators, as in `.error + {color: red}`.
+
+* Repeated combinators, as in `div > > .error {color: red}`.
+
+None of these are valid CSS, and all of them will cause browsers to ignore the
+style rule in question. Supporting them added a substantial amount of complexity
+to Sass's implementation, and made it particularly difficult to fix various bugs
+related to the `@extend` rule. As such, we [made the decision] to remove support
+for these uses.
+
+[made the decision]: https://github.com/sass/sass/issues/3340
+
+**There is one major exception**: leading and trailing combinators may still be
+used for nesting purposes. For example, the following is still very much
+supported:
+{% endmarkdown %}
+
+{% codeExample 'bogus-combinators' %}
+.sidebar > {
+  .error {
+    color: red;
+  }
+}
+===
+.sidebar >
+  .error
+    color: red
+{% endcodeExample %}
+
+{% markdown %}
+Sass will only produce an error if a selector still has a leading or trailing
+combinator _after nesting is resolved_. Repeated combinators, on the other hand,
+will always be errors.
+
+To make sure existing stylesheets who (likely accidentally) contain invalid
+combinators, we'll support a transition period until the next major release of
+Dart Sass.
+
+## Transition Period
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.54.0', false, null, false %}{% endcompatibility %}
+
+First, we'll emit deprecation warnings for all double combinators, as well as
+leading or trailing combinators that end up in selectors after nesting is
+resolved.
+
+{% render 'documentation/snippets/silence-deprecations' %}
+
+In addition, we'll immediately start omitting selectors that we know to be
+invalid CSS from the compiled CSS, with one exception: we _won't_ omit selectors
+that begin with a leading combinator, since they may be used from a nested
+`@import` rule or `meta.load-css()` mixin. However, we don't encourage this
+pattern and will drop support for it in Dart Sass 2.0.0.
+{% endmarkdown %}

source/documentation/breaking-changes/css-vars.liquid

@@ -0,0 +1,105 @@
+---
+title: 'Breaking Change: CSS Variable Syntax'
+introduction: >
+  Older versions of LibSass and Ruby Sass parsed custom property declarations
+  just like any other property declaration, allowing the full range of
+  [SassScript expressions](/documentation/syntax/structure#expressions) as
+  values. But this wasn't compatible with CSS.
+---
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility true, '3.5.0', null, '3.5.0' %}{% endcompatibility %}
+
+{% markdown %}
+The CSS spec allows almost any string of characters to be used in a custom
+property declaration. Even though these values might not be meaningful for any
+CSS property, they could be accessed from JavaScript. When they were parsed as
+SassScript values, syntax that would have been valid plain CSS failed to parse.
+For example, the [Polymer library][] used this to support plain-CSS mixins:
+
+[Polymer library]: https://polymer-library.polymer-project.org/3.0/docs/devguide/custom-css-properties#use-custom-css-mixins
+{% endmarkdown %}
+
+{% codeExample 'css-vars', true, 'scss' %}
+:root {
+  --flex-theme: {
+    border: 1px solid var(--theme-dark-blue);
+    font-family: var(--theme-font-family);
+    padding: var(--theme-wide-padding);
+    background-color: var(--theme-light-blue);
+  };
+}
+===
+:root {
+  --flex-theme: {
+    border: 1px solid var(--theme-dark-blue);
+    font-family: var(--theme-font-family);
+    padding: var(--theme-wide-padding);
+    background-color: var(--theme-light-blue);
+  };
+}
+{% endcodeExample %}
+
+{% markdown %}
+To provide maximum compatibility with plain CSS, more recent versions of Sass
+require SassScript expressions in custom property values to be written within
+[interpolation](/documentation/interpolation). Interpolation will also work for
+older Sass versions, and so is recommended for all stylesheets.
+{% endmarkdown %}
+
+{% codeExample 'css-vars-interpolation' %}
+$accent-color: #fbbc04;
+
+:root {
+  // WRONG, will not work in recent Sass versions.
+  --accent-color-wrong: $accent-color;
+
+  // RIGHT, will work in all Sass versions.
+  --accent-color-right: #{$accent-color};
+}
+===
+$accent-color: #fbbc04
+
+:root
+  // WRONG, will not work in recent Sass versions.
+  --accent-color-wrong: $accent-color
+
+  // RIGHT, will work in all Sass versions.
+  --accent-color-right: #{$accent-color}
+===
+:root {
+  --accent-color-wrong: $accent-color;
+  --accent-color-right: #fbbc04;
+}
+{% endcodeExample %}
+
+{% headsUp false %}
+{% markdown %}
+Because interpolation removes quotation marks from quoted strings, it may be
+necessary to wrap them in the [`meta.inspect()` function][] to preserve their
+quotes.
+
+[`meta.inspect()` function]: /documentation/modules/meta#inspect
+{% endmarkdown %}
+
+{% codeExample 'css-vars-heads-up' %}
+@use "sass:meta";
+
+$font-family-monospace: Menlo, Consolas, "Courier New", monospace;
+
+:root {
+  --font-family-monospace: #{meta.inspect($font-family-monospace)};
+}
+===
+@use "sass:meta"
+
+$font-family-monospace: Menlo, Consolas, "Courier New", monospace
+
+:root
+  --font-family-monospace: #{meta.inspect($font-family-monospace)}
+===
+:root {
+  --font-family-monospace: Menlo, Consolas, "Courier New", monospace;
+}
+{% endcodeExample %}
+{% endheadsUp %}

source/documentation/breaking-changes/duplicate-var-flags.md

@@ -0,0 +1,25 @@
+---
+title: 'Breaking Change: Duplicate Variable Flags'
+introduction: >
+  Variables will only allow a single `!global` or `!default` flag. Duplicate
+  flags never had any additional effect, this just ensures that stylesheets are
+  more consistent.
+---
+
+## Phase 1
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '2.0.0', false, null, false %}{% endcompatibility %}
+
+Starting in Dart Sass 2.0.0, if a single variable declaration has more than one
+each `!global` or `!default` flag, this will be a syntax error. This means that
+`$var: value !default !default` will be forbidden. `$var: value !global
+!default` will still be allowed.
+
+## Transition Period
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.62.0', false, null, false %}{% endcompatibility %}
+
+Until Dart Sass 2.0.0 is released, multiple copies of a flag just produce
+deprecation warnings.

source/documentation/breaking-changes/extend-compound.liquid

@@ -0,0 +1,117 @@
+---
+title: 'Breaking Change: Extending Compound Selectors'
+introduction: >
+  LibSass currently allows compound selectors like `.message.info` to be
+  [extended](/documentation/at-rules/extend), but the way it was extended
+  doesn't match the way `@extend` is meant to work.
+---
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility true, false, null, false %}{% endcompatibility %}
+
+{% markdown %}
+When one selector extends another, Sass styles all elements that match the
+extender as though they also match the class being extended. In other words, if
+you write `.heads-up {@extend .info}`, it works just like you replaced
+`class="heads-up"` in your HTML with `class="heads-up info"`.
+
+Following that logic, you'd expect that `.heads-up {@extend .message.info}` to
+work like replacing `class="heads-up"` with `class="heads-up info message"`. But
+that's not how it works right now in LibSass and Ruby Sass--instead of adding
+`.heads-up` to every selector that has *either `.info` or `.message`*, it only
+adds it to selectors that have *`.info.message` together*.
+{% endmarkdown %}
+
+{% codeExample 'extend-compound-bad', false %}
+// These should both be extended, but they won't be.
+.message {
+  border: 1px solid black;
+}
+.info {
+  font-size: 1.5rem;
+}
+
+.heads-up {
+  @extend .message.info;
+}
+===
+// These should both be extended, but they won't be.
+.message
+  border: 1px solid black
+
+.info
+  font-size: 1.5rem
+
+
+.heads-up
+  @extend .message.info
+{% endcodeExample %}
+
+{% markdown %}
+To fix this issue, avoid more confusion, and keep the implementation clean and
+efficient the ability to extend compound selectors is unsupported in Dart Sass
+and will be removed in a future version of LibSass. For compatibility, users
+should extend each simple selector separately instead:
+{% endmarkdown %}
+
+{% codeExample 'extend-compound-good' %}
+.message {
+  border: 1px solid black;
+}
+.info {
+  font-size: 1.5rem;
+}
+
+.heads-up {
+  @extend .message, .info;
+}
+===
+.message
+  border: 1px solid black
+
+.info
+  font-size: 1.5rem
+
+
+.heads-up
+  @extend .message, .info
+{% endcodeExample %}
+
+{% headsUp false %}
+{% markdown %}
+Because Sass doesn't know the details of the HTML the CSS is going to style, any
+`@extend` might need to generate extra selectors that won't apply to your HTML
+in particular. This is especially true when switching away from extending
+compound selectors.
+
+Most of the time, these extra selectors won't cause any problems, and will only
+add a couple extra bytes to gzipped CSS. But some stylesheets might be relying
+more heavily on the old behavior. In that case, we recommend replacing the
+compound selector with a [placeholder selector][].
+
+[placeholder selector]: /documentation/style-rules/placeholder-selectors
+{% endmarkdown %}
+
+{% codeExample 'extend-compound-heads-up' %}
+// Instead of just `.message.info`.
+%message-info, .message.info {
+  border: 1px solid black;
+  font-size: 1.5rem;
+}
+
+.heads-up {
+  // Instead of `.message.info`.
+  @extend %message-info;
+}
+===
+// Instead of just `.message.info`.
+%message-info, .message.info
+  border: 1px solid black
+  font-size: 1.5rem
+
+
+.heads-up
+  // Instead of `.message.info`.
+  @extend %message-info
+{% endcodeExample %}
+{% endheadsUp %}

source/documentation/breaking-changes/function-units.liquid

@@ -0,0 +1,229 @@
+---
+title: 'Breaking Change: Strict Function Units'
+introduction: >
+  Various built-in functions will become stricter in which units they allow
+  and will handle those units more consistently. This makes Sass more compatible
+  with the CSS spec and helps catch errors more quickly.
+---
+
+{% markdown %}
+## Hue
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.32.0', false, null, false %}{% endcompatibility %}
+
+When specifying a color's 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
+
+To fix this issue and bring Sass in line with the CSS spec, we're making changes
+in multiple phases:
+
+### Phase 1{#hue-phase-1}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.32.0', false, null, false %}{% endcompatibility %}
+
+At first, Sass just emitted a deprecation warning if you passed a number with a
+unit other than `deg` as a hue to any function. Passing a unitless number is
+still allowed.
+
+### Phase 2{#hue-phase-2}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.52.1', false, null, false %}{% endcompatibility %}
+
+Next, we changed 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 was 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.
+
+[Dart Sass compatibility policy]: https://github.com/sass/dart-sass#compatibility-policy
+
+### Phase 3{#hue-phase-3}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+Finally, in Dart Sass 2.0.0 color functions will throw errors if they're passed
+a hue parameter with a non-angle unit. Unitless hues will still be allowed.
+
+## Saturation and Lightness
+
+When specifying an HSL color's saturation and lightness, 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 two phases:
+
+### Phase 1{#saturation-lightness-phase-1}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.32.0', false, null, false %}{% endcompatibility %}
+
+Currently, Sass just emits a deprecation warning if you pass a number with no
+unit or a unit other than `%` as a lightness or saturation to any function.
+
+### Phase 2{#saturation-lightness-phase-2}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+In Dart Sass 2.0.0 color functions will throw errors if they're passed a
+saturation or lightness parameter with no unit or a non-`%` unit.
+
+## Alpha
+
+When specifying a color's alpha value, CSS (as of [Colors Level 4]) allows
+either unitless values between 0 and 1 or `%` values between `0%` and `100%`. In
+most cases Sass follows this behavior, but the functions `color.adjust()` and
+`color.change()` have historically allowed *any* unit, and interpreted it as
+unitless. You could even write `color.change(red, $alpha: 1%)` and Sass would
+return the opaque color `black`.
+
+[Colors Level 4]: https://www.w3.org/TR/css-color-4/#typedef-alpha-value
+
+To fix this issue and bring Sass in line with the CSS spec, we're making changes
+in three phases:
+
+### Phase 1{#alpha-phase-1}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.56.0', false, null, false %}{% endcompatibility %}
+
+Currently, Sass just emits a deprecation warning if you pass a number with any
+unit, including `%`, as an alpha value to `color.change()` or `color.adjust()`.
+
+### Phase 2{#alpha-phase-2}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+Next, we'll change the way `%` units are handled for the alpha argument to
+`color.change()` and `color.adjust()`. Alphas with unit `%` will be divided by
+`100%`, converting them to unitless numbers between 0 and 1.
+
+Because this change is a bug fix that improves consistency with other Sass
+functions, it will be made with only a minor version bump. It will be changed at
+minimum three months after Phase 1 is released, to give users time to adjust
+their code and avoid the bug.
+
+[Dart Sass compatibility policy]: https://github.com/sass/dart-sass#compatibility-policy
+
+### Phase 3{#alpha-phase-3}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+Finally, in Dart Sass 2.0.0 `color.change()` and `color.adjust()` will throw
+errors if they're passed an alpha parameter with a non-`%` unit. Unitless alphas
+will still be allowed.
+
+## `math.random()`
+
+[The `math.random()` function] has historically ignored units in `$limit` and
+returned a unitless value. For example `math.random(100px)` would drop "px" and
+return a value like `42`.
+
+A future version of Sass will stop ignoring units for the `$limit` argument and
+return a random integer with the same units.
+
+[The `math.random()` function]: /documentation/modules/math#random
+{% endmarkdown %}
+
+{% codeExample 'function-units', false %}
+// Future Sass, doesn't work yet!
+@debug math.random(100px); // 42px
+===
+// Future Sass, doesn't work yet!
+@debug math.random(100px)  // 42px
+{% endcodeExample %}
+
+{% markdown %}
+### Phase 1{#math-random-phase-1}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.54.5', false, null, false %}{% endcompatibility %}
+
+Currently, Sass emits a deprecation warning if you pass a `$limit` with units to
+`math.random()`.
+
+### Phase 2{#math-random-phase-2}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+In Dart Sass 2.0.0, passing a `$limit` number with units will be an error.
+
+### Phase 3{#math-random-phase-3}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+In a minor release after Dart Sass 2.0.0, passing a `$limit` number with units
+to the `math.random()` function will be allowed again. It will return a random
+integer the same units as `$limit`, instead of a unitless number.
+
+## Weight
+
+The [`color.mix()` function] and [`color.invert()` function] have both
+historically ignored units in their `$weight` arguments, despite that argument
+conceptually representing a percentage. A future version of Sass will require
+the unit `%`.
+
+[`color.mix()` function]: /documentation/modules/color#mix
+[`color.invert()` function]: /documentation/modules/color#invert
+
+### Phase 1{#weight-phase-1}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.56.0', false, null, false %}{% endcompatibility %}
+
+Currently, Sass emits a deprecation warning if you pass a `$weight` with no
+units or with units other than `%` to `color.mix()` or `color.invert()`.
+
+### Phase 2{#weight-phase-2}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+In Dart Sass 2.0.0, `color.mix()` and `color.invert()` will throw errors if
+they're passed a `$weight` with no unit or a non-`%` unit.
+
+## Index
+
+The [`list.nth()` function] and [`list.set-nth()` function] have both
+historically ignored units in their `$n` arguments. A future version of Sass
+will forbid any units.
+
+[`list.nth()` function]: /documentation/modules/list#nth
+[`list.set-nth()` function]: /documentation/modules/list#set-nth
+
+### Phase 1{#index-phase-1}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.56.0', false, null, false %}{% endcompatibility %}
+
+Currently, Sass emits a deprecation warning if you pass a `$weight` with no
+units or with units other than `%` to `color.mix()` or `color.invert()`.
+
+### Phase 2{#index-phase-2}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility false, false, null, false %}{% endcompatibility %}
+
+In Dart Sass 2.0.0, `list.nth()` and `list.set-nth()` will throw errors if
+they're passed an index `$n` with a unit.
+{% endmarkdown %}

source/documentation/breaking-changes/index.md

@@ -0,0 +1,57 @@
+---
+title: Breaking Changes
+introduction: >
+  New versions of Sass are as backwards-compatible as possible, but sometimes
+  a breaking change is necessary. Sass needs to keep up with the evolving CSS
+  specification, and old language design mistakes occasionally need to be fixed.
+---
+
+Before each breaking change is released, Sass implementations will produce
+deprecation warnings for stylesheets whose behavior will change. Whenever
+possible, these warnings will include suggestions for how to update the
+deprecated styles to make them forward-compatible.
+
+Different implementations have different policies for breaking changes and
+deprecations. [Dart Sass][] will emit deprecation warnings for at least three
+months before releasing a breaking change, and will release the breaking change
+with a new major version number **unless that change is necessary for CSS
+compatibility**. CSS compatibility changes are often both non-disruptive and
+time-sensitive, so they may be released with new minor version numbers instead.
+
+[Dart Sass]: /dart-sass
+
+These breaking changes are coming soon or have recently been released:
+
+- [A variable may only have a single `!global` or `!default`
+  flag](/documentation/breaking-changes/duplicate-var-flags) beginning in Dart
+  Sass 1.62.0.
+
+- [Selectors with invalid combinators are
+  invalid](/documentation/breaking-changes/bogus-combinators) beginning in Dart
+  Sass 1.54.0.
+
+- [`/` is changing from a division operation to a list
+  separator](/documentation/breaking-changes/slash-div) beginning in Dart Sass
+  1.33.0.
+
+- [Functions are stricter about which units they
+  allow](/documentation/breaking-changes/function-units) beginning in Dart Sass
+  1.32.0.
+
+- [Parsing the special syntax of `@-moz-document` will be
+  invalid](/documentation/breaking-changes/moz-document) beginning in Dart Sass
+  1.7.2.
+
+- [Compound selectors could not be
+  extended](/documentation/breaking-changes/extend-compound) in Dart Sass 1.0.0
+  and Ruby Sass 4.0.0.
+
+- [The syntax for CSS custom property values
+  changed](/documentation/breaking-changes/css-vars) in Dart Sass 1.0.0, LibSass
+  3.5.0, and Ruby Sass 3.5.0.
+
+## Early Opt-In
+
+Dart Sass users can opt in to treat deprecations as errors early using the
+[`--fatal-deprecation` command line
+option](/documentation/cli/dart-sass#fatal-deprecation).

source/documentation/breaking-changes/media-logic.md

@@ -0,0 +1,32 @@
+---
+title: 'Breaking Change: Media Queries Level 4'
+introduction: >
+  Sass has added support for the CSS Media Queries Level 4 specification. This
+  originally conflicted with some Sass-specific syntax, so this syntax was
+  deprecated and is now interpreted according to the CSS standard.
+---
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.56.0', false, null, false %}{% endcompatibility %}
+
+Because Sass supports almost any Sass expression in parenthesized media
+conditions, there were a few constructs whose meaning was changed by adding full
+support for Media Queries Level 4. Specifically:
+
+- `@media (not (foo))` was historically interpreted by Sass as meaning
+  `@media (#{not (foo)})`, and so compiled to `@media (false)`.
+
+- `@media ((foo) and (bar))` and `@media ((foo) or (bar))` were similarly
+  interpreted as SassScript's logical operators, compiling to `@media (bar)` and
+  `@media (foo)` respectively.
+
+Fortunately, these came up very infrequently in practice.
+
+## Transition Period
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.54.0', false, null, false %}{% endcompatibility %}
+
+First, we emitted deprecation warnings for the previous ambiguous cases. These
+will have suggestions for how to preserve the existing behavior or how to use
+the new CSS syntax.

source/documentation/breaking-changes/moz-document.liquid

@@ -0,0 +1,42 @@
+---
+title: 'Breaking Change: -moz-document'
+introduction: >
+  Firefox used to have a @-moz-document rule requiring special parsing. As
+  support is removed from Firefox, Sass is in the process of removing support
+  for parsing them.
+---
+
+{% markdown %}
+Sass has historically supported a special parsing for the `@-moz-document` rule.
+As [Firefox dropped support for them], Sass will also drop support for the special
+parsing and will treat it as an unknown at-rule.
+
+[Firefox dropped support for them]: https://web.archive.org/web/20200528221656/https://www.fxsitecompat.dev/en-CA/docs/2018/moz-document-support-has-been-dropped-except-for-empty-url-prefix/
+
+**There is one exception**: an empty url prefix function is still allowed, as
+that's used in a hack targetting Firefox.
+{% endmarkdown %}
+
+{% codeExample 'moz-document' %}
+@-moz-document url-prefix() {
+  .error {
+    color: red;
+  }
+}
+===
+@-moz-document url-prefix()
+  .error
+    color: red
+{% endcodeExample %}
+
+{% markdown %}
+## Transition Period
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.7.2', false, null, false %}{% endcompatibility %}
+
+First, we'll emit deprecation warnings for all usages of `@-moz-document`
+except for the empty url-prefix hack.
+
+In Dart Sass 2.0, `@-moz-document` will be treated as an unknown at-rule.
+{% endmarkdown %}

source/documentation/breaking-changes/slash-div.liquid

@@ -0,0 +1,150 @@
+---
+title: 'Breaking Change: Slash as Division'
+introduction: >
+  Sass currently treats `/` as a division operation in some contexts and a
+  separator in others. This makes it difficult for Sass users to tell what any
+  given `/` will mean, and makes it hard to work with new CSS features that use
+  `/` as a separator.
+---
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility 'partial', false, null, false %}{% endcompatibility %}
+
+{% markdown %}
+Today, Sass uses [complex heuristics][] to figure out whether a `/` should be
+treated as division or a separator. Even then, as a separator it just produces
+an unquoted string that's difficult to inspect from within Sass. As more and
+more CSS features like [CSS Grid][] and the [new `rgb()` and `hsl()` syntax][]
+use `/` as a separator, this is becoming more and more painful to Sass users.
+
+[complex heuristics]: /documentation/operators/numeric#slash-separated-values
+[CSS Grid]: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row
+[new `rgb()` and `hsl()` syntax]: https://drafts.csswg.org/css-color/#rgb-functions
+
+Because Sass is a CSS superset, we're matching CSS's syntax by redefining `/` to
+be *only* a separator. `/` will be treated as a new type of list separator,
+similar to how `,` works today. Division will instead be written using the new
+`math.div()` function. This function will behave exactly the same as `/` does
+today.
+
+This deprecation does not affect uses of `/` inside `calc()` expressions.
+{% endmarkdown %}
+
+{% codeExample 'slash-div' %}
+@use "sass:math";
+
+// Future Sass, doesn't work yet!
+.item3 {
+  $row: span math.div(6, 2) / 7; // A two-element slash-separated list.
+  grid-row: $row;
+}
+===
+@use "sass:math"
+
+// Future Sass, doesn't work yet!
+.item3
+  $row: span math.div(6, 2) / 7 // A two-element slash-separated list.
+  grid-row: $row
+===
+.item3 {
+  grid-row: span 3 / 7;
+}
+{% endcodeExample %}
+
+{% markdown %}
+## Transition Period
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.33.0', false, null, false, 'math.div() and list.slash()' %}{% endcompatibility %}
+
+To ease the transition, we've begun by adding the `math.div()` function. The `/`
+operator still does division for now, but it also prints a deprecation warning
+when it does so. Users should switch all division to use `math.div()` instead.
+{% endmarkdown %}
+
+{% render 'documentation/snippets/silence-deprecations' %}
+
+{% codeExample 'math-div', false %}
+@use "sass:math";
+
+// WRONG, will not work in future Sass versions.
+@debug (12px/4px); // 3
+
+// RIGHT, will work in future Sass versions.
+@debug math.div(12px, 4px); // 3
+===
+@use "sass:math"
+
+// WRONG, will not work in future Sass versions.
+@debug (12px/4px) // 3
+
+// RIGHT, will work in future Sass versions.
+@debug math.div(12px, 4px) // 3
+{% endcodeExample %}
+
+{% markdown %}
+Slash-separated lists will also be available in the transition period. Because
+they can't be created with `/` yet, the `list.slash()` function will be added to
+create them. You will also be able to pass `"slash"` as the `$separator` to the
+[`list.join()` function][] and the [`list.append()` function][].
+
+[`list.join()` function]: /documentation/modules/list#join
+[`list.append()` function]: /documentation/modules/list#append
+{% endmarkdown %}
+
+{% codeExample 'slash-div-list' %}
+@use "sass:list";
+@use "sass:math";
+
+.item3 {
+  $row: list.slash(span math.div(6, 2), 7);
+  grid-row: $row;
+}
+===
+@use "sass:list"
+@use "sass:math"
+
+.item3
+  $row: list.slash(span math.div(6, 2), 7)
+  grid-row: $row
+===
+.item3 {
+  grid-row: span 3 / 7;
+}
+{% endcodeExample %}
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.40.0', false, null, false, 'First-class calc' %}{% endcompatibility %}
+
+{% markdown %}
+Alternatively, users can wrap division operations inside a `calc()` expression,
+which Sass will simplify to a single number.
+{% endmarkdown %}
+
+{% codeExample 'slash-div-calc', false %}
+// WRONG, will not work in future Sass versions.
+@debug (12px/4px); // 3
+
+// RIGHT, will work in future Sass versions.
+@debug calc(12px / 4px); // 3
+===
+// WRONG, will not work in future Sass versions.
+@debug (12px/4px) // 3
+
+// RIGHT, will work in future Sass versions.
+@debug calc(12px / 4px) // 3
+{% endcodeExample %}
+
+{% markdown %}
+## Automatic Migration
+
+You can use [the Sass migrator][] to automatically update your stylesheets to
+use `math.div()` and `list.slash()`.
+
+[the Sass migrator]: https://github.com/sass/migrator#readme
+
+```shellsession
+$ npm install -g sass-migrator
+$ sass-migrator division **/*.scss
+```
+{% endmarkdown %}

source/documentation/breaking-changes/strict-unary.liquid

@@ -0,0 +1,69 @@
+---
+title: 'Breaking Change: Strict Unary Operators'
+introduction: >
+  Sass has historically allowed `-` and `+` to be used in ways that make it
+  ambiguous whether the author intended them to be a binary or unary operator.
+  This confusing syntax is being deprecated.
+---
+
+{% markdown %}
+How is this property compiled?
+{% endmarkdown %}
+
+{% codeExample 'strict-unary', false %}
+$size: 10px;
+
+div {
+  margin: 15px -$size;
+}
+===
+$size: 10px
+
+div
+  margin: 15px -$size
+{% endcodeExample %}
+
+{% markdown %}
+Some users might say "the `-` is attached to `$size`, so it should be `margin:
+20px -10px`". Others might say "the `-` is between `20px` and `$size`, so it
+should be `margin: 5px`." Sass currently agrees with the latter opinion, but the
+real problem is that it's so confusing in the first place! This is a natural but
+unfortunate consequence of CSS's space-separated list syntax combined with
+Sass's arithmetic syntax.
+
+That's why we're moving to make this an error. In the future, if you want to use
+a binary `-` or `+` operator (that is, one that subtracts or adds two numbers),
+you'll need to put whitespace on both sides or on neither side:
+
+* Valid: `15px - $size`
+* Valid: `(15px)-$size`
+* Invalid: `15px -$size`
+
+If you want to use a unary `-` or `+` operator as part of a space-separated
+list, you'll (still) need to wrap it in parentheses:
+
+* Valid: `15px (-$size)`
+
+## Transition Period
+
+{% # Arguments are (in order): `dart`, `libsass`, `node`, `ruby`, optional feature name, additional details within %}
+{% compatibility '1.55.0', false, null, false %}{% endcompatibility %}
+
+We'll make this an error in Dart Sass 2.0.0, but until then it'll just emit a
+deprecation warning.
+
+{% render 'documentation/snippets/silence-deprecations' %}
+
+## Automatic Migration
+
+You can use [the Sass migrator] to automatically update your stylesheets to add
+a space after any `-` or `+` operators that need it, which will preserve the
+existing behavior of these stylesheets.
+
+[the Sass migrator]: https://github.com/sass/migrator#readme
+
+```shellsession
+$ npm install -g sass-migrator
+$ sass-migrator strict-unary **/*.scss
+```
+{% endmarkdown %}

source/documentation/snippets/silence-deprecations.liquid

@@ -0,0 +1,9 @@
+{% funFact %}
+  Remember, you can silence deprecation warnings from libraries you don't
+  control! If you're using the command-line interface you can pass the
+  [`--quiet-deps` flag], and if you're using the JavaScript API you can set the
+  [`quietDeps` option] to `true`.
+
+  [`--quiet-deps` flag]: /documentation/cli/dart-sass#quiet-deps
+  [`quietDeps` option]: /documentation/js-api/interfaces/StringOptionsWithoutImporter#quietDeps
+{% endfunFact %}