add examples to theming docs section on css vars in media queries, closes #26205

diff --git a/docs/4.0/getting-started/theming.md b/docs/4.0/getting-started/theming.md
index bbf8081b52bd50fd59ba1ace37fc3dff4fabce86..57cbaa424afe95f0c4ab2a1df394e45bdca66c0a 100644 (file)
--- a/docs/4.0/getting-started/theming.md
+++ b/docs/4.0/getting-started/theming.md
@@ -419,4 +419,24 @@ a {
 }
 {% endhighlight %}
 
-While we include breakpoints in our CSS variables, they unfortunately cannot be used in media queries. These remain in the compiled CSS for backward compatibility given they can be utilized by JavaScript. [Learn more in the spec.](https://www.w3.org/TR/css-variables-1/#using-variables)
+### Breakpoint variables
+
+While we originally included breakpoints in our CSS variables (e.g., `--breakpoint-md`), **these are not supported in media queries**, but they can still be used _within_ rulesets in media queries. These breakpoint variables remain in the compiled CSS for backward compatibility given they can be utilized by JavaScript. [Learn more in the spec.](https://www.w3.org/TR/css-variables-1/#using-variables)
+
+Here's an example of **what's not supported:**
+
+{% highlight css %}
+@media (min-width: var(--breakpoint-sm)) {
+  ...
+}
+{% endhighlight %}
+
+And here's an example of **what is supported:**
+
+{% highlight css %}
+@media (min-width: 768px) {
+  .custom-element {
+    color: var(--primary);
+  }
+}
+{% endhighlight %}