From 9c50925646be3050aae1eac68f2e78f761991411 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Tue, 30 Apr 2024 14:20:02 -0700 Subject: [PATCH] Document plain CSS function/mixin preparation (#1028) See #979 --- source/documentation/at-rules/function.md | 8 ++-- source/documentation/at-rules/mixin.md | 10 ++--- .../breaking-changes/css-function-mixin.md | 40 +++++++++++++++++++ 3 files changed, 49 insertions(+), 9 deletions(-) create mode 100644 source/documentation/breaking-changes/css-function-mixin.md diff --git a/source/documentation/at-rules/function.md b/source/documentation/at-rules/function.md index eabf3539b..4a5b6c828 100644 --- a/source/documentation/at-rules/function.md +++ b/source/documentation/at-rules/function.md @@ -9,10 +9,10 @@ introduction: > --- Functions are defined using the `@function` at-rule, which is written `@function -() { ... }`. 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. +() { ... }`. 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 diff --git a/source/documentation/at-rules/mixin.md b/source/documentation/at-rules/mixin.md index aa9cff8ea..6dd821afe 100644 --- a/source/documentation/at-rules/mixin.md +++ b/source/documentation/at-rules/mixin.md @@ -9,11 +9,11 @@ introduction: > Mixins are defined using the `@mixin` at-rule, which is written `@mixin { ... }` or `@mixin name() { ... }`. 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 diff --git a/source/documentation/breaking-changes/css-function-mixin.md b/source/documentation/breaking-changes/css-function-mixin.md new file mode 100644 index 000000000..611679acc --- /dev/null +++ b/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 `--`.