From 0aabec51c6bdf15d7afa5e80f1704e289117519e Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Mon, 31 Jul 2023 17:20:22 -0700
Subject: [PATCH] Document deprecating passing null as alpha in the JS/Dart
 APIs

See sass/sass#2831
---
 .../documentation/breaking-changes/index.md   |  4 ++
 .../breaking-changes/null-alpha.md            | 57 +++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 source/documentation/breaking-changes/null-alpha.md

diff --git a/source/documentation/breaking-changes/index.md b/source/documentation/breaking-changes/index.md
index 11a68c379..09985f339 100644
--- a/source/documentation/breaking-changes/index.md
+++ b/source/documentation/breaking-changes/index.md
@@ -22,6 +22,10 @@ time-sensitive, so they may be released with new minor version numbers instead.
 
 These breaking changes are coming soon or have recently been released:
 
+* [Passing `null` as an alpha channel to `new SassColor()` is changing
+  behavior](/documentation/breaking-changes/null-alpha) beginning in Dart
+  Sass 1.64.3.
+
 * [Loading Sass as a default export in JS is no longer
   allowed](/documentation/breaking-changes/default-export) beginning in Dart
   Sass 1.63.0.
diff --git a/source/documentation/breaking-changes/null-alpha.md b/source/documentation/breaking-changes/null-alpha.md
new file mode 100644
index 000000000..e90049e3b
--- /dev/null
+++ b/source/documentation/breaking-changes/null-alpha.md
@@ -0,0 +1,57 @@
+---
+title: "Breaking Change: Null Alpha Channel"
+introduction: |
+  Prior to Dart Sass 1.64.3, in the JS and Dart APIs, if `null` was passed to
+  the `SassColor` constructor it would be treated as 1. This is now deprecated.
+  Users should explicitly pass 1 or `undefined` instead.
+---
+
+Sass is working on adding support for the [CSS Color Module Level 4]. One of the
+changes in this module is the idea of ["missing components"]: if a color
+component like `alpha` is missing, it's mostly treated as 0, but if it's
+interpolated with another color (such as in a gradient or an animation) it will
+automatically take on the other color's value.
+
+[CSS Color Module Level 4]: https://www.w3.org/TR/css-color-4/
+["missing components"]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+
+We need a way for users of the JS and Dart APIs to access and set missing
+channels, and `null` is the most natural way to do that. In most cases, this
+isn't an issue; callers who intend to create opaque colors usually just leave
+out the `alpha` parameter anyway (or pass `undefined` in JS). But if callers are
+explicitly passing `null`, that will eventually be treated as a transparent
+color instead of an opaque one.
+
+To preserve the current behavior, all you need to do is explicitly pass 1 if
+`alpha` is unset. In JS:
+
+```js
+new sass.SassColor({
+  red: 102,
+  green: 51,
+  blue: 153,
+  alpha: alpha ?? 1,
+});
+```
+
+And in Dart:
+
+```dart
+sass.SassColor.rgb(102, 51, 153, alpha ?? 1);
+```
+
+{% funFact %}
+  The TypeScript types for the Sass API already forbid passing `null` as
+  `alpha`; it's only allowed to be absent, `undefined`, or a `Number`. But prior
+  to Dart Sass 1.64.3, if you weren't using TypeScript and you _did_ pass `null`
+  it would still be treated as an opaque color.
+{% endfunFact %}
+
+## Transition Period
+
+{% compatibility 'dart: "1.64.3"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
+
+Between Dart Sass 1.64.3 and the upcoming release of support for CSS Colors
+Level 4, Dart Sass will continue to interpret a `null` `alpha` value as an opaque
+color. However, it will emit a deprecation warning to encourage authors to
+explicitly pass `alpha` 1 instead.