@telus-uds/components-base 3.19.0 → 3.20.0

package/CHANGELOG.md

@@ -1,9 +1,24 @@
 # Change Log - @telus-uds/components-base
 
-This log was last generated on Fri, 03 Oct 2025 20:34:06 GMT and should not be manually modified.
+This log was last generated on Fri, 10 Oct 2025 15:11:05 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 3.20.0
+
+Fri, 10 Oct 2025 15:11:05 GMT
+
+### Minor changes
+
+- `Spacer`: add RNMQ support (guillermo.peitzner@telus.com)
+- Bump @telus-uds/system-theme-tokens to v4.15.1
+
+### Patches
+
+- `ButtonDropdown`: Small size variant updates. (oscar.palencia@telus.com)
+- `MultiSelectfilter`: rowLimit prop issue causing display problems fixed (35577399+JoshHC@users.noreply.github.com)
+- `ExpandCollapseMini`: extra padding removed (35577399+JoshHC@users.noreply.github.com)
+
 ## 3.19.0
 
 Fri, 03 Oct 2025 20:34:06 GMT

package/lib/cjs/Button/ButtonDropdown.js

@@ -64,6 +64,7 @@ const selectDescriptionTextStyles = tokens => ({
     fontName: tokens?.descriptionFontName,
     fontSize: tokens?.descriptionFontSize,
     fontWeight: tokens?.descriptionFontWeight,
+    lineHeight: tokens?.descriptionLineHeight,
     fontColor: tokens?.color
   }),
   paddingBottom: tokens?.descriptionTextPaddingBottom

package/lib/cjs/ExpandCollapseMini/ExpandCollapseMiniControl.js

@@ -73,35 +73,21 @@ const ExpandCollapseMiniControl = /*#__PURE__*/_react.default.forwardRef((_ref,
     const isHovered = hover || linkHover;
     const iconBaselineOffset = 0;
     const hoverTranslateY = 4;
-
-    // Calculate baseline alignment to vertically center icon with text
-    // This combines font and icon metrics with adjustments for visual balance
-    const fontBaseline = fontSize / hoverTranslateY; // Quarter of font size - adjusts for text's visual center point
-    const iconBaseline = iconSize / hoverTranslateY; // Quarter of icon size - adjusts for icon's visual center point
-    const staticOffset = hoverTranslateY; // Fixed downward adjustment to fine-tune vertical alignment
-    const sizeCompensation = -Math.abs(iconSize - fontSize); // Compensates when icon and text sizes differ significantly
-
+    const fontBaseline = fontSize / hoverTranslateY;
+    const iconBaseline = iconSize / hoverTranslateY;
+    const staticOffset = hoverTranslateY;
+    const sizeCompensation = -Math.abs(iconSize - fontSize);
     const baselineAlignment = fontBaseline + iconBaseline - staticOffset + sizeCompensation;
-    if (_Platform.default.OS !== 'web') {
-      // For native platforms, use baseline alignment with optional offset
-      return {
-        iconTranslateY: baselineAlignment + iconBaselineOffset
-      };
-    }
+    const mobileAdjustment = _Platform.default.OS !== 'web' ? -2 : 0;
     if (isHovered) {
-      // Apply animation offset to the baseline-aligned position
-      // When expanded: move icon UP (1.3 the hover distance for clear movement)
-      // When collapsed: move icon DOWN (single hover distance)
       const hoverMovementDistance = 1.3;
       const animationOffset = expanded ? -(hoverTranslateY * hoverMovementDistance) : hoverTranslateY;
       return {
-        iconTranslateY: baselineAlignment + iconBaselineOffset + animationOffset
+        iconTranslateY: baselineAlignment + iconBaselineOffset + animationOffset + mobileAdjustment
       };
     }
-
-    // Default state uses baseline alignment with optional offset
     return {
-      iconTranslateY: baselineAlignment + iconBaselineOffset
+      iconTranslateY: baselineAlignment + iconBaselineOffset + mobileAdjustment
     };
   };
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Link.Link, {
@@ -112,6 +98,7 @@ const ExpandCollapseMiniControl = /*#__PURE__*/_react.default.forwardRef((_ref,
       ...linkTokens,
       ...getTokens(linkState),
       iconSize,
+      blockFontSize: fontSize,
       blockLineHeight: lineHeight
     }),
     ref: ref,

package/lib/cjs/Link/LinkBase.js

@@ -187,7 +187,8 @@ const LinkBase = /*#__PURE__*/_react.default.forwardRef((_ref6, ref) => {
       const themeTokens = resolveLinkTokens(linkState);
       const outerBorderStyles = selectOuterBorderStyles(themeTokens);
       const decorationStyles = selectDecorationStyles(themeTokens);
-      return [outerBorderStyles, staticStyles.outerBorderStyles, blockLeftStyle, decorationStyles, hasIcon && staticStyles.rowContainer];
+      const mobileCompensation = null;
+      return [outerBorderStyles, mobileCompensation, blockLeftStyle, decorationStyles, hasIcon && staticStyles.rowContainer];
     },
     children: linkState => {
       const themeTokens = resolveLinkTokens(linkState);
@@ -200,10 +201,12 @@ const LinkBase = /*#__PURE__*/_react.default.forwardRef((_ref6, ref) => {
       const {
         iconSpace
       } = themeTokens;
+      const isTextOnlyLink = !IconComponent && !icon && accessibilityRole === 'link';
+      const adjustedIconSpace = _Platform.default.OS !== 'web' && isTextOnlyLink ? 0 : iconSpace;
       return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Icon.IconText, {
         icon: IconComponent,
         iconPosition: iconPosition,
-        space: iconSpace,
+        space: adjustedIconSpace,
         iconProps: {
           ...iconProps,
           tokens: iconTokens,
@@ -270,15 +273,11 @@ const staticStyles = _StyleSheet.default.create({
       }
     })
   },
-  outerBorderStyles: {
+  outerBorderCompensation: {
     ...(_Platform.default.OS !== 'web' && {
-      margin: 0,
       marginHorizontal: 2,
-      padding: 0
-    }),
-    ...(_Platform.default.OS === 'android' && {
-      paddingHorizontal: 2,
-      paddingTop: 2
+      paddingHorizontal: _Platform.default.OS === 'android' ? 2 : 0,
+      paddingTop: _Platform.default.OS === 'android' ? 2 : 0
     })
   }
 });

package/lib/cjs/MultiSelectFilter/MultiSelectFilter.js

@@ -71,7 +71,6 @@ const selectContainerStyle = (windowHeight, windowWidth) => ({
   width: windowWidth
 });
 const TOTAL_COLUMNS = 12;
-const MAX_ITEMS_THRESHOLD = 12;
 const MultiSelectFilter = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
   let {
     label,
@@ -178,12 +177,13 @@ const MultiSelectFilter = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) =>
   });
   const colSizeNotMobile = items.length > rowLimit ? 2 : 1;
   const colSize = viewport !== 'xs' ? colSizeNotMobile : 1;
-  const itemsLengthNotMobile = items.length > 24 ? items.length / 2 : rowLimit;
-  const rowLength = viewport !== 'xs' ? itemsLengthNotMobile : items.length;
+  let rowLength = items.length;
+  if (viewport !== 'xs' && colSize === 2) {
+    rowLength = Math.ceil(items.length / 2);
+  }
   _react.default.useEffect(() => {
-    if (colSize === 1) return setMaxWidth(false);
-    return colSize === 2 && setMaxWidth(true);
-  }, [colSize]);
+    setMaxWidth(items.length >= rowLimit);
+  }, [items.length, rowLimit]);
   _react.default.useEffect(() => setCheckedIds(currentValues ?? []), [currentValues]);
   const uniqueFields = ['id', 'label'];
   if (!(0, _utils.containUniqueFields)(items, uniqueFields)) {
@@ -430,14 +430,14 @@ const MultiSelectFilter = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) =>
       dismissWhenPressedOutside: dismissWhenPressedOutside,
       onClose: onClose,
       overlaidPosition: overlaidPosition,
-      maxHeight: items.length > MAX_ITEMS_THRESHOLD ? true : maxHeight,
+      maxHeight: items.length >= rowLimit ? true : maxHeight,
       maxHeightSize: maxHeightSize,
       maxWidthSize: maxWidthSize,
       minHeight: minHeight,
       minWidth: minWidth,
       tokens: {
         ...tokens,
-        maxWidth: items.length > MAX_ITEMS_THRESHOLD ? true : maxWidth,
+        maxWidth: items.length >= rowLimit ? true : maxWidth,
         borderColor: containerBorderColor
       },
       copy: copy,

package/lib/cjs/Spacer/Spacer.js

@@ -6,9 +6,11 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _react = _interopRequireDefault(require("react"));
 var _propTypes = _interopRequireDefault(require("prop-types"));
-var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
 var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
 var _utils = require("../utils");
+var _useMediaQuerySpacing = _interopRequireDefault(require("../utils/useMediaQuerySpacing"));
+var _useTheme = _interopRequireDefault(require("../ThemeProvider/useTheme"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /**
@@ -65,13 +67,66 @@ const Spacer = /*#__PURE__*/_react.default.forwardRef((_ref, ref) => {
   let {
     space = 1,
     direction = 'column',
+    dataSet,
     ...rest
   } = _ref;
-  const size = (0, _utils.useSpacingScale)(space);
-  const sizeStyle = selectSizeStyle(size, direction);
+  const {
+    themeOptions: {
+      enableMediaQueryStyleSheet
+    }
+  } = (0, _useTheme.default)();
+  const {
+    sizeByViewport
+  } = (0, _useMediaQuerySpacing.default)(space);
+  const fallbackSize = (0, _utils.useSpacingScale)(space);
+  const sizeStyle = selectSizeStyle(fallbackSize, direction);
+  let spacerStyles;
+  let dataSetValue = dataSet;
+  if (enableMediaQueryStyleSheet) {
+    const sizeKey = direction === 'row' ? 'width' : 'height';
+    const stylesByViewport = {
+      xs: {
+        [sizeKey]: sizeByViewport.xs,
+        ...staticStyles.stretch
+      },
+      sm: {
+        [sizeKey]: sizeByViewport.sm,
+        ...staticStyles.stretch
+      },
+      md: {
+        [sizeKey]: sizeByViewport.md,
+        ...staticStyles.stretch
+      },
+      lg: {
+        [sizeKey]: sizeByViewport.lg,
+        ...staticStyles.stretch
+      },
+      xl: {
+        [sizeKey]: sizeByViewport.xl,
+        ...staticStyles.stretch
+      }
+    };
+    const mediaQueryStyles = (0, _utils.createMediaQueryStyles)(stylesByViewport);
+    const {
+      ids,
+      styles
+    } = _utils.StyleSheet.create({
+      spacer: {
+        ...mediaQueryStyles
+      }
+    });
+    spacerStyles = styles.spacer;
+    dataSetValue = {
+      media: ids.spacer,
+      ...dataSet
+    };
+  } else {
+    spacerStyles = [staticStyles.stretch, sizeStyle];
+  }
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
     ref: ref,
-    style: [staticStyles.stretch, sizeStyle],
+    style: spacerStyles,
+    dataSet: dataSetValue,
     ...selectProps(rest)
   });
 });
@@ -90,7 +145,12 @@ Spacer.propTypes = {
    * - `'column'` (default) applies space vertically; has a fixed height and not width.
    * - `'row'` applies space horizontally; has a fixed width and not height.
    */
-  direction: _propTypes.default.oneOf(['column', 'row'])
+  direction: _propTypes.default.oneOf(['column', 'row']),
+  /**
+   * Data attributes to be applied to the element. When media query stylesheet is enabled,
+   * this will include media query IDs for responsive styling.
+   */
+  dataSet: _propTypes.default.object
 };
 const staticStyles = _StyleSheet.default.create({
   stretch: {

package/lib/cjs/utils/index.js

@@ -8,6 +8,7 @@ var _exportNames = {
   useCopy: true,
   useHash: true,
   useSpacingScale: true,
+  useMediaQuerySpacing: true,
   useResponsiveProp: true,
   useOverlaidPosition: true,
   useSafeLayoutEffect: true,
@@ -90,6 +91,12 @@ Object.defineProperty(exports, "useHash", {
     return _useHash.default;
   }
 });
+Object.defineProperty(exports, "useMediaQuerySpacing", {
+  enumerable: true,
+  get: function () {
+    return _useMediaQuerySpacing.default;
+  }
+});
 Object.defineProperty(exports, "useOverlaidPosition", {
   enumerable: true,
   get: function () {
@@ -226,6 +233,7 @@ var _info = _interopRequireDefault(require("./info"));
 var _useCopy = _interopRequireDefault(require("./useCopy"));
 var _useHash = _interopRequireDefault(require("./useHash"));
 var _useSpacingScale = _interopRequireDefault(require("./useSpacingScale"));
+var _useMediaQuerySpacing = _interopRequireDefault(require("./useMediaQuerySpacing"));
 var _useResponsiveProp = _interopRequireWildcard(require("./useResponsiveProp"));
 Object.keys(_useResponsiveProp).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/lib/cjs/utils/useMediaQuerySpacing.js

@@ -0,0 +1,121 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ThemeProvider = require("../ThemeProvider");
+var _useResponsiveProp = require("./useResponsiveProp");
+/**
+ * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
+ * @typedef {import('./props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('./props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./props/spacingProps.js').SpacingObject} SpacingObject
+ */
+
+/**
+ * A utility hook that simplifies implementing media query-based responsive spacing.
+ *
+ * This hook handles the complexity of:
+ * - Detecting if a space value is responsive (has viewport keys)
+ * - Fetching theme tokens for each viewport
+ * - Resolving the correct space index for each viewport
+ * - Extracting actual pixel values from theme tokens
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * const { sizeByViewport } = useMediaQuerySpacing(space, 'spacingScale')
+ *
+ * // Use sizeByViewport to create media query styles
+ * const stylesByViewport = {
+ *   xs: { padding: sizeByViewport.xs },
+ *   sm: { padding: sizeByViewport.sm },
+ *   md: { padding: sizeByViewport.md },
+ *   lg: { padding: sizeByViewport.lg },
+ *   xl: { padding: sizeByViewport.xl }
+ * }
+ * const mediaQueryStyles = createMediaQueryStyles(stylesByViewport)
+ * ```
+ *
+ * ## Parameters
+ *
+ * @param {SpacingValue} spaceValue - A spacing value (number or responsive object with viewport keys)
+ * @param {string} tokenKey - The theme token key to use (e.g., 'spacingScale', 'Typography')
+ * @param {object} [tokens={}] - Additional tokens to pass to useThemeTokens
+ * @param {object} [variant={}] - Variant to pass to useThemeTokens
+ *
+ * ## Returns
+ *
+ * @returns {{
+ *   spaceIndexByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   sizeByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   tokensByViewport: { xs: object, sm: object, md: object, lg: object, xl: object }
+ * }}
+ *
+ * - `spaceIndexByViewport`: The resolved space index for each viewport
+ * - `sizeByViewport`: The actual pixel/number values for each viewport
+ * - `tokensByViewport`: The full theme tokens for each viewport (for advanced use cases)
+ */
+const useMediaQuerySpacing = function (spaceValue) {
+  let tokenKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'spacingScale';
+  let tokens = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  let variant = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+  const isResponsive = typeof spaceValue === 'object' && spaceValue !== null && !spaceValue.space && !spaceValue.options;
+  const getSpaceIndex = viewport => {
+    if (isResponsive) {
+      return (0, _useResponsiveProp.resolveResponsiveProp)(spaceValue, viewport);
+    }
+    if (typeof spaceValue === 'number') {
+      return spaceValue;
+    }
+    return spaceValue?.space ?? 1;
+  };
+  const spaceIndexByViewport = {
+    xs: getSpaceIndex('xs'),
+    sm: getSpaceIndex('sm'),
+    md: getSpaceIndex('md'),
+    lg: getSpaceIndex('lg'),
+    xl: getSpaceIndex('xl')
+  };
+  const tokensXs = (0, _ThemeProvider.useThemeTokens)(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xs,
+    viewport: 'xs'
+  });
+  const tokensSm = (0, _ThemeProvider.useThemeTokens)(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.sm,
+    viewport: 'sm'
+  });
+  const tokensMd = (0, _ThemeProvider.useThemeTokens)(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.md,
+    viewport: 'md'
+  });
+  const tokensLg = (0, _ThemeProvider.useThemeTokens)(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.lg,
+    viewport: 'lg'
+  });
+  const tokensXl = (0, _ThemeProvider.useThemeTokens)(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xl,
+    viewport: 'xl'
+  });
+  const sizeByViewport = {
+    xs: tokensXs.size ?? 0,
+    sm: tokensSm.size ?? 0,
+    md: tokensMd.size ?? 0,
+    lg: tokensLg.size ?? 0,
+    xl: tokensXl.size ?? 0
+  };
+  const tokensByViewport = {
+    xs: tokensXs,
+    sm: tokensSm,
+    md: tokensMd,
+    lg: tokensLg,
+    xl: tokensXl
+  };
+  return {
+    spaceIndexByViewport,
+    sizeByViewport,
+    tokensByViewport
+  };
+};
+var _default = exports.default = useMediaQuerySpacing;

package/lib/esm/Button/ButtonDropdown.js

@@ -55,6 +55,7 @@ const selectDescriptionTextStyles = tokens => ({
     fontName: tokens?.descriptionFontName,
     fontSize: tokens?.descriptionFontSize,
     fontWeight: tokens?.descriptionFontWeight,
+    lineHeight: tokens?.descriptionLineHeight,
     fontColor: tokens?.color
   }),
   paddingBottom: tokens?.descriptionTextPaddingBottom

package/lib/esm/ExpandCollapseMini/ExpandCollapseMiniControl.js

@@ -66,35 +66,21 @@ const ExpandCollapseMiniControl = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     const isHovered = hover || linkHover;
     const iconBaselineOffset = 0;
     const hoverTranslateY = 4;
-
-    // Calculate baseline alignment to vertically center icon with text
-    // This combines font and icon metrics with adjustments for visual balance
-    const fontBaseline = fontSize / hoverTranslateY; // Quarter of font size - adjusts for text's visual center point
-    const iconBaseline = iconSize / hoverTranslateY; // Quarter of icon size - adjusts for icon's visual center point
-    const staticOffset = hoverTranslateY; // Fixed downward adjustment to fine-tune vertical alignment
-    const sizeCompensation = -Math.abs(iconSize - fontSize); // Compensates when icon and text sizes differ significantly
-
+    const fontBaseline = fontSize / hoverTranslateY;
+    const iconBaseline = iconSize / hoverTranslateY;
+    const staticOffset = hoverTranslateY;
+    const sizeCompensation = -Math.abs(iconSize - fontSize);
     const baselineAlignment = fontBaseline + iconBaseline - staticOffset + sizeCompensation;
-    if (Platform.OS !== 'web') {
-      // For native platforms, use baseline alignment with optional offset
-      return {
-        iconTranslateY: baselineAlignment + iconBaselineOffset
-      };
-    }
+    const mobileAdjustment = Platform.OS !== 'web' ? -2 : 0;
     if (isHovered) {
-      // Apply animation offset to the baseline-aligned position
-      // When expanded: move icon UP (1.3 the hover distance for clear movement)
-      // When collapsed: move icon DOWN (single hover distance)
       const hoverMovementDistance = 1.3;
       const animationOffset = expanded ? -(hoverTranslateY * hoverMovementDistance) : hoverTranslateY;
       return {
-        iconTranslateY: baselineAlignment + iconBaselineOffset + animationOffset
+        iconTranslateY: baselineAlignment + iconBaselineOffset + animationOffset + mobileAdjustment
       };
     }
-
-    // Default state uses baseline alignment with optional offset
     return {
-      iconTranslateY: baselineAlignment + iconBaselineOffset
+      iconTranslateY: baselineAlignment + iconBaselineOffset + mobileAdjustment
     };
   };
   return /*#__PURE__*/_jsx(Link, {
@@ -105,6 +91,7 @@ const ExpandCollapseMiniControl = /*#__PURE__*/React.forwardRef((_ref, ref) => {
       ...linkTokens,
       ...getTokens(linkState),
       iconSize,
+      blockFontSize: fontSize,
       blockLineHeight: lineHeight
     }),
     ref: ref,

package/lib/esm/Link/LinkBase.js

@@ -180,7 +180,8 @@ const LinkBase = /*#__PURE__*/React.forwardRef((_ref6, ref) => {
       const themeTokens = resolveLinkTokens(linkState);
       const outerBorderStyles = selectOuterBorderStyles(themeTokens);
       const decorationStyles = selectDecorationStyles(themeTokens);
-      return [outerBorderStyles, staticStyles.outerBorderStyles, blockLeftStyle, decorationStyles, hasIcon && staticStyles.rowContainer];
+      const mobileCompensation = null;
+      return [outerBorderStyles, mobileCompensation, blockLeftStyle, decorationStyles, hasIcon && staticStyles.rowContainer];
     },
     children: linkState => {
       const themeTokens = resolveLinkTokens(linkState);
@@ -193,10 +194,12 @@ const LinkBase = /*#__PURE__*/React.forwardRef((_ref6, ref) => {
       const {
         iconSpace
       } = themeTokens;
+      const isTextOnlyLink = !IconComponent && !icon && accessibilityRole === 'link';
+      const adjustedIconSpace = Platform.OS !== 'web' && isTextOnlyLink ? 0 : iconSpace;
       return /*#__PURE__*/_jsx(IconText, {
         icon: IconComponent,
         iconPosition: iconPosition,
-        space: iconSpace,
+        space: adjustedIconSpace,
         iconProps: {
           ...iconProps,
           tokens: iconTokens,
@@ -263,15 +266,11 @@ const staticStyles = StyleSheet.create({
       }
     })
   },
-  outerBorderStyles: {
+  outerBorderCompensation: {
     ...(Platform.OS !== 'web' && {
-      margin: 0,
       marginHorizontal: 2,
-      padding: 0
-    }),
-    ...(Platform.OS === 'android' && {
-      paddingHorizontal: 2,
-      paddingTop: 2
+      paddingHorizontal: Platform.OS === 'android' ? 2 : 0,
+      paddingTop: Platform.OS === 'android' ? 2 : 0
     })
   }
 });

package/lib/esm/MultiSelectFilter/MultiSelectFilter.js

@@ -64,7 +64,6 @@ const selectContainerStyle = (windowHeight, windowWidth) => ({
   width: windowWidth
 });
 const TOTAL_COLUMNS = 12;
-const MAX_ITEMS_THRESHOLD = 12;
 const MultiSelectFilter = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
   let {
     label,
@@ -171,12 +170,13 @@ const MultiSelectFilter = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
   });
   const colSizeNotMobile = items.length > rowLimit ? 2 : 1;
   const colSize = viewport !== 'xs' ? colSizeNotMobile : 1;
-  const itemsLengthNotMobile = items.length > 24 ? items.length / 2 : rowLimit;
-  const rowLength = viewport !== 'xs' ? itemsLengthNotMobile : items.length;
+  let rowLength = items.length;
+  if (viewport !== 'xs' && colSize === 2) {
+    rowLength = Math.ceil(items.length / 2);
+  }
   React.useEffect(() => {
-    if (colSize === 1) return setMaxWidth(false);
-    return colSize === 2 && setMaxWidth(true);
-  }, [colSize]);
+    setMaxWidth(items.length >= rowLimit);
+  }, [items.length, rowLimit]);
   React.useEffect(() => setCheckedIds(currentValues ?? []), [currentValues]);
   const uniqueFields = ['id', 'label'];
   if (!containUniqueFields(items, uniqueFields)) {
@@ -423,14 +423,14 @@ const MultiSelectFilter = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
       dismissWhenPressedOutside: dismissWhenPressedOutside,
       onClose: onClose,
       overlaidPosition: overlaidPosition,
-      maxHeight: items.length > MAX_ITEMS_THRESHOLD ? true : maxHeight,
+      maxHeight: items.length >= rowLimit ? true : maxHeight,
       maxHeightSize: maxHeightSize,
       maxWidthSize: maxWidthSize,
       minHeight: minHeight,
       minWidth: minWidth,
       tokens: {
         ...tokens,
-        maxWidth: items.length > MAX_ITEMS_THRESHOLD ? true : maxWidth,
+        maxWidth: items.length >= rowLimit ? true : maxWidth,
         borderColor: containerBorderColor
       },
       copy: copy,

package/lib/esm/Spacer/Spacer.js

@@ -1,8 +1,10 @@
 import React from 'react';
 import PropTypes from 'prop-types';
-import StyleSheet from "react-native-web/dist/exports/StyleSheet";
 import View from "react-native-web/dist/exports/View";
-import { a11yProps, selectSystemProps, spacingProps, useSpacingScale, viewProps } from '../utils';
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import { a11yProps, selectSystemProps, spacingProps, useSpacingScale, viewProps, StyleSheet as StyleSheetUtils, createMediaQueryStyles } from '../utils';
+import useMediaQuerySpacing from '../utils/useMediaQuerySpacing';
+import useTheme from '../ThemeProvider/useTheme';
 
 /**
  * @typedef {import('../utils/props/spacingProps.js').SpacingValue} SpacingValue
@@ -60,13 +62,66 @@ const Spacer = /*#__PURE__*/React.forwardRef((_ref, ref) => {
   let {
     space = 1,
     direction = 'column',
+    dataSet,
     ...rest
   } = _ref;
-  const size = useSpacingScale(space);
-  const sizeStyle = selectSizeStyle(size, direction);
+  const {
+    themeOptions: {
+      enableMediaQueryStyleSheet
+    }
+  } = useTheme();
+  const {
+    sizeByViewport
+  } = useMediaQuerySpacing(space);
+  const fallbackSize = useSpacingScale(space);
+  const sizeStyle = selectSizeStyle(fallbackSize, direction);
+  let spacerStyles;
+  let dataSetValue = dataSet;
+  if (enableMediaQueryStyleSheet) {
+    const sizeKey = direction === 'row' ? 'width' : 'height';
+    const stylesByViewport = {
+      xs: {
+        [sizeKey]: sizeByViewport.xs,
+        ...staticStyles.stretch
+      },
+      sm: {
+        [sizeKey]: sizeByViewport.sm,
+        ...staticStyles.stretch
+      },
+      md: {
+        [sizeKey]: sizeByViewport.md,
+        ...staticStyles.stretch
+      },
+      lg: {
+        [sizeKey]: sizeByViewport.lg,
+        ...staticStyles.stretch
+      },
+      xl: {
+        [sizeKey]: sizeByViewport.xl,
+        ...staticStyles.stretch
+      }
+    };
+    const mediaQueryStyles = createMediaQueryStyles(stylesByViewport);
+    const {
+      ids,
+      styles
+    } = StyleSheetUtils.create({
+      spacer: {
+        ...mediaQueryStyles
+      }
+    });
+    spacerStyles = styles.spacer;
+    dataSetValue = {
+      media: ids.spacer,
+      ...dataSet
+    };
+  } else {
+    spacerStyles = [staticStyles.stretch, sizeStyle];
+  }
   return /*#__PURE__*/_jsx(View, {
     ref: ref,
-    style: [staticStyles.stretch, sizeStyle],
+    style: spacerStyles,
+    dataSet: dataSetValue,
     ...selectProps(rest)
   });
 });
@@ -85,7 +140,12 @@ Spacer.propTypes = {
    * - `'column'` (default) applies space vertically; has a fixed height and not width.
    * - `'row'` applies space horizontally; has a fixed width and not height.
    */
-  direction: PropTypes.oneOf(['column', 'row'])
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * Data attributes to be applied to the element. When media query stylesheet is enabled,
+   * this will include media query IDs for responsive styling.
+   */
+  dataSet: PropTypes.object
 };
 const staticStyles = StyleSheet.create({
   stretch: {

package/lib/esm/utils/index.js

@@ -9,6 +9,7 @@ export { default as info } from './info';
 export { default as useCopy } from './useCopy';
 export { default as useHash } from './useHash';
 export { default as useSpacingScale } from './useSpacingScale';
+export { default as useMediaQuerySpacing } from './useMediaQuerySpacing';
 export { default as useResponsiveProp } from './useResponsiveProp';
 export { default as useOverlaidPosition } from './useOverlaidPosition';
 export { default as useSafeLayoutEffect } from './useSafeLayoutEffect';

package/lib/esm/utils/useMediaQuerySpacing.js

@@ -0,0 +1,116 @@
+import { useThemeTokens } from '../ThemeProvider';
+import { resolveResponsiveProp } from './useResponsiveProp';
+
+/**
+ * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
+ * @typedef {import('./props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('./props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./props/spacingProps.js').SpacingObject} SpacingObject
+ */
+
+/**
+ * A utility hook that simplifies implementing media query-based responsive spacing.
+ *
+ * This hook handles the complexity of:
+ * - Detecting if a space value is responsive (has viewport keys)
+ * - Fetching theme tokens for each viewport
+ * - Resolving the correct space index for each viewport
+ * - Extracting actual pixel values from theme tokens
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * const { sizeByViewport } = useMediaQuerySpacing(space, 'spacingScale')
+ *
+ * // Use sizeByViewport to create media query styles
+ * const stylesByViewport = {
+ *   xs: { padding: sizeByViewport.xs },
+ *   sm: { padding: sizeByViewport.sm },
+ *   md: { padding: sizeByViewport.md },
+ *   lg: { padding: sizeByViewport.lg },
+ *   xl: { padding: sizeByViewport.xl }
+ * }
+ * const mediaQueryStyles = createMediaQueryStyles(stylesByViewport)
+ * ```
+ *
+ * ## Parameters
+ *
+ * @param {SpacingValue} spaceValue - A spacing value (number or responsive object with viewport keys)
+ * @param {string} tokenKey - The theme token key to use (e.g., 'spacingScale', 'Typography')
+ * @param {object} [tokens={}] - Additional tokens to pass to useThemeTokens
+ * @param {object} [variant={}] - Variant to pass to useThemeTokens
+ *
+ * ## Returns
+ *
+ * @returns {{
+ *   spaceIndexByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   sizeByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   tokensByViewport: { xs: object, sm: object, md: object, lg: object, xl: object }
+ * }}
+ *
+ * - `spaceIndexByViewport`: The resolved space index for each viewport
+ * - `sizeByViewport`: The actual pixel/number values for each viewport
+ * - `tokensByViewport`: The full theme tokens for each viewport (for advanced use cases)
+ */
+const useMediaQuerySpacing = function (spaceValue) {
+  let tokenKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'spacingScale';
+  let tokens = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  let variant = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+  const isResponsive = typeof spaceValue === 'object' && spaceValue !== null && !spaceValue.space && !spaceValue.options;
+  const getSpaceIndex = viewport => {
+    if (isResponsive) {
+      return resolveResponsiveProp(spaceValue, viewport);
+    }
+    if (typeof spaceValue === 'number') {
+      return spaceValue;
+    }
+    return spaceValue?.space ?? 1;
+  };
+  const spaceIndexByViewport = {
+    xs: getSpaceIndex('xs'),
+    sm: getSpaceIndex('sm'),
+    md: getSpaceIndex('md'),
+    lg: getSpaceIndex('lg'),
+    xl: getSpaceIndex('xl')
+  };
+  const tokensXs = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xs,
+    viewport: 'xs'
+  });
+  const tokensSm = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.sm,
+    viewport: 'sm'
+  });
+  const tokensMd = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.md,
+    viewport: 'md'
+  });
+  const tokensLg = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.lg,
+    viewport: 'lg'
+  });
+  const tokensXl = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xl,
+    viewport: 'xl'
+  });
+  const sizeByViewport = {
+    xs: tokensXs.size ?? 0,
+    sm: tokensSm.size ?? 0,
+    md: tokensMd.size ?? 0,
+    lg: tokensLg.size ?? 0,
+    xl: tokensXl.size ?? 0
+  };
+  const tokensByViewport = {
+    xs: tokensXs,
+    sm: tokensSm,
+    md: tokensMd,
+    lg: tokensLg,
+    xl: tokensXl
+  };
+  return {
+    spaceIndexByViewport,
+    sizeByViewport,
+    tokensByViewport
+  };
+};
+export default useMediaQuerySpacing;

package/lib/package.json

@@ -12,7 +12,7 @@
     "@gorhom/portal": "^1.0.14",
     "@react-native-picker/picker": "^2.9.0",
     "@telus-uds/system-constants": "^3.0.0",
-    "@telus-uds/system-theme-tokens": "^4.15.0",
+    "@telus-uds/system-theme-tokens": "^4.15.1",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -84,6 +84,6 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "3.19.0",
+  "version": "3.20.0",
   "types": "types/index.d.ts"
 }

package/package.json

@@ -12,7 +12,7 @@
     "@gorhom/portal": "^1.0.14",
     "@react-native-picker/picker": "^2.9.0",
     "@telus-uds/system-constants": "^3.0.0",
-    "@telus-uds/system-theme-tokens": "^4.15.0",
+    "@telus-uds/system-theme-tokens": "^4.15.1",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -84,6 +84,6 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "3.19.0",
+  "version": "3.20.0",
   "types": "types/index.d.ts"
 }

package/src/Button/ButtonDropdown.jsx

@@ -56,6 +56,7 @@ const selectDescriptionTextStyles = (tokens) => ({
     fontName: tokens?.descriptionFontName,
     fontSize: tokens?.descriptionFontSize,
     fontWeight: tokens?.descriptionFontWeight,
+    lineHeight: tokens?.descriptionLineHeight,
     fontColor: tokens?.color
   }),
   paddingBottom: tokens?.descriptionTextPaddingBottom

package/src/ExpandCollapseMini/ExpandCollapseMiniControl.jsx

@@ -62,36 +62,28 @@ const ExpandCollapseMiniControl = React.forwardRef(
       const iconBaselineOffset = 0
       const hoverTranslateY = 4
 
-      // Calculate baseline alignment to vertically center icon with text
-      // This combines font and icon metrics with adjustments for visual balance
-      const fontBaseline = fontSize / hoverTranslateY // Quarter of font size - adjusts for text's visual center point
-      const iconBaseline = iconSize / hoverTranslateY // Quarter of icon size - adjusts for icon's visual center point
-      const staticOffset = hoverTranslateY // Fixed downward adjustment to fine-tune vertical alignment
-      const sizeCompensation = -Math.abs(iconSize - fontSize) // Compensates when icon and text sizes differ significantly
+      const fontBaseline = fontSize / hoverTranslateY
+      const iconBaseline = iconSize / hoverTranslateY
+      const staticOffset = hoverTranslateY
+      const sizeCompensation = -Math.abs(iconSize - fontSize)
 
       const baselineAlignment = fontBaseline + iconBaseline - staticOffset + sizeCompensation
 
-      if (Platform.OS !== 'web') {
-        // For native platforms, use baseline alignment with optional offset
-        return { iconTranslateY: baselineAlignment + iconBaselineOffset }
-      }
+      const mobileAdjustment = Platform.OS !== 'web' ? -2 : 0
 
       if (isHovered) {
-        // Apply animation offset to the baseline-aligned position
-        // When expanded: move icon UP (1.3 the hover distance for clear movement)
-        // When collapsed: move icon DOWN (single hover distance)
         const hoverMovementDistance = 1.3
         const animationOffset = expanded
           ? -(hoverTranslateY * hoverMovementDistance)
           : hoverTranslateY
 
         return {
-          iconTranslateY: baselineAlignment + iconBaselineOffset + animationOffset
+          iconTranslateY:
+            baselineAlignment + iconBaselineOffset + animationOffset + mobileAdjustment
         }
       }
 
-      // Default state uses baseline alignment with optional offset
-      return { iconTranslateY: baselineAlignment + iconBaselineOffset }
+      return { iconTranslateY: baselineAlignment + iconBaselineOffset + mobileAdjustment }
     }
 
     return (
@@ -103,6 +95,7 @@ const ExpandCollapseMiniControl = React.forwardRef(
           ...linkTokens,
           ...getTokens(linkState),
           iconSize,
+          blockFontSize: fontSize,
           blockLineHeight: lineHeight
         })}
         ref={ref}

package/src/Link/LinkBase.jsx

@@ -171,9 +171,12 @@ const LinkBase = React.forwardRef(
           const themeTokens = resolveLinkTokens(linkState)
           const outerBorderStyles = selectOuterBorderStyles(themeTokens)
           const decorationStyles = selectDecorationStyles(themeTokens)
+
+          const mobileCompensation = null
+
           return [
             outerBorderStyles,
-            staticStyles.outerBorderStyles,
+            mobileCompensation,
             blockLeftStyle,
             decorationStyles,
             hasIcon && staticStyles.rowContainer
@@ -191,11 +194,14 @@ const LinkBase = React.forwardRef(
           const IconComponent = icon || themeTokens.icon
           const { iconSpace } = themeTokens
 
+          const isTextOnlyLink = !IconComponent && !icon && accessibilityRole === 'link'
+          const adjustedIconSpace = Platform.OS !== 'web' && isTextOnlyLink ? 0 : iconSpace
+
           return (
             <IconText
               icon={IconComponent}
               iconPosition={iconPosition}
-              space={iconSpace}
+              space={adjustedIconSpace}
               iconProps={{
                 ...iconProps,
                 tokens: iconTokens,
@@ -274,15 +280,11 @@ const staticStyles = StyleSheet.create({
       }
     })
   },
-  outerBorderStyles: {
+  outerBorderCompensation: {
     ...(Platform.OS !== 'web' && {
-      margin: 0,
       marginHorizontal: 2,
-      padding: 0
-    }),
-    ...(Platform.OS === 'android' && {
-      paddingHorizontal: 2,
-      paddingTop: 2
+      paddingHorizontal: Platform.OS === 'android' ? 2 : 0,
+      paddingTop: Platform.OS === 'android' ? 2 : 0
     })
   }
 })

package/src/MultiSelectFilter/MultiSelectFilter.jsx

@@ -65,7 +65,6 @@ const selectContainerStyle = (windowHeight, windowWidth) => ({
 })
 
 const TOTAL_COLUMNS = 12
-const MAX_ITEMS_THRESHOLD = 12
 
 const MultiSelectFilter = React.forwardRef(
   (
@@ -174,13 +173,15 @@ const MultiSelectFilter = React.forwardRef(
     const getCopy = useCopy({ dictionary, copy })
     const colSizeNotMobile = items.length > rowLimit ? 2 : 1
     const colSize = viewport !== 'xs' ? colSizeNotMobile : 1
-    const itemsLengthNotMobile = items.length > 24 ? items.length / 2 : rowLimit
-    const rowLength = viewport !== 'xs' ? itemsLengthNotMobile : items.length
+
+    let rowLength = items.length
+    if (viewport !== 'xs' && colSize === 2) {
+      rowLength = Math.ceil(items.length / 2)
+    }
 
     React.useEffect(() => {
-      if (colSize === 1) return setMaxWidth(false)
-      return colSize === 2 && setMaxWidth(true)
-    }, [colSize])
+      setMaxWidth(items.length >= rowLimit)
+    }, [items.length, rowLimit])
 
     React.useEffect(() => setCheckedIds(currentValues ?? []), [currentValues])
 
@@ -414,14 +415,14 @@ const MultiSelectFilter = React.forwardRef(
             dismissWhenPressedOutside={dismissWhenPressedOutside}
             onClose={onClose}
             overlaidPosition={overlaidPosition}
-            maxHeight={items.length > MAX_ITEMS_THRESHOLD ? true : maxHeight}
+            maxHeight={items.length >= rowLimit ? true : maxHeight}
             maxHeightSize={maxHeightSize}
             maxWidthSize={maxWidthSize}
             minHeight={minHeight}
             minWidth={minWidth}
             tokens={{
               ...tokens,
-              maxWidth: items.length > MAX_ITEMS_THRESHOLD ? true : maxWidth,
+              maxWidth: items.length >= rowLimit ? true : maxWidth,
               borderColor: containerBorderColor
             }}
             copy={copy}

package/src/Spacer/Spacer.jsx

@@ -1,7 +1,17 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { StyleSheet, View } from 'react-native'
-import { a11yProps, selectSystemProps, spacingProps, useSpacingScale, viewProps } from '../utils'
+import { View, StyleSheet } from 'react-native'
+import {
+  a11yProps,
+  selectSystemProps,
+  spacingProps,
+  useSpacingScale,
+  viewProps,
+  StyleSheet as StyleSheetUtils,
+  createMediaQueryStyles
+} from '../utils'
+import useMediaQuerySpacing from '../utils/useMediaQuerySpacing'
+import useTheme from '../ThemeProvider/useTheme'
 
 /**
  * @typedef {import('../utils/props/spacingProps.js').SpacingValue} SpacingValue
@@ -56,11 +66,43 @@ const selectSizeStyle = (size, direction) => ({
  * Spacer has no content and is ignored by tools such as screen readers. Use `Divider` for
  * separations between elements that may be treated as semantically meaningful on web.
  */
-const Spacer = React.forwardRef(({ space = 1, direction = 'column', ...rest }, ref) => {
-  const size = useSpacingScale(space)
-  const sizeStyle = selectSizeStyle(size, direction)
+const Spacer = React.forwardRef(({ space = 1, direction = 'column', dataSet, ...rest }, ref) => {
+  const {
+    themeOptions: { enableMediaQueryStyleSheet }
+  } = useTheme()
 
-  return <View ref={ref} style={[staticStyles.stretch, sizeStyle]} {...selectProps(rest)} />
+  const { sizeByViewport } = useMediaQuerySpacing(space)
+
+  const fallbackSize = useSpacingScale(space)
+  const sizeStyle = selectSizeStyle(fallbackSize, direction)
+
+  let spacerStyles
+  let dataSetValue = dataSet
+
+  if (enableMediaQueryStyleSheet) {
+    const sizeKey = direction === 'row' ? 'width' : 'height'
+    const stylesByViewport = {
+      xs: { [sizeKey]: sizeByViewport.xs, ...staticStyles.stretch },
+      sm: { [sizeKey]: sizeByViewport.sm, ...staticStyles.stretch },
+      md: { [sizeKey]: sizeByViewport.md, ...staticStyles.stretch },
+      lg: { [sizeKey]: sizeByViewport.lg, ...staticStyles.stretch },
+      xl: { [sizeKey]: sizeByViewport.xl, ...staticStyles.stretch }
+    }
+    const mediaQueryStyles = createMediaQueryStyles(stylesByViewport)
+
+    const { ids, styles } = StyleSheetUtils.create({
+      spacer: {
+        ...mediaQueryStyles
+      }
+    })
+
+    spacerStyles = styles.spacer
+    dataSetValue = { media: ids.spacer, ...dataSet }
+  } else {
+    spacerStyles = [staticStyles.stretch, sizeStyle]
+  }
+
+  return <View ref={ref} style={spacerStyles} dataSet={dataSetValue} {...selectProps(rest)} />
 })
 Spacer.displayName = 'Spacer'
 
@@ -78,7 +120,12 @@ Spacer.propTypes = {
    * - `'column'` (default) applies space vertically; has a fixed height and not width.
    * - `'row'` applies space horizontally; has a fixed width and not height.
    */
-  direction: PropTypes.oneOf(['column', 'row'])
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * Data attributes to be applied to the element. When media query stylesheet is enabled,
+   * this will include media query IDs for responsive styling.
+   */
+  dataSet: PropTypes.object
 }
 
 const staticStyles = StyleSheet.create({

package/src/utils/index.js

@@ -9,6 +9,7 @@ export { default as info } from './info'
 export { default as useCopy } from './useCopy'
 export { default as useHash } from './useHash'
 export { default as useSpacingScale } from './useSpacingScale'
+export { default as useMediaQuerySpacing } from './useMediaQuerySpacing'
 export { default as useResponsiveProp } from './useResponsiveProp'
 export { default as useOverlaidPosition } from './useOverlaidPosition'
 export { default as useSafeLayoutEffect } from './useSafeLayoutEffect'

package/src/utils/useMediaQuerySpacing.js

@@ -0,0 +1,124 @@
+import { useThemeTokens } from '../ThemeProvider'
+import { resolveResponsiveProp } from './useResponsiveProp'
+
+/**
+ * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
+ * @typedef {import('./props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('./props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./props/spacingProps.js').SpacingObject} SpacingObject
+ */
+
+/**
+ * A utility hook that simplifies implementing media query-based responsive spacing.
+ *
+ * This hook handles the complexity of:
+ * - Detecting if a space value is responsive (has viewport keys)
+ * - Fetching theme tokens for each viewport
+ * - Resolving the correct space index for each viewport
+ * - Extracting actual pixel values from theme tokens
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * const { sizeByViewport } = useMediaQuerySpacing(space, 'spacingScale')
+ *
+ * // Use sizeByViewport to create media query styles
+ * const stylesByViewport = {
+ *   xs: { padding: sizeByViewport.xs },
+ *   sm: { padding: sizeByViewport.sm },
+ *   md: { padding: sizeByViewport.md },
+ *   lg: { padding: sizeByViewport.lg },
+ *   xl: { padding: sizeByViewport.xl }
+ * }
+ * const mediaQueryStyles = createMediaQueryStyles(stylesByViewport)
+ * ```
+ *
+ * ## Parameters
+ *
+ * @param {SpacingValue} spaceValue - A spacing value (number or responsive object with viewport keys)
+ * @param {string} tokenKey - The theme token key to use (e.g., 'spacingScale', 'Typography')
+ * @param {object} [tokens={}] - Additional tokens to pass to useThemeTokens
+ * @param {object} [variant={}] - Variant to pass to useThemeTokens
+ *
+ * ## Returns
+ *
+ * @returns {{
+ *   spaceIndexByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   sizeByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   tokensByViewport: { xs: object, sm: object, md: object, lg: object, xl: object }
+ * }}
+ *
+ * - `spaceIndexByViewport`: The resolved space index for each viewport
+ * - `sizeByViewport`: The actual pixel/number values for each viewport
+ * - `tokensByViewport`: The full theme tokens for each viewport (for advanced use cases)
+ */
+const useMediaQuerySpacing = (spaceValue, tokenKey = 'spacingScale', tokens = {}, variant = {}) => {
+  const isResponsive =
+    typeof spaceValue === 'object' &&
+    spaceValue !== null &&
+    !spaceValue.space &&
+    !spaceValue.options
+
+  const getSpaceIndex = (viewport) => {
+    if (isResponsive) {
+      return resolveResponsiveProp(spaceValue, viewport)
+    }
+    if (typeof spaceValue === 'number') {
+      return spaceValue
+    }
+    return spaceValue?.space ?? 1
+  }
+
+  const spaceIndexByViewport = {
+    xs: getSpaceIndex('xs'),
+    sm: getSpaceIndex('sm'),
+    md: getSpaceIndex('md'),
+    lg: getSpaceIndex('lg'),
+    xl: getSpaceIndex('xl')
+  }
+
+  const tokensXs = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xs,
+    viewport: 'xs'
+  })
+  const tokensSm = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.sm,
+    viewport: 'sm'
+  })
+  const tokensMd = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.md,
+    viewport: 'md'
+  })
+  const tokensLg = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.lg,
+    viewport: 'lg'
+  })
+  const tokensXl = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xl,
+    viewport: 'xl'
+  })
+
+  const sizeByViewport = {
+    xs: tokensXs.size ?? 0,
+    sm: tokensSm.size ?? 0,
+    md: tokensMd.size ?? 0,
+    lg: tokensLg.size ?? 0,
+    xl: tokensXl.size ?? 0
+  }
+
+  const tokensByViewport = {
+    xs: tokensXs,
+    sm: tokensSm,
+    md: tokensMd,
+    lg: tokensLg,
+    xl: tokensXl
+  }
+
+  return {
+    spaceIndexByViewport,
+    sizeByViewport,
+    tokensByViewport
+  }
+}
+
+export default useMediaQuerySpacing