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

1 files changed, 21 insertions, 1 deletions

diff --git a/docs/4.0/getting-started/theming.md b/docs/4.0/getting-started/theming.md
index bbf8081b52..57cbaa424a 100644
--- 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 %}