@skyscanner/backpack-web 41.7.0-beta-layout → 41.7.0-beta-v2

package/bpk-component-layout/src/theme.js

@@ -0,0 +1,229 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { defineConfig } from '@chakra-ui/react';
+// Import tokens from Backpack foundations
+// Note: Some tokens may not be in TypeScript definitions but exist at runtime
+
+const bpkTokens = require('@skyscanner/bpk-foundations-web/tokens/base.es6');
+
+// NOTE:
+// We intentionally do not use the raw breakpoint *values* from foundations here.
+// Foundations exports breakpoint values such as `breakpointMobile = "32rem"` which
+// are used primarily for max-width queries (e.g. `(max-width: 32rem)`).
+//
+// Backpack layout responsive values in this package are mobile-first and behave
+// like Chakra breakpoints (min-width thresholds). To align with Backpack’s
+// intended breakpoint ranges we define lower-bound (min-width) thresholds:
+//
+// - small-mobile: 320px+
+// - mobile: 360px+
+// - small-tablet: 513px+
+// - tablet: 769px+
+// - desktop: 1025px+
+
+// Note: Spacing tokens are defined as SCSS functions in Backpack foundations,
+// not as direct values. We need to use the actual rem values from the SCSS functions.
+// Based on @skyscanner/bpk-foundations-web/tokens/base.default.scss:
+// - bpk-spacing-sm() returns .25rem
+// - bpk-spacing-md() returns .5rem
+// - bpk-spacing-lg() returns 1.5rem
+// - bpk-spacing-xl() returns 2rem (needs verification)
+// - bpk-spacing-xxl() returns 2.5rem
+// - bpk-spacing-base() returns 1rem (standard base spacing)
+// TODO: CLOV-1021 - will add spacing tokens to Backpack Foundations package and use them here after we ship the PoC
+const spacingXs = '.125rem'; // 2px
+const spacingSm = '.25rem';
+const spacingBase = '1rem'; // Standard base spacing
+const spacingMd = '.5rem';
+const spacingLg = '1.5rem';
+const spacingXl = '2rem';
+const spacingXxl = '2.5rem';
+
+/**
+ * Backpack Theme Configuration for Chakra UI
+ *
+ * This theme maps Backpack design tokens from @skyscanner/bpk-foundations-web
+ * to Chakra UI's theme structure.
+ */
+
+/**
+ * Maps Backpack spacing tokens to actual rem values.
+ * These come directly from @skyscanner/bpk-foundations-web.
+ */
+// Spacing tokens - directly imported from foundations
+const spacingMap = {
+  'bpk-spacing-none': {
+    value: '0'
+  },
+  // Temporary: Foundations does not yet export a 2px spacing token. This will be
+  // replaced with a foundations value once available.
+  'bpk-spacing-xs': {
+    value: spacingXs
+  },
+  'bpk-spacing-sm': {
+    value: spacingSm
+  },
+  'bpk-spacing-base': {
+    value: spacingBase
+  },
+  'bpk-spacing-md': {
+    value: spacingMd
+  },
+  'bpk-spacing-lg': {
+    value: spacingLg
+  },
+  'bpk-spacing-xl': {
+    value: spacingXl
+  },
+  'bpk-spacing-xxl': {
+    value: spacingXxl
+  }
+};
+
+/**
+ * Maps Backpack border size tokens to actual border width values
+ * These come directly from @skyscanner/bpk-foundations-web
+ */
+const borderSizeMap = {
+  'bpk-border-size-sm': bpkTokens.borderSizeSm,
+  'bpk-border-size-lg': bpkTokens.borderSizeLg,
+  'bpk-border-size-xl': bpkTokens.borderSizeXl
+};
+
+/**
+ * Maps Backpack border radius tokens to actual radius values.
+ * These come directly from @skyscanner/bpk-foundations-web.
+ */
+const borderRadiusMap = {
+  'bpk-border-radius-none': '0',
+  'bpk-border-radius-xs': bpkTokens.borderRadiusXs,
+  'bpk-border-radius-sm': bpkTokens.borderRadiusSm,
+  'bpk-border-radius-md': bpkTokens.borderRadiusMd,
+  'bpk-border-radius-lg': bpkTokens.borderRadiusLg,
+  'bpk-border-radius-xl': bpkTokens.borderRadiusXl,
+  'bpk-border-radius-full': bpkTokens.borderRadiusFull
+};
+
+/**
+ * Maps Backpack shadow tokens to actual box-shadow values
+ * These come directly from @skyscanner/bpk-foundations-web
+ */
+const shadowMap = {
+  'bpk-shadow-sm': bpkTokens.boxShadowSm,
+  'bpk-shadow-lg': bpkTokens.boxShadowLg,
+  'bpk-shadow-xl': bpkTokens.boxShadowXl
+};
+
+/**
+ * Chakra expects raw width values (e.g. "48rem"), not full media queries.
+ * The media query construction is handled internally by Chakra's system.
+ *
+ * We align Backpack breakpoint tokens to Chakra's keys like this:
+ * - base: 0 (implicit)
+ * - sm: small-mobile (>= 320px)
+ * - md: mobile (>= 360px)
+ * - lg: small-tablet (>= 513px)
+ * - xl: tablet (>= 769px)
+ * - 2xl: desktop (>= 1025px)
+ */
+// TODO: CLOV-1021 - will add breakpoint boundary tokens to Backpack Foundations package and use them here after we ship the PoC
+const breakpointMap = {
+  base: '0rem',
+  sm: '20rem',
+  // 320px
+  md: '22.5rem',
+  // 360px
+  lg: '32.0625rem',
+  // 513px
+  xl: '48.0625rem',
+  // 769px
+  '2xl': '64.0625rem' // 1025px
+};
+
+/**
+ * Exports spacing map for use in tokenUtils
+ * This allows tokenUtils to look up actual spacing values
+ *
+ * @returns {Record<string, string>} A map of spacing token names to values.
+ */
+export function getSpacingMap() {
+  // Return simple string values for backward compatibility with utilities
+  const simpleMap = {};
+  Object.entries(spacingMap).forEach(([key, obj]) => {
+    simpleMap[key] = obj.value;
+  });
+  return simpleMap;
+}
+
+/**
+ * Gets the actual spacing value for a Backpack spacing token
+ *
+ * @param {string} token - Backpack spacing token name.
+ * @returns {string | undefined} The actual spacing value.
+ */
+export function getSpacingValue(token) {
+  return spacingMap[token]?.value;
+}
+
+/**
+ * Gets the actual border width value for a Backpack border size token
+ *
+ * @param {string} token - Backpack border size token name.
+ * @returns {string | undefined} The actual border width value.
+ */
+export function getBorderSizeValue(token) {
+  return borderSizeMap[token];
+}
+
+/**
+ * Gets the actual border radius value for a Backpack border radius token
+ *
+ * @param {string} token - Backpack border radius token name.
+ * @returns {string | undefined} The actual border radius value.
+ */
+export function getBorderRadiusValue(token) {
+  return borderRadiusMap[token];
+}
+
+/**
+ * Gets the actual box-shadow value for a Backpack shadow token
+ *
+ * @param {string} token - Backpack shadow token name.
+ * @returns {string | undefined} The actual box-shadow value.
+ */
+export function getShadowValue(token) {
+  return shadowMap[token];
+}
+export function createBpkConfig() {
+  // Convert breakpoint map to Chakra UI format
+  // Breakpoints in Chakra v3 are typically simple strings in the breakpoints object
+  const chakraBreakpoints = {};
+  Object.entries(breakpointMap).forEach(([token, value]) => {
+    chakraBreakpoints[token] = value;
+  });
+  return defineConfig({
+    cssVarsPrefix: 'bpk',
+    theme: {
+      tokens: {
+        spacing: spacingMap
+      },
+      breakpoints: chakraBreakpoints
+    }
+  });
+}

package/bpk-component-layout/src/tokenUtils.d.ts

@@ -0,0 +1,108 @@
+export type BpkLayoutComponentName = 'BpkBox' | 'BpkFlex' | 'BpkGrid' | 'BpkStack';
+/**
+ * Allowlisted, component-scoped prop groups that are eligible for Backpack responsive value
+ * processing (Backpack breakpoint keys -> Chakra breakpoint keys).
+ *
+ * NOTE:
+ * - Spacing/size/position props are processed separately via `processBpkProps` and therefore
+ *   are intentionally NOT included here.
+ * - These groups are meant to keep the responsive surface predictable per component, while
+ *   avoiding duplicated per-component breakpoint mapping logic.
+ */
+type BpkResponsivePropGroups = {
+    /**
+     * Container-level layout props (how children are laid out).
+     */
+    container: readonly string[];
+    /**
+     * Item-level layout props (how this element participates in a parent layout).
+     */
+    item?: readonly string[];
+};
+export declare const BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT: Record<BpkLayoutComponentName, BpkResponsivePropGroups>;
+export declare const BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT: Record<BpkLayoutComponentName, readonly string[]>;
+export type ProcessBpkComponentPropsOptions = {
+    component: BpkLayoutComponentName;
+    /**
+     * Optional map of responsive props. When provided, it will be filtered to the
+     * allowlist for the given component, then breakpoint-normalised.
+     *
+     * This is useful for components like `BpkFlex` and `BpkGrid` that expose a
+     * public API with different prop names.
+     */
+    responsiveProps?: Record<string, any>;
+    /**
+     * Optional mapping of source prop name -> target prop name.
+     * Primarily kept for parity with `processResponsiveProps`.
+     */
+    propNameMap?: Record<string, string>;
+};
+/**
+ * Process a component's props in one place:
+ * - strip className/style
+ * - process spacing/size/position props (including breakpoint mapping + token conversion)
+ * - process allowlisted non-spacing responsive layout props (breakpoint mapping only)
+ *
+ * The allowlist is grouped by component via `BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT`.
+ *
+ * @param {T} props - The component props to process.
+ * @param {ProcessBpkComponentPropsOptions} options - Component processing options (allowlist group + mapping).
+ * @returns {Record<string, any>} The processed props ready to pass to Chakra primitives.
+ */
+export declare function processBpkComponentProps<T extends Record<string, any>>(props: T, options: ProcessBpkComponentPropsOptions): Record<string, any>;
+/**
+ * Converts Backpack spacing token to Chakra UI compatible value
+ * Returns the actual spacing value from the theme, not a token path
+ *
+ * @param {string} value - Backpack spacing token (e.g., 'bpk-spacing-base') or percentage
+ * @returns {string} The actual spacing value in rem or the percentage string
+ */
+export declare function convertBpkSpacingToChakra(value: string): string;
+/**
+ * Recursively processes responsive values (arrays or objects) to validate and convert tokens
+ *
+ * @param {*} value - The value to process (could be string, array, or object)
+ * @param {Function} converter - Function to convert valid tokens to actual values
+ * @param {Function} validator - Function to validate if a token is allowed
+ * @param {string} propName - The name of the prop being processed (for warning messages)
+ * @returns {*} The processed value with tokens converted, or undefined for invalid tokens
+ */
+export declare function normalizeResponsiveObject<T>(value: Record<string, T>): Record<string, T>;
+export declare function processResponsiveValue(value: any, converter: (v: string) => string, validator: (v: string) => boolean, propName: string): any;
+/**
+ * Validates and converts spacing props for Chakra UI
+ * Handles all spacing-related properties including padding, margin, gap, size, border radius and position
+ *
+ * @param {T} props - Component props object
+ * @returns {Record<string, any>} Processed props with spacing tokens converted to actual values
+ */
+export declare function processSpacingProps<T extends Record<string, any>>(props: T): Record<string, any>;
+/**
+ * Processes all props to convert Backpack tokens to Chakra UI format
+ * Also explicitly removes className and style to prevent ad-hoc overrides
+ *
+ * Processing order:
+ * 1. Remove className & style
+ * 2. Process spacing props (includes position)
+ *
+ * @param {T} props - Component props object
+ * @returns {Record<string, any>} Processed props with tokens converted and disallowed props removed
+ */
+export declare function processBpkProps<T extends Record<string, any>>(props: T): Record<string, any>;
+/**
+ * Processes responsive props that are simple string/enum values (non-spacing)
+ * using Backpack breakpoint keys. Array syntax is rejected as in spacing.
+ *
+ * @param {*} value - The value to process
+ * @param {string} propName - The name of the prop being processed
+ * @returns {*} The processed value with breakpoint keys mapped to Chakra keys
+ */
+export declare function processResponsiveStringProp(value: any, propName: string): any;
+/**
+ * Processes a collection of responsive props.
+ * @param {Record<string, any>} props - Object containing prop values.
+ * @param {Record<string, string>} propNameMap - Map of prop name to CSS/Chakra property name (for error messages and mapping).
+ * @returns {Record<string, any>} Processed props object.
+ */
+export declare function processResponsiveProps(props: Record<string, any>, propNameMap?: Record<string, string>): Record<string, any>;
+export {};

package/bpk-component-layout/src/tokenUtils.js

@@ -0,0 +1,323 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import StackOptionKeys from "./BpkStack.constant";
+import { getSpacingValue } from "./theme";
+import { BpkBreakpointToChakraKey, isValidSpacingValue, isValidSizeValue, isValidPositionValue, isPercentage } from "./tokens";
+
+/**
+ * Allowlisted, component-scoped prop groups that are eligible for Backpack responsive value
+ * processing (Backpack breakpoint keys -> Chakra breakpoint keys).
+ *
+ * NOTE:
+ * - Spacing/size/position props are processed separately via `processBpkProps` and therefore
+ *   are intentionally NOT included here.
+ * - These groups are meant to keep the responsive surface predictable per component, while
+ *   avoiding duplicated per-component breakpoint mapping logic.
+ */
+
+export const BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT = {
+  BpkBox: {
+    container: [
+    // Display
+    'display',
+    // Flex container props
+    'flexDirection', 'flexWrap', 'justifyContent', 'alignItems', 'alignContent',
+    // Grid container props
+    'gridTemplateColumns', 'gridTemplateRows', 'gridTemplateAreas', 'gridAutoFlow', 'gridAutoRows', 'gridAutoColumns'],
+    item: [
+    // Flex item props
+    'flex', 'flexGrow', 'flexShrink', 'flexBasis', 'order', 'alignSelf', 'justifySelf',
+    // Grid item placement props (useful on Box when composing grids)
+    'gridColumn', 'gridRow']
+  },
+  // Note: BpkFlex maps its public API props to these Chakra keys.
+  BpkFlex: {
+    container: ['flexDirection', 'justifyContent', 'alignItems', 'flexWrap'],
+    item: ['flexGrow', 'flexShrink', 'flexBasis']
+  },
+  // Note: BpkGrid maps its public API props to these Chakra keys.
+  BpkGrid: {
+    container: ['justifyContent', 'alignItems', 'gridTemplateColumns', 'gridTemplateRows', 'gridTemplateAreas', 'gridAutoFlow', 'gridAutoRows', 'gridAutoColumns'],
+    item: [
+    // Used when placing the grid itself within a parent grid.
+    'gridColumn', 'gridRow']
+  },
+  // Note: BpkStack uses Chakra Stack option prop names directly.
+  BpkStack: {
+    container: StackOptionKeys
+  }
+};
+export const BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT = {
+  BpkBox: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkBox.container, ...(BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkBox.item ?? [])],
+  BpkFlex: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkFlex.container, ...(BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkFlex.item ?? [])],
+  BpkGrid: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkGrid.container, ...(BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkGrid.item ?? [])],
+  BpkStack: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkStack.container]
+};
+function filterToAllowlist(props, allowlist) {
+  const allowed = new Set(allowlist);
+  const result = {};
+  Object.keys(props).forEach(key => {
+    if (allowed.has(key) && props[key] !== undefined) {
+      result[key] = props[key];
+    }
+  });
+  return result;
+}
+
+/**
+ * Process a component's props in one place:
+ * - strip className/style
+ * - process spacing/size/position props (including breakpoint mapping + token conversion)
+ * - process allowlisted non-spacing responsive layout props (breakpoint mapping only)
+ *
+ * The allowlist is grouped by component via `BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT`.
+ *
+ * @param {T} props - The component props to process.
+ * @param {ProcessBpkComponentPropsOptions} options - Component processing options (allowlist group + mapping).
+ * @returns {Record<string, any>} The processed props ready to pass to Chakra primitives.
+ */
+export function processBpkComponentProps(props, options) {
+  const processed = processBpkProps(props);
+  const allowlist = BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT[options.component];
+  const responsiveSource = options.responsiveProps ? filterToAllowlist(options.responsiveProps, allowlist) : filterToAllowlist(processed, allowlist);
+  if (Object.keys(responsiveSource).length === 0) {
+    return processed;
+  }
+
+  // Ensure allowlisted layout props do NOT fall through unprocessed (e.g. array responsive values).
+  // These props must be provided via the responsive processing pipeline only.
+  const cleanedProcessed = {
+    ...processed
+  };
+  allowlist.forEach(key => {
+    if (key in cleanedProcessed) {
+      delete cleanedProcessed[key];
+    }
+  });
+  const responsiveProcessed = processResponsiveProps(responsiveSource, options.propNameMap);
+
+  // Remove keys that ended up as `undefined` (e.g. array responsive values are rejected).
+  Object.keys(responsiveProcessed).forEach(key => {
+    if (responsiveProcessed[key] === undefined) {
+      delete responsiveProcessed[key];
+    }
+  });
+  return {
+    ...cleanedProcessed,
+    ...responsiveProcessed
+  };
+}
+
+/**
+ * Converts Backpack spacing token to Chakra UI compatible value
+ * Returns the actual spacing value from the theme, not a token path
+ *
+ * @param {string} value - Backpack spacing token (e.g., 'bpk-spacing-base') or percentage
+ * @returns {string} The actual spacing value in rem or the percentage string
+ */
+export function convertBpkSpacingToChakra(value) {
+  if (isPercentage(value)) {
+    return value; // Percentages pass through
+  }
+
+  // Look up the actual spacing value from the theme
+  const spacingValue = getSpacingValue(value);
+  if (spacingValue !== undefined) {
+    return spacingValue;
+  }
+
+  // Fallback: if token not found, return the value as-is (will cause a warning)
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn(`Spacing token "${value}" not found in theme. Returning as-is.`);
+  }
+  return value;
+}
+
+/**
+ * Recursively processes responsive values (arrays or objects) to validate and convert tokens
+ *
+ * @param {*} value - The value to process (could be string, array, or object)
+ * @param {Function} converter - Function to convert valid tokens to actual values
+ * @param {Function} validator - Function to validate if a token is allowed
+ * @param {string} propName - The name of the prop being processed (for warning messages)
+ * @returns {*} The processed value with tokens converted, or undefined for invalid tokens
+ */
+export function normalizeResponsiveObject(value) {
+  const normalized = {};
+  Object.entries(value).forEach(([key, val]) => {
+    if (key === 'base') {
+      normalized.base = val;
+      return;
+    }
+    const chakraKey = BpkBreakpointToChakraKey[key];
+    if (chakraKey) {
+      normalized[chakraKey] = val;
+    } else if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(`Unknown breakpoint "${key}" used in responsive prop. ` + 'Use Backpack breakpoint tokens such as mobile, tablet or desktop.');
+    }
+  });
+  return normalized;
+}
+export function processResponsiveValue(value, converter, validator, propName) {
+  if (value === undefined || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(`Array-based responsive values are not supported for prop "${propName}". ` + `Please use Backpack breakpoint keys instead.`);
+    }
+    return undefined;
+  }
+  if (typeof value === 'object') {
+    const normalized = normalizeResponsiveObject(value);
+    const result = {};
+    Object.keys(normalized).forEach(key => {
+      const processedValue = processResponsiveValue(normalized[key], converter, validator, propName);
+      if (processedValue !== undefined) {
+        result[key] = processedValue;
+      }
+    });
+    return Object.keys(result).length > 0 ? result : undefined;
+  }
+  const strValue = String(value);
+  if (!validator(strValue)) {
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(`Invalid value "${strValue}" for prop "${propName}". ` + `Only Backpack tokens are allowed.`);
+    }
+    return undefined; // Invalid values are removed
+  }
+  return converter(strValue);
+}
+
+/**
+ * Validates and converts spacing props for Chakra UI
+ * Handles all spacing-related properties including padding, margin, gap, size, border radius and position
+ *
+ * @param {T} props - Component props object
+ * @returns {Record<string, any>} Processed props with spacing tokens converted to actual values
+ */
+export function processSpacingProps(props) {
+  const spacingKeys = [
+  // Padding props
+  'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft', 'paddingStart', 'paddingEnd', 'paddingInline',
+  // Margin props
+  'margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft', 'marginStart', 'marginEnd', 'marginInline',
+  // Gap and spacing
+  'gap', 'spacing', 'rowGap', 'columnGap',
+  // Size props
+  'width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight',
+  // Position props
+  'top', 'right', 'bottom', 'left'];
+  const processed = {
+    ...props
+  };
+  spacingKeys.forEach(key => {
+    if (key in processed && processed[key] !== undefined) {
+      const sizeKeys = ['width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight'];
+      const positionKeys = ['top', 'right', 'bottom', 'left'];
+      const isSizeProp = sizeKeys.includes(key);
+      const isPositionProp = positionKeys.includes(key);
+      let converter;
+      if (isSizeProp || isPositionProp) {
+        converter = v => v;
+      } else {
+        converter = convertBpkSpacingToChakra;
+      }
+      let validator;
+      if (isSizeProp) {
+        validator = isValidSizeValue;
+      } else if (isPositionProp) {
+        validator = isValidPositionValue;
+      } else {
+        validator = isValidSpacingValue;
+      }
+      const processedValue = processResponsiveValue(processed[key], converter, validator, key);
+      if (processedValue !== undefined) {
+        processed[key] = processedValue;
+      } else {
+        delete processed[key];
+      }
+    }
+  });
+  return processed;
+}
+
+/**
+ * Processes all props to convert Backpack tokens to Chakra UI format
+ * Also explicitly removes className and style to prevent ad-hoc overrides
+ *
+ * Processing order:
+ * 1. Remove className & style
+ * 2. Process spacing props (includes position)
+ *
+ * @param {T} props - Component props object
+ * @returns {Record<string, any>} Processed props with tokens converted and disallowed props removed
+ */
+export function processBpkProps(props) {
+  // Explicitly remove className and style to prevent style overrides
+  const {
+    className,
+    style,
+    ...cleanProps
+  } = props;
+  if (className !== undefined && process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn('className prop is not allowed on Backpack layout components. ' + 'It has been removed to maintain design system consistency.');
+  }
+  if (style !== undefined && process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn('style prop is not allowed on Backpack layout components. ' + 'It has been removed to maintain design system consistency.');
+  }
+
+  // Process spacing props (includes position)
+  return processSpacingProps(cleanProps);
+}
+
+/**
+ * Processes responsive props that are simple string/enum values (non-spacing)
+ * using Backpack breakpoint keys. Array syntax is rejected as in spacing.
+ *
+ * @param {*} value - The value to process
+ * @param {string} propName - The name of the prop being processed
+ * @returns {*} The processed value with breakpoint keys mapped to Chakra keys
+ */
+export function processResponsiveStringProp(value, propName) {
+  return processResponsiveValue(value, v => v, () => true, propName);
+}
+
+/**
+ * Processes a collection of responsive props.
+ * @param {Record<string, any>} props - Object containing prop values.
+ * @param {Record<string, string>} propNameMap - Map of prop name to CSS/Chakra property name (for error messages and mapping).
+ * @returns {Record<string, any>} Processed props object.
+ */
+export function processResponsiveProps(props, propNameMap) {
+  const processed = {};
+  Object.keys(props).forEach(key => {
+    if (props[key] !== undefined) {
+      const targetPropName = propNameMap ? propNameMap[key] || key : key;
+      processed[targetPropName] = processResponsiveStringProp(props[key], targetPropName);
+    }
+  });
+  return processed;
+}