Document that saturate()/hue-rotate() are not in HSL space (#34609)

* Document that saturate()/hue-rotate() are not in HSL space

* Address reviews

files/en-us/web/css/filter-function/hue-rotate/index.md

@@ -9,6 +9,8 @@ browser-compat: css.types.filter-function.hue-rotate
 
 The **`hue-rotate()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) rotates the [hue](https://en.wikipedia.org/wiki/Hue) of an element and its contents. Its result is a {{cssxref("<filter-function>")}}.
 
+> **Note:** `hue-rotate()` is specified as a matrix operation on the RGB color. It does not actually convert the color to the HSL model, which is a non-linear operation. Therefore, it may not preserve the saturation or lightness of the original color, especially for saturated colors.
+
 {{EmbedInteractiveExample("pages/css/function-hue-rotate.html")}}
 
 ## Syntax
@@ -174,6 +176,53 @@ This example shows three images: the image with a `hue-rotate()` filter function
 
 {{EmbedLiveSample('With_url()_and_the_SVG_hue-rotate_filter','100%','280')}}
 
+### hue-rotate() does not preserve saturation or lightness
+
+The diagram below compares two color gradients starting with red: the first is generated using `hue-rotate()`, and the second uses actual HSL color values. Note how the `hue-rotate()` gradient shows obvious differences in saturation and lightness in the middle.
+
+```html
+<div>
+  <p>Using <code>hue-rotate()</code></p>
+  <div id="hue-rotate"></div>
+</div>
+<div>
+  <p>Using <code>hsl()</code></p>
+  <div id="hsl"></div>
+</div>
+```
+
+```css hidden
+#hue-rotate,
+#hsl {
+  display: flex;
+  margin: 1em 0;
+}
+
+#hue-rotate div,
+#hsl div {
+  width: 2px;
+  height: 100px;
+}
+```
+
+```js
+const hueRotate = document.getElementById("hue-rotate");
+const hsl = document.getElementById("hsl");
+
+for (let i = 0; i < 360; i++) {
+  const div1 = document.createElement("div");
+  div1.style.backgroundColor = `hsl(${i}, 100%, 50%)`;
+  hsl.appendChild(div1);
+
+  const div2 = document.createElement("div");
+  div2.style.backgroundColor = "red";
+  div2.style.filter = `hue-rotate(${i}deg)`;
+  hueRotate.appendChild(div2);
+}
+```
+
+{{EmbedLiveSample('hue-rotate_does_not_preserve_saturation_or_lightness','100%','350')}}
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/css/filter-function/saturate/index.md

@@ -9,6 +9,8 @@ browser-compat: css.types.filter-function.saturate
 
 The **`saturate()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Functions) super-saturates or desaturates the input image. Its result is a {{cssxref("<filter-function>")}}.
 
+> **Note:** `saturate()` is specified as a matrix operation on the RGB color. It does not actually convert the color to the HSL model, which is a non-linear operation. Therefore, it may not preserve the hue or lightness of the original color.
+
 {{EmbedInteractiveExample("pages/css/function-saturate.html")}}
 
 ## Syntax
@@ -33,6 +35,53 @@ saturate(100%)  /* No effect */
 saturate(200%)  /* Double saturation */
 ```
 
+### saturate() does not preserve hue or lightness
+
+The diagram below compares two color gradients with `hsl(0, 50%, 50%)` as the mid-point: the first is generated using `saturate()`, and the second uses actual HSL color values. Note how the `saturate()` gradient shows differences in hue and lightness towards the two ends.
+
+```html
+<div>
+  <p>Using <code>saturate()</code></p>
+  <div id="saturate"></div>
+</div>
+<div>
+  <p>Using <code>hsl()</code></p>
+  <div id="hsl"></div>
+</div>
+```
+
+```css hidden
+#saturate,
+#hsl {
+  display: flex;
+  margin: 1em 0;
+}
+
+#saturate div,
+#hsl div {
+  width: 2px;
+  height: 100px;
+}
+```
+
+```js
+const saturate = document.getElementById("saturate");
+const hsl = document.getElementById("hsl");
+
+for (let i = 0; i <= 200; i++) {
+  const div1 = document.createElement("div");
+  div1.style.backgroundColor = `hsl(0, ${i / 2}%, 50%)`;
+  hsl.appendChild(div1);
+
+  const div2 = document.createElement("div");
+  div2.style.backgroundColor = "hsl(0, 50%, 50%)";
+  div2.style.filter = `saturate(${i}%)`;
+  saturate.appendChild(div2);
+}
+```
+
+{{EmbedLiveSample('saturate_does_not_preserve_hue_or_lightness','100%','350')}}
+
 ## Specifications
 
 {{Specifications}}