Document plain CSS function/mixin preparation (#1028)

See #979

Author: nex3

source/documentation/at-rules/function.md

@@ -9,10 +9,10 @@ introduction: >
 ---
 
 Functions are defined using the `@function` at-rule, which is written `@function
-<name>(<arguments...>) { ... }`. A function's name can be any Sass identifier.
-It can only contain [universal statements][], as well as the [`@return`
-at-rule][] which indicates the value to use as the result of the function call.
-Functions are called using the normal CSS function syntax.
+<name>(<arguments...>) { ... }`. A function's name can be any Sass identifier
+that doesn't begin with `--`. It can only contain [universal statements], as
+well as the [`@return` at-rule] which indicates the value to use as the result
+of the function call. Functions are called using the normal CSS function syntax.
 
 [universal statements]: /documentation/syntax/structure#universal-statements
 [`@return` at-rule]: #return

source/documentation/at-rules/mixin.md

@@ -9,11 +9,11 @@ introduction: >
 
 Mixins are defined using the `@mixin` at-rule, which is written `@mixin <name> {
 ... }` or `@mixin name(<arguments...>) { ... }`. A mixin's name can be any Sass
-identifier, and it can contain any [statement][] other than [top-level
-statements][]. They can be used to encapsulate styles that can be dropped into a
-single [style rule][]; they can contain style rules of their own that can be
-nested in other rules or included at the top level of the stylesheet; or they
-can just serve to modify variables.
+identifier that doesn't begin with `--`, and it can contain any [statement]
+other than [top-level statements]. They can be used to encapsulate styles that
+can be dropped into a single [style rule]; they can contain style rules of their
+own that can be nested in other rules or included at the top level of the
+stylesheet; or they can just serve to modify variables.
 
 [statement]: /documentation/syntax/structure#statements
 [top-level statements]: /documentation/syntax/structure#top-level-statements

source/documentation/breaking-changes/css-function-mixin.md

@@ -0,0 +1,40 @@
+---
+title: "Breaking Change: Functions and Mixins Beginning with --"
+introduction: |
+  Prior to Dart Sass 1.76.0, function and mixin names could be any valid CSS
+  identifier, but identifiers beginning with `--` are now deprecated.
+---
+
+Generally, Sass allows any valid CSS identifier to be used for any Sass
+definition. This includes identifiers which begin with `--`, which users may be
+most familiar with in the context of [CSS custom properties]. However, the CSS
+working group is [seriously considering] adding built-in support to CSS itself
+for functions and mixins, likely using at-rules named `@mixin` and `@function`
+just like Sass.
+
+[CSS custom properties]: https://www.w3.org/TR/css-variables-1/
+[seriously considering]: https://github.com/w3c/csswg-drafts/issues/9350
+
+This means that Sass, in order to preserve its core design principle of CSS
+compatibility while still supporting Sass's build-time functions and mixins,
+needs to be able to distinguish between CSS and Sass declarations that use the
+same at-rule names. Fortunately, although the details of the syntax CSS uses for
+functions and mixins is still very much up in the air, one point seems
+uncontroversial: the use of custom-property-like identifiers beginning with `--`
+for CSS mixin and function names.
+
+This will allow Sass to distinguish plain-CSS functions and mixins as those that
+begin with `--`. But in order for this to work, we first have to disallow Sass
+functions and mixins from using that prefix.
+
+## Transition Period
+
+{% compatibility 'dart: "1.76.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
+
+Between Dart Sass 1.76.0 and Dart Sass 2.0.0, Dart Sass will continue to allow
+functions and mixins whose names begin with `--`. However, it will emit a
+deprecation warning named `css-function-mixin`.
+
+Between Dart Sass 2.0.0 and the release of Dart Sass's support for plain CSS
+functions and mixins, functions and mixins will not be allowed to have names
+that begin with `--`.