Skip to content

Commit

Permalink
Document plain CSS function/mixin preparation (sass#1028)
Browse files Browse the repository at this point in the history
  • Loading branch information
nex3 committed Apr 30, 2024
1 parent 85faf5c commit 9c50925
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 9 deletions.
8 changes: 4 additions & 4 deletions source/documentation/at-rules/function.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions source/documentation/at-rules/mixin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
40 changes: 40 additions & 0 deletions source/documentation/breaking-changes/css-function-mixin.md
Original file line number Diff line number Diff line change
@@ -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 `--`.

0 comments on commit 9c50925

Please sign in to comment.