docs: add warning about code duplication in `breakpoint` and XY grid docs

diff --git a/docs/pages/xy-grid.md b/docs/pages/xy-grid.md
index 43dccbe28b38530b35f69116fb8188d12fc0905d..6251078bf1ce1ba26a04b82596b44da11e6123e9 100644 (file)
--- a/docs/pages/xy-grid.md
+++ b/docs/pages/xy-grid.md
@@ -449,6 +449,10 @@ We also have a shorthand option for the above which outputs the same CSS:
 }
 ```
 
+<div class="callout warning">
+  If you pass multiple breakpoints to the <code>breakpoint</code> mixin, it will duplicate its content for each of them. Be careful to only use <code>breakpoint</code> with properties that should change across breakpoints.
+</div>
+
 ### Custom Block Grid
 
 Use the `xy-grid-layout()` mixin to create your own block grid.

diff --git a/scss/util/_breakpoint.scss b/scss/util/_breakpoint.scss
index c519ca52f6f1cc4d99c5afc91dc87915e16d25d3..05cc9dd6b690841d8f4d7e3ba8e359e54dc856a8 100644 (file)
--- a/scss/util/_breakpoint.scss
+++ b/scss/util/_breakpoint.scss
@@ -137,6 +137,9 @@ $breakpoint-classes: (small medium large) !default;
 ///  - If an em value is passed, the value will be used as-is.
 ///
 /// If multiple values are passed, the mixin will generate a media query for each of them as described above.
+/// Since the content is duplicated for each breakpoint, this mixin should only be used with properties that
+/// change across breakpoints.
+///
 /// @param {Keyword|Number} $values... - Breakpoint name or px/rem/em value to process.
 ///
 /// @output If the breakpoint is "0px and larger", outputs the content as-is. Otherwise, outputs the content wrapped in a media query.