From 6c528cc51ae1d1417644ed0949c61ab9d9ff7bd3 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 1 Apr 2026 16:26:09 +0000
Subject: [PATCH 1/9] feat(shared): migrate Box to ADR-0003 and ADR-0004 shared
 types (DSYS-482)

- Create packages/design-system-shared/src/types/Box/Box.types.ts with:
  - BoxFlexDirection, BoxFlexWrap, BoxAlignItems, BoxJustifyContent,
    BoxBackgroundColor, BoxBorderColor converted from enums to const objects (ADR-0003)
  - BoxSpacing, BoxBorderWidth type aliases (unchanged primitive types)
  - BoxPropsShared new shared props type with platform-independent properties (ADR-0004)
- Export Box types from @metamask/design-system-shared index
- Update React package Box.types.ts to extend BoxPropsShared from shared
- Update React package Box/index.ts to export const objects from shared
- Update React Native package Box.types.ts to extend BoxPropsShared from shared
- Update React Native package Box/index.ts to export const objects from shared
- Remove old Box enums from both platform type indices
- Update all files importing Box types to import from @metamask/design-system-shared

Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
---
 .../BannerAlert/BannerAlert.constants.ts      |   9 +-
 .../BannerAlert/BannerAlert.test.tsx          |   3 +-
 .../src/components/BannerBase/BannerBase.tsx  |  11 +-
 .../src/components/Box/Box.constants.ts       |   5 +-
 .../src/components/Box/Box.stories.tsx        |  17 +-
 .../src/components/Box/Box.test.tsx           |  15 +-
 .../src/components/Box/Box.types.ts           | 129 +-------
 .../src/components/Box/index.ts               |   5 +-
 .../src/components/BoxColumn/BoxColumn.tsx    |   2 +-
 .../src/components/BoxRow/BoxRow.tsx          |   5 +-
 .../ButtonBase/ButtonBase.stories.tsx         |   3 +-
 .../src/components/Card/Card.stories.tsx      |   2 +-
 .../MainActionButton.stories.tsx              |   2 +-
 .../TabEmptyState/TabEmptyState.stories.tsx   |   2 +-
 .../Blockies/Blockies.stories.tsx             |  12 +-
 .../Jazzicon/Jazzicon.stories.tsx             |  12 +-
 .../Maskicon/Maskicon.stories.tsx             |  12 +-
 .../src/types/index.ts                        | 182 -----------
 .../BannerAlert/BannerAlert.constants.ts      |   9 +-
 .../BannerAlert/BannerAlert.test.tsx          |   3 +-
 .../src/components/BannerBase/BannerBase.tsx  |  11 +-
 .../src/components/Box/Box.constants.ts       |   5 +-
 .../src/components/Box/Box.stories.tsx        |  15 +-
 .../src/components/Box/Box.test.tsx           |   7 +-
 .../src/components/Box/Box.types.ts           | 143 +-------
 .../src/components/Box/index.ts               |   5 +-
 .../design-system-react/src/types/index.ts    | 182 -----------
 packages/design-system-shared/src/index.ts    |  13 +
 .../src/types/Box/Box.types.ts                | 308 ++++++++++++++++++
 .../src/types/Box/index.ts                    |  11 +
 30 files changed, 445 insertions(+), 695 deletions(-)
 create mode 100644 packages/design-system-shared/src/types/Box/Box.types.ts
 create mode 100644 packages/design-system-shared/src/types/Box/index.ts

diff --git a/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.constants.ts b/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.constants.ts
index bcb9e91f3..012a8f31b 100644
--- a/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.constants.ts
+++ b/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.constants.ts
@@ -1,11 +1,10 @@
-import { BannerAlertSeverity } from '@metamask/design-system-shared';
-
 import {
+  BannerAlertSeverity,
   BoxBackgroundColor,
   BoxBorderColor,
-  IconColor,
-  IconName,
-} from '../../types';
+} from '@metamask/design-system-shared';
+
+import { IconColor, IconName } from '../../types';
 
 export const MAP_BANNER_ALERT_SEVERITY_ICON_NAME: Record<
   (typeof BannerAlertSeverity)[keyof typeof BannerAlertSeverity],
diff --git a/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.test.tsx b/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.test.tsx
index 3d5f66cbf..e6504af4f 100644
--- a/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.test.tsx
+++ b/packages/design-system-react-native/src/components/BannerAlert/BannerAlert.test.tsx
@@ -1,8 +1,9 @@
+import { BoxBackgroundColor } from '@metamask/design-system-shared';
 import { useTailwind } from '@metamask/design-system-twrnc-preset';
 import { render } from '@testing-library/react-native';
 import React from 'react';
 
-import { BoxBackgroundColor, IconColor, IconName } from '../../types';
+import { IconColor, IconName } from '../../types';
 import { BannerBase } from '../BannerBase';
 
 import { BannerAlert } from './BannerAlert';
diff --git a/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx b/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx
index 63eba2c9c..55a662dc9 100644
--- a/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx
+++ b/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx
@@ -1,13 +1,16 @@
-import { FontWeight, TextVariant } from '@metamask/design-system-shared';
+import {
+  BoxAlignItems,
+  BoxBackgroundColor,
+  BoxFlexDirection,
+  FontWeight,
+  TextVariant,
+} from '@metamask/design-system-shared';
 import React from 'react';
 import { GestureResponderEvent } from 'react-native';
 
 import {
-  BoxAlignItems,
-  BoxBackgroundColor,
   ButtonIconSize,
   ButtonSize,
-  BoxFlexDirection,
   IconName,
 } from '../../types';
 import { Box } from '../Box';
diff --git a/packages/design-system-react-native/src/components/Box/Box.constants.ts b/packages/design-system-react-native/src/components/Box/Box.constants.ts
index 4b7b390d8..ac2577ad4 100644
--- a/packages/design-system-react-native/src/components/Box/Box.constants.ts
+++ b/packages/design-system-react-native/src/components/Box/Box.constants.ts
@@ -1,4 +1,7 @@
-import type { BoxSpacing, BoxBorderWidth } from '../../types';
+import type {
+  BoxSpacing,
+  BoxBorderWidth,
+} from '@metamask/design-system-shared';
 
 export const TWCLASSMAP_BOX_GAP: Record<BoxSpacing, string> = {
   0: 'gap-0',
diff --git a/packages/design-system-react-native/src/components/Box/Box.stories.tsx b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
index ed5b7f17e..7fde07f9e 100644
--- a/packages/design-system-react-native/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
@@ -1,16 +1,15 @@
-import { TextColor } from '@metamask/design-system-shared';
-import type { Meta, StoryObj } from '@storybook/react-native';
-import React from 'react';
-import { ScrollView } from 'react-native';
-
 import {
-  BoxFlexDirection,
-  BoxFlexWrap,
   BoxAlignItems,
-  BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-} from '../../types';
+  BoxFlexDirection,
+  BoxFlexWrap,
+  BoxJustifyContent,
+  TextColor,
+} from '@metamask/design-system-shared';
+import type { Meta, StoryObj } from '@storybook/react-native';
+import React from 'react';
+import { ScrollView } from 'react-native';
 import { Text } from '../Text';
 
 import { Box } from './Box';
diff --git a/packages/design-system-react-native/src/components/Box/Box.test.tsx b/packages/design-system-react-native/src/components/Box/Box.test.tsx
index 282a86c09..54088a3fb 100644
--- a/packages/design-system-react-native/src/components/Box/Box.test.tsx
+++ b/packages/design-system-react-native/src/components/Box/Box.test.tsx
@@ -1,10 +1,3 @@
-import { useTailwind } from '@metamask/design-system-twrnc-preset';
-import { renderHook } from '@testing-library/react-hooks';
-import { render } from '@testing-library/react-native';
-import React from 'react';
-import { Text } from 'react-native';
-import type { StyleProp, ViewStyle } from 'react-native';
-
 import {
   BoxFlexDirection,
   BoxFlexWrap,
@@ -12,7 +5,13 @@ import {
   BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-} from '../../types';
+} from '@metamask/design-system-shared';
+import { useTailwind } from '@metamask/design-system-twrnc-preset';
+import { renderHook } from '@testing-library/react-hooks';
+import { render } from '@testing-library/react-native';
+import React from 'react';
+import { Text } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
 
 import { Box } from './Box';
 import {
diff --git a/packages/design-system-react-native/src/components/Box/Box.types.ts b/packages/design-system-react-native/src/components/Box/Box.types.ts
index 343bcfab1..bdfa03758 100644
--- a/packages/design-system-react-native/src/components/Box/Box.types.ts
+++ b/packages/design-system-react-native/src/components/Box/Box.types.ts
@@ -1,123 +1,10 @@
+import type { BoxPropsShared } from '@metamask/design-system-shared';
 import type { ViewProps } from 'react-native';
 
-import type {
-  BoxFlexDirection,
-  BoxFlexWrap,
-  BoxSpacing,
-  BoxBorderWidth,
-  BoxAlignItems,
-  BoxJustifyContent,
-  BoxBackgroundColor,
-  BoxBorderColor,
-} from '../../types';
-
-export type BoxProps = {
-  /**
-   * The flexDirection style of the component.
-   */
-  flexDirection?: BoxFlexDirection;
-  /**
-   * The flexWrap style of the component.
-   */
-  flexWrap?: BoxFlexWrap;
-  /**
-   * The gap between the component's children.
-   * Use 1-12 for a gap of 4px-48px.
-   */
-  gap?: BoxSpacing;
-  /**
-   * The alignItems style of the component.
-   */
-  alignItems?: BoxAlignItems;
-  /**
-   * The justifyContent style of the component.
-   */
-  justifyContent?: BoxJustifyContent;
-  /**
-   * The margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  margin?: BoxSpacing;
-  /**
-   * The top margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  marginTop?: BoxSpacing;
-  /**
-   * The right margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  marginRight?: BoxSpacing;
-  /**
-   * The bottom margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  marginBottom?: BoxSpacing;
-  /**
-   * The left margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  marginLeft?: BoxSpacing;
-  /**
-   * The horizontal margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  marginHorizontal?: BoxSpacing;
-  /**
-   * The vertical margin of the component.
-   * Use 1-12 for margin of 4px-48px.
-   */
-  marginVertical?: BoxSpacing;
-  /**
-   * The padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  padding?: BoxSpacing;
-  /**
-   * The top padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  paddingTop?: BoxSpacing;
-  /**
-   * The right padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  paddingRight?: BoxSpacing;
-  /**
-   * The bottom padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  paddingBottom?: BoxSpacing;
-  /**
-   * The left padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  paddingLeft?: BoxSpacing;
-  /**
-   * The horizontal padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  paddingHorizontal?: BoxSpacing;
-  /**
-   * The vertical padding of the component.
-   * Use 1-12 for padding of 4px-48px.
-   */
-  paddingVertical?: BoxSpacing;
-  /**
-   * The border width of the component.
-   * Use 0, 1, 2, 4, or 8 for border width of 0px, 1px, 2px, 4px, or 8px.
-   */
-  borderWidth?: BoxBorderWidth;
-  /**
-   * The border color of the component.
-   */
-  borderColor?: BoxBorderColor;
-  /**
-   * The background color of the component.
-   */
-  backgroundColor?: BoxBackgroundColor;
-  /**
-   * Optional prop to add twrnc overriding classNames.
-   */
-  twClassName?: string;
-} & ViewProps;
+export type BoxProps = BoxPropsShared &
+  ViewProps & {
+    /**
+     * Optional prop to add twrnc overriding classNames.
+     */
+    twClassName?: string;
+  };
diff --git a/packages/design-system-react-native/src/components/Box/index.ts b/packages/design-system-react-native/src/components/Box/index.ts
index a79b71ab8..0cad656a6 100644
--- a/packages/design-system-react-native/src/components/Box/index.ts
+++ b/packages/design-system-react-native/src/components/Box/index.ts
@@ -5,7 +5,8 @@ export {
   BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-} from '../../types';
-export type { BoxSpacing, BoxBorderWidth } from '../../types';
+  type BoxSpacing,
+  type BoxBorderWidth,
+} from '@metamask/design-system-shared';
 export { Box } from './Box';
 export type { BoxProps } from './Box.types';
diff --git a/packages/design-system-react-native/src/components/BoxColumn/BoxColumn.tsx b/packages/design-system-react-native/src/components/BoxColumn/BoxColumn.tsx
index 1741e8b08..e2d7534be 100644
--- a/packages/design-system-react-native/src/components/BoxColumn/BoxColumn.tsx
+++ b/packages/design-system-react-native/src/components/BoxColumn/BoxColumn.tsx
@@ -1,6 +1,6 @@
+import { BoxFlexDirection } from '@metamask/design-system-shared';
 import React from 'react';
 
-import { BoxFlexDirection } from '../../types';
 import { Box } from '../Box';
 import { TextOrChildren } from '../temp-components/TextOrChildren';
 
diff --git a/packages/design-system-react-native/src/components/BoxRow/BoxRow.tsx b/packages/design-system-react-native/src/components/BoxRow/BoxRow.tsx
index ca8fcfd55..b38f731a1 100644
--- a/packages/design-system-react-native/src/components/BoxRow/BoxRow.tsx
+++ b/packages/design-system-react-native/src/components/BoxRow/BoxRow.tsx
@@ -1,6 +1,9 @@
+import {
+  BoxAlignItems,
+  BoxFlexDirection,
+} from '@metamask/design-system-shared';
 import React from 'react';
 
-import { BoxAlignItems, BoxFlexDirection } from '../../types';
 import { Box } from '../Box';
 import { TextOrChildren } from '../temp-components/TextOrChildren';
 
diff --git a/packages/design-system-react-native/src/components/ButtonBase/ButtonBase.stories.tsx b/packages/design-system-react-native/src/components/ButtonBase/ButtonBase.stories.tsx
index a867b767c..378d20406 100644
--- a/packages/design-system-react-native/src/components/ButtonBase/ButtonBase.stories.tsx
+++ b/packages/design-system-react-native/src/components/ButtonBase/ButtonBase.stories.tsx
@@ -1,6 +1,7 @@
+import { BoxFlexDirection } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 
-import { BoxFlexDirection, ButtonBaseSize } from '../../types';
+import { ButtonBaseSize } from '../../types';
 import { Box } from '../Box';
 import { IconName } from '../Icon';
 
diff --git a/packages/design-system-react-native/src/components/Card/Card.stories.tsx b/packages/design-system-react-native/src/components/Card/Card.stories.tsx
index d0b66e639..723e231ca 100644
--- a/packages/design-system-react-native/src/components/Card/Card.stories.tsx
+++ b/packages/design-system-react-native/src/components/Card/Card.stories.tsx
@@ -1,7 +1,7 @@
+import { BoxBackgroundColor } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 
-import { BoxBackgroundColor } from '../../types';
 import { Box } from '../Box';
 import { Text } from '../Text';
 
diff --git a/packages/design-system-react-native/src/components/MainActionButton/MainActionButton.stories.tsx b/packages/design-system-react-native/src/components/MainActionButton/MainActionButton.stories.tsx
index 36df83704..7112b0cce 100644
--- a/packages/design-system-react-native/src/components/MainActionButton/MainActionButton.stories.tsx
+++ b/packages/design-system-react-native/src/components/MainActionButton/MainActionButton.stories.tsx
@@ -1,6 +1,6 @@
+import { BoxFlexDirection } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 
-import { BoxFlexDirection } from '../../types';
 import { Box } from '../Box';
 import { IconName } from '../Icon';
 
diff --git a/packages/design-system-react-native/src/components/TabEmptyState/TabEmptyState.stories.tsx b/packages/design-system-react-native/src/components/TabEmptyState/TabEmptyState.stories.tsx
index 644312a25..3ed5a3952 100644
--- a/packages/design-system-react-native/src/components/TabEmptyState/TabEmptyState.stories.tsx
+++ b/packages/design-system-react-native/src/components/TabEmptyState/TabEmptyState.stories.tsx
@@ -1,7 +1,7 @@
+import { BoxBackgroundColor } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 
-import { BoxBackgroundColor } from '../../types';
 import { Box } from '../Box';
 import { Icon, IconName, IconSize } from '../Icon';
 import { Text } from '../Text';
diff --git a/packages/design-system-react-native/src/components/temp-components/Blockies/Blockies.stories.tsx b/packages/design-system-react-native/src/components/temp-components/Blockies/Blockies.stories.tsx
index 480060b6e..546012384 100644
--- a/packages/design-system-react-native/src/components/temp-components/Blockies/Blockies.stories.tsx
+++ b/packages/design-system-react-native/src/components/temp-components/Blockies/Blockies.stories.tsx
@@ -1,14 +1,12 @@
-import type { Meta, StoryObj } from '@storybook/react-native';
-import { ScrollView } from 'react-native';
-
 import {
-  TextVariant,
-  TextColor,
-  FontWeight,
   BoxFlexDirection,
   BoxFlexWrap,
   BoxAlignItems,
-} from '../../../types';
+} from '@metamask/design-system-shared';
+import type { Meta, StoryObj } from '@storybook/react-native';
+import { ScrollView } from 'react-native';
+
+import { TextVariant, TextColor, FontWeight } from '../../../types';
 import { Box } from '../../Box';
 import { Text } from '../../Text';
 
diff --git a/packages/design-system-react-native/src/components/temp-components/Jazzicon/Jazzicon.stories.tsx b/packages/design-system-react-native/src/components/temp-components/Jazzicon/Jazzicon.stories.tsx
index ac4161abb..194a77f30 100644
--- a/packages/design-system-react-native/src/components/temp-components/Jazzicon/Jazzicon.stories.tsx
+++ b/packages/design-system-react-native/src/components/temp-components/Jazzicon/Jazzicon.stories.tsx
@@ -1,14 +1,12 @@
-import type { Meta, StoryObj } from '@storybook/react-native';
-import { ScrollView } from 'react-native';
-
 import {
-  TextVariant,
-  TextColor,
-  FontWeight,
   BoxFlexDirection,
   BoxFlexWrap,
   BoxAlignItems,
-} from '../../../types';
+} from '@metamask/design-system-shared';
+import type { Meta, StoryObj } from '@storybook/react-native';
+import { ScrollView } from 'react-native';
+
+import { TextVariant, TextColor, FontWeight } from '../../../types';
 import { Box } from '../../Box';
 import { Text } from '../../Text';
 
diff --git a/packages/design-system-react-native/src/components/temp-components/Maskicon/Maskicon.stories.tsx b/packages/design-system-react-native/src/components/temp-components/Maskicon/Maskicon.stories.tsx
index 4907db0e6..03cc785eb 100644
--- a/packages/design-system-react-native/src/components/temp-components/Maskicon/Maskicon.stories.tsx
+++ b/packages/design-system-react-native/src/components/temp-components/Maskicon/Maskicon.stories.tsx
@@ -1,14 +1,12 @@
-import type { Meta, StoryObj } from '@storybook/react-native';
-import { ScrollView } from 'react-native';
-
 import {
-  TextVariant,
-  TextColor,
-  FontWeight,
   BoxFlexDirection,
   BoxFlexWrap,
   BoxAlignItems,
-} from '../../../types';
+} from '@metamask/design-system-shared';
+import type { Meta, StoryObj } from '@storybook/react-native';
+import { ScrollView } from 'react-native';
+
+import { TextVariant, TextColor, FontWeight } from '../../../types';
 import { Box } from '../../Box';
 import { Text } from '../../Text';
 
diff --git a/packages/design-system-react-native/src/types/index.ts b/packages/design-system-react-native/src/types/index.ts
index c326c94af..d52bce6cd 100644
--- a/packages/design-system-react-native/src/types/index.ts
+++ b/packages/design-system-react-native/src/types/index.ts
@@ -29,188 +29,6 @@ export enum AvatarIconSeverity {
   Warning = 'warning',
 }
 
-/**
- * Box - all spacing-related props
- */
-export type BoxSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
-
-/**
- * Box - border width values (only valid Tailwind CSS border width utilities)
- */
-export type BoxBorderWidth = 0 | 1 | 2 | 4 | 8;
-
-/**
- * Box - flexDirection
- */
-export enum BoxFlexDirection {
-  Row = 'flex-row',
-  RowReverse = 'flex-row-reverse',
-  Column = 'flex-col',
-  ColumnReverse = 'flex-col-reverse',
-}
-
-/**
- * Box - flexWrap
- */
-export enum BoxFlexWrap {
-  NoWrap = 'flex-nowrap',
-  Wrap = 'flex-wrap',
-  WrapReverse = 'flex-wrap-reverse',
-}
-
-/**
- * Box - alignItems
- */
-export enum BoxAlignItems {
-  Start = 'items-start',
-  Center = 'items-center',
-  End = 'items-end',
-  Stretch = 'items-stretch',
-  Baseline = 'items-baseline',
-}
-
-/**
- * Box - justifyContent
- */
-export enum BoxJustifyContent {
-  Start = 'justify-start',
-  Center = 'justify-center',
-  End = 'justify-end',
-  Between = 'justify-between',
-  Around = 'justify-around',
-  Evenly = 'justify-evenly',
-}
-
-/**
- * Box - backgroundColor
- */
-export enum BoxBackgroundColor {
-  /** Default background color */
-  BackgroundDefault = 'bg-default',
-  /** Alternative background color */
-  BackgroundAlternative = 'bg-alternative',
-  /** Section background color */
-  BackgroundSection = 'bg-section',
-  /** Subsection background color */
-  BackgroundSubsection = 'bg-subsection',
-  /** Muted background color */
-  BackgroundMuted = 'bg-muted',
-  /** Primary default background color */
-  PrimaryDefault = 'bg-primary-default',
-  /** Primary alternative background color */
-  PrimaryAlternative = 'bg-primary-alternative',
-  /** Primary muted background color */
-  PrimaryMuted = 'bg-primary-muted',
-  /** Primary inverse background color */
-  PrimaryInverse = 'bg-primary-inverse',
-  /** Error default background color */
-  ErrorDefault = 'bg-error-default',
-  /** Error alternative background color */
-  ErrorAlternative = 'bg-error-alternative',
-  /** Error muted background color */
-  ErrorMuted = 'bg-error-muted',
-  /** Error inverse background color */
-  ErrorInverse = 'bg-error-inverse',
-  /** Warning default background color */
-  WarningDefault = 'bg-warning-default',
-  /** Warning alternative background color */
-  WarningAlternative = 'bg-warning-alternative',
-  /** Warning muted background color */
-  WarningMuted = 'bg-warning-muted',
-  /** Warning inverse background color */
-  WarningInverse = 'bg-warning-inverse',
-  /** Success default background color */
-  SuccessDefault = 'bg-success-default',
-  /** Success alternative background color */
-  SuccessAlternative = 'bg-success-alternative',
-  /** Success muted background color */
-  SuccessMuted = 'bg-success-muted',
-  /** Success inverse background color */
-  SuccessInverse = 'bg-success-inverse',
-  /** Info default background color */
-  InfoDefault = 'bg-info-default',
-  /** Info muted background color */
-  InfoMuted = 'bg-info-muted',
-  /** Info inverse background color */
-  InfoInverse = 'bg-info-inverse',
-  /** Flask default background color */
-  FlaskDefault = 'bg-flask-default',
-  /** Flask inverse background color */
-  FlaskInverse = 'bg-flask-inverse',
-  /** Overlay alternative background color */
-  OverlayAlternative = 'bg-overlay-alternative',
-  /** Overlay default background color */
-  OverlayDefault = 'bg-overlay-default',
-  /** Overlay inverse background color */
-  OverlayInverse = 'bg-overlay-inverse',
-  /** Transparent background color */
-  Transparent = 'bg-transparent',
-}
-
-/**
- * Box - borderColor
- */
-export enum BoxBorderColor {
-  /** Background default for cut out effect*/
-  BackgroundDefault = 'border-background-default',
-  /** Default border color */
-  BorderDefault = 'border-default',
-  /** Muted border color */
-  BorderMuted = 'border-muted',
-  /** Primary default border color */
-  PrimaryDefault = 'border-primary-default',
-  /** Primary alternative border color */
-  PrimaryAlternative = 'border-primary-alternative',
-  /** Primary muted border color */
-  PrimaryMuted = 'border-primary-muted',
-  /** Primary inverse border color */
-  PrimaryInverse = 'border-primary-inverse',
-  /** Error default border color */
-  ErrorDefault = 'border-error-default',
-  /** Error alternative border color */
-  ErrorAlternative = 'border-error-alternative',
-  /** Error muted border color */
-  ErrorMuted = 'border-error-muted',
-  /** Error inverse border color */
-  ErrorInverse = 'border-error-inverse',
-  /** Warning default border color */
-  WarningDefault = 'border-warning-default',
-  /** Warning alternative border color */
-  WarningAlternative = 'border-warning-alternative',
-  /** Warning muted border color */
-  WarningMuted = 'border-warning-muted',
-  /** Warning inverse border color */
-  WarningInverse = 'border-warning-inverse',
-  /** Success default border color */
-  SuccessDefault = 'border-success-default',
-  /** Success alternative border color */
-  SuccessAlternative = 'border-success-alternative',
-  /** Success muted border color */
-  SuccessMuted = 'border-success-muted',
-  /** Success inverse border color */
-  SuccessInverse = 'border-success-inverse',
-  /** Info default border color */
-  InfoDefault = 'border-info-default',
-  /** Info alternative border color */
-  InfoAlternative = 'border-info-alternative',
-  /** Info muted border color */
-  InfoMuted = 'border-info-muted',
-  /** Info inverse border color */
-  InfoInverse = 'border-info-inverse',
-  /** Flask default border color */
-  FlaskDefault = 'border-flask-default',
-  /** Flask inverse border color */
-  FlaskInverse = 'border-flask-inverse',
-  /** Overlay alternative border color */
-  OverlayAlternative = 'border-overlay-alternative',
-  /** Overlay default border color */
-  OverlayDefault = 'border-overlay-default',
-  /** Overlay inverse border color */
-  OverlayInverse = 'border-overlay-inverse',
-  /** Transparent border color */
-  Transparent = 'border-transparent',
-}
-
 /**
  * ButtonBase - size
  */
diff --git a/packages/design-system-react/src/components/BannerAlert/BannerAlert.constants.ts b/packages/design-system-react/src/components/BannerAlert/BannerAlert.constants.ts
index bcb9e91f3..012a8f31b 100644
--- a/packages/design-system-react/src/components/BannerAlert/BannerAlert.constants.ts
+++ b/packages/design-system-react/src/components/BannerAlert/BannerAlert.constants.ts
@@ -1,11 +1,10 @@
-import { BannerAlertSeverity } from '@metamask/design-system-shared';
-
 import {
+  BannerAlertSeverity,
   BoxBackgroundColor,
   BoxBorderColor,
-  IconColor,
-  IconName,
-} from '../../types';
+} from '@metamask/design-system-shared';
+
+import { IconColor, IconName } from '../../types';
 
 export const MAP_BANNER_ALERT_SEVERITY_ICON_NAME: Record<
   (typeof BannerAlertSeverity)[keyof typeof BannerAlertSeverity],
diff --git a/packages/design-system-react/src/components/BannerAlert/BannerAlert.test.tsx b/packages/design-system-react/src/components/BannerAlert/BannerAlert.test.tsx
index 1e2d68b34..e003e0c8a 100644
--- a/packages/design-system-react/src/components/BannerAlert/BannerAlert.test.tsx
+++ b/packages/design-system-react/src/components/BannerAlert/BannerAlert.test.tsx
@@ -1,7 +1,8 @@
+import { BoxBackgroundColor } from '@metamask/design-system-shared';
 import { render } from '@testing-library/react';
 import React from 'react';
 
-import { BoxBackgroundColor, IconColor } from '../../types';
+import { IconColor } from '../../types';
 
 import { BannerAlert } from './BannerAlert';
 
diff --git a/packages/design-system-react/src/components/BannerBase/BannerBase.tsx b/packages/design-system-react/src/components/BannerBase/BannerBase.tsx
index b8bd113a8..d5a47596f 100644
--- a/packages/design-system-react/src/components/BannerBase/BannerBase.tsx
+++ b/packages/design-system-react/src/components/BannerBase/BannerBase.tsx
@@ -1,12 +1,15 @@
-import { FontWeight, TextVariant } from '@metamask/design-system-shared';
-import React, { forwardRef } from 'react';
-
 import {
   BoxAlignItems,
   BoxBackgroundColor,
+  BoxFlexDirection,
+  FontWeight,
+  TextVariant,
+} from '@metamask/design-system-shared';
+import React, { forwardRef } from 'react';
+
+import {
   ButtonIconSize,
   ButtonSize,
-  BoxFlexDirection,
   IconName,
 } from '../../types';
 import { twMerge } from '../../utils/tw-merge';
diff --git a/packages/design-system-react/src/components/Box/Box.constants.ts b/packages/design-system-react/src/components/Box/Box.constants.ts
index 4b7b390d8..ac2577ad4 100644
--- a/packages/design-system-react/src/components/Box/Box.constants.ts
+++ b/packages/design-system-react/src/components/Box/Box.constants.ts
@@ -1,4 +1,7 @@
-import type { BoxSpacing, BoxBorderWidth } from '../../types';
+import type {
+  BoxSpacing,
+  BoxBorderWidth,
+} from '@metamask/design-system-shared';
 
 export const TWCLASSMAP_BOX_GAP: Record<BoxSpacing, string> = {
   0: 'gap-0',
diff --git a/packages/design-system-react/src/components/Box/Box.stories.tsx b/packages/design-system-react/src/components/Box/Box.stories.tsx
index 9cc3e7f11..bd0d40a48 100644
--- a/packages/design-system-react/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react/src/components/Box/Box.stories.tsx
@@ -1,15 +1,14 @@
-import { TextColor } from '@metamask/design-system-shared';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import React from 'react';
-
 import {
-  BoxFlexDirection,
-  BoxFlexWrap,
   BoxAlignItems,
-  BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-} from '../../types';
+  BoxFlexDirection,
+  BoxFlexWrap,
+  BoxJustifyContent,
+  TextColor,
+} from '@metamask/design-system-shared';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
 import { Text } from '../Text';
 
 import { Box } from './Box';
diff --git a/packages/design-system-react/src/components/Box/Box.test.tsx b/packages/design-system-react/src/components/Box/Box.test.tsx
index e0af3750a..4420ba742 100644
--- a/packages/design-system-react/src/components/Box/Box.test.tsx
+++ b/packages/design-system-react/src/components/Box/Box.test.tsx
@@ -1,6 +1,3 @@
-import { render, screen } from '@testing-library/react';
-import React, { createRef } from 'react';
-
 import {
   BoxAlignItems,
   BoxFlexDirection,
@@ -8,7 +5,9 @@ import {
   BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-} from '../../types';
+} from '@metamask/design-system-shared';
+import { render, screen } from '@testing-library/react';
+import React, { createRef } from 'react';
 
 import { Box } from './Box';
 import {
diff --git a/packages/design-system-react/src/components/Box/Box.types.ts b/packages/design-system-react/src/components/Box/Box.types.ts
index 18684ff9c..3b0558265 100644
--- a/packages/design-system-react/src/components/Box/Box.types.ts
+++ b/packages/design-system-react/src/components/Box/Box.types.ts
@@ -1,130 +1,17 @@
+import type { BoxPropsShared } from '@metamask/design-system-shared';
 import type { ComponentProps } from 'react';
 
-import type {
-  BoxFlexDirection,
-  BoxFlexWrap,
-  BoxSpacing,
-  BoxBorderWidth,
-  BoxAlignItems,
-  BoxJustifyContent,
-  BoxBackgroundColor,
-  BoxBorderColor,
-} from '../../types';
-
-export type BoxProps = ComponentProps<'div'> & {
-  /**
-   * The flex-direction style of the component.
-   */
-  flexDirection?: BoxFlexDirection;
-  /**
-   * The flex-wrap style of the component.
-   */
-  flexWrap?: BoxFlexWrap;
-  /**
-   * The gap between the component's children.
-   * Use 0-12 for a gap of 0px-48px.
-   */
-  gap?: BoxSpacing;
-  /**
-   * The align-items style of the component.
-   */
-  alignItems?: BoxAlignItems;
-  /**
-   * The justify-content style of the component.
-   */
-  justifyContent?: BoxJustifyContent;
-  /**
-   * The margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  margin?: BoxSpacing;
-  /**
-   * The top margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  marginTop?: BoxSpacing;
-  /**
-   * The right margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  marginRight?: BoxSpacing;
-  /**
-   * The bottom margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  marginBottom?: BoxSpacing;
-  /**
-   * The left margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  marginLeft?: BoxSpacing;
-  /**
-   * The horizontal margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  marginHorizontal?: BoxSpacing;
-  /**
-   * The vertical margin of the component.
-   * Use 0-12 for margin of 0px-48px.
-   */
-  marginVertical?: BoxSpacing;
-  /**
-   * The padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  padding?: BoxSpacing;
-  /**
-   * The top padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  paddingTop?: BoxSpacing;
-  /**
-   * The right padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  paddingRight?: BoxSpacing;
-  /**
-   * The bottom padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  paddingBottom?: BoxSpacing;
-  /**
-   * The left padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  paddingLeft?: BoxSpacing;
-  /**
-   * The horizontal padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  paddingHorizontal?: BoxSpacing;
-  /**
-   * The vertical padding of the component.
-   * Use 0-12 for padding of 0px-48px.
-   */
-  paddingVertical?: BoxSpacing;
-  /**
-   * The border width of the component.
-   * Use 0, 1, 2, 4, or 8 for border width of 0px, 1px, 2px, 4px, or 8px.
-   */
-  borderWidth?: BoxBorderWidth;
-  /**
-   * The border color of the component.
-   */
-  borderColor?: BoxBorderColor;
-  /**
-   * The background color of the component.
-   */
-  backgroundColor?: BoxBackgroundColor;
-  /**
-   * Optional prop for additional CSS classes to be applied to the Box component.
-   */
-  className?: string;
-  /**
-   * Optional boolean that determines if the component should merge its props onto its immediate child
-   * instead of rendering a div element
-   *
-   * @default false
-   */
-  asChild?: boolean;
-};
+export type BoxProps = ComponentProps<'div'> &
+  BoxPropsShared & {
+    /**
+     * Optional prop for additional CSS classes to be applied to the Box component.
+     */
+    className?: string;
+    /**
+     * Optional boolean that determines if the component should merge its props onto its immediate child
+     * instead of rendering a div element
+     *
+     * @default false
+     */
+    asChild?: boolean;
+  };
diff --git a/packages/design-system-react/src/components/Box/index.ts b/packages/design-system-react/src/components/Box/index.ts
index 5105a0ca0..0cad656a6 100644
--- a/packages/design-system-react/src/components/Box/index.ts
+++ b/packages/design-system-react/src/components/Box/index.ts
@@ -5,7 +5,8 @@ export {
   BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-} from '../../types';
-export type { BoxSpacing } from '../../types';
+  type BoxSpacing,
+  type BoxBorderWidth,
+} from '@metamask/design-system-shared';
 export { Box } from './Box';
 export type { BoxProps } from './Box.types';
diff --git a/packages/design-system-react/src/types/index.ts b/packages/design-system-react/src/types/index.ts
index 224741501..c48c48455 100644
--- a/packages/design-system-react/src/types/index.ts
+++ b/packages/design-system-react/src/types/index.ts
@@ -29,188 +29,6 @@ export enum AvatarGroupVariant {
   Token = 'token',
 }
 
-/**
- * Box - all spacing-related props
- */
-export type BoxSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
-
-/**
- * Box - border width values (only valid Tailwind CSS border width utilities)
- */
-export type BoxBorderWidth = 0 | 1 | 2 | 4 | 8;
-
-/**
- * Box - flexDirection
- */
-export enum BoxFlexDirection {
-  Row = 'flex-row',
-  RowReverse = 'flex-row-reverse',
-  Column = 'flex-col',
-  ColumnReverse = 'flex-col-reverse',
-}
-
-/**
- * Box - flexWrap
- */
-export enum BoxFlexWrap {
-  NoWrap = 'flex-nowrap',
-  Wrap = 'flex-wrap',
-  WrapReverse = 'flex-wrap-reverse',
-}
-
-/**
- * Box - alignItems
- */
-export enum BoxAlignItems {
-  Start = 'items-start',
-  Center = 'items-center',
-  End = 'items-end',
-  Stretch = 'items-stretch',
-  Baseline = 'items-baseline',
-}
-
-/**
- * Box - justifyContent
- */
-export enum BoxJustifyContent {
-  Start = 'justify-start',
-  Center = 'justify-center',
-  End = 'justify-end',
-  Between = 'justify-between',
-  Around = 'justify-around',
-  Evenly = 'justify-evenly',
-}
-
-/**
- * Box - backgroundColor
- */
-export enum BoxBackgroundColor {
-  /** Default background color */
-  BackgroundDefault = 'bg-default',
-  /** Alternative background color */
-  BackgroundAlternative = 'bg-alternative',
-  /** Section background color */
-  BackgroundSection = 'bg-section',
-  /** Subsection background color */
-  BackgroundSubsection = 'bg-subsection',
-  /** Muted background color */
-  BackgroundMuted = 'bg-muted',
-  /** Primary default background color */
-  PrimaryDefault = 'bg-primary-default',
-  /** Primary alternative background color */
-  PrimaryAlternative = 'bg-primary-alternative',
-  /** Primary muted background color */
-  PrimaryMuted = 'bg-primary-muted',
-  /** Primary inverse background color */
-  PrimaryInverse = 'bg-primary-inverse',
-  /** Error default background color */
-  ErrorDefault = 'bg-error-default',
-  /** Error alternative background color */
-  ErrorAlternative = 'bg-error-alternative',
-  /** Error muted background color */
-  ErrorMuted = 'bg-error-muted',
-  /** Error inverse background color */
-  ErrorInverse = 'bg-error-inverse',
-  /** Warning default background color */
-  WarningDefault = 'bg-warning-default',
-  /** Warning alternative background color */
-  WarningAlternative = 'bg-warning-alternative',
-  /** Warning muted background color */
-  WarningMuted = 'bg-warning-muted',
-  /** Warning inverse background color */
-  WarningInverse = 'bg-warning-inverse',
-  /** Success default background color */
-  SuccessDefault = 'bg-success-default',
-  /** Success alternative background color */
-  SuccessAlternative = 'bg-success-alternative',
-  /** Success muted background color */
-  SuccessMuted = 'bg-success-muted',
-  /** Success inverse background color */
-  SuccessInverse = 'bg-success-inverse',
-  /** Info default background color */
-  InfoDefault = 'bg-info-default',
-  /** Info muted background color */
-  InfoMuted = 'bg-info-muted',
-  /** Info inverse background color */
-  InfoInverse = 'bg-info-inverse',
-  /** Flask default background color */
-  FlaskDefault = 'bg-flask-default',
-  /** Flask inverse background color */
-  FlaskInverse = 'bg-flask-inverse',
-  /** Overlay alternative background color */
-  OverlayAlternative = 'bg-overlay-alternative',
-  /** Overlay default background color */
-  OverlayDefault = 'bg-overlay-default',
-  /** Overlay inverse background color */
-  OverlayInverse = 'bg-overlay-inverse',
-  /** Transparent background color */
-  Transparent = 'bg-transparent',
-}
-
-/**
- * Box - borderColor
- */
-export enum BoxBorderColor {
-  /** Background default for cut out effect */
-  BackgroundDefault = 'border-background-default',
-  /** Default border color */
-  BorderDefault = 'border-default',
-  /** Muted border color */
-  BorderMuted = 'border-muted',
-  /** Primary default border color */
-  PrimaryDefault = 'border-primary-default',
-  /** Primary alternative border color */
-  PrimaryAlternative = 'border-primary-alternative',
-  /** Primary muted border color */
-  PrimaryMuted = 'border-primary-muted',
-  /** Primary inverse border color */
-  PrimaryInverse = 'border-primary-inverse',
-  /** Error default border color */
-  ErrorDefault = 'border-error-default',
-  /** Error alternative border color */
-  ErrorAlternative = 'border-error-alternative',
-  /** Error muted border color */
-  ErrorMuted = 'border-error-muted',
-  /** Error inverse border color */
-  ErrorInverse = 'border-error-inverse',
-  /** Warning default border color */
-  WarningDefault = 'border-warning-default',
-  /** Warning alternative border color */
-  WarningAlternative = 'border-warning-alternative',
-  /** Warning muted border color */
-  WarningMuted = 'border-warning-muted',
-  /** Warning inverse border color */
-  WarningInverse = 'border-warning-inverse',
-  /** Success default border color */
-  SuccessDefault = 'border-success-default',
-  /** Success alternative border color */
-  SuccessAlternative = 'border-success-alternative',
-  /** Success muted border color */
-  SuccessMuted = 'border-success-muted',
-  /** Success inverse border color */
-  SuccessInverse = 'border-success-inverse',
-  /** Info default border color */
-  InfoDefault = 'border-info-default',
-  /** Info alternative border color */
-  InfoAlternative = 'border-info-alternative',
-  /** Info muted border color */
-  InfoMuted = 'border-info-muted',
-  /** Info inverse border color */
-  InfoInverse = 'border-info-inverse',
-  /** Flask default border color */
-  FlaskDefault = 'border-flask-default',
-  /** Flask inverse border color */
-  FlaskInverse = 'border-flask-inverse',
-  /** Overlay alternative border color */
-  OverlayAlternative = 'border-overlay-alternative',
-  /** Overlay default border color */
-  OverlayDefault = 'border-overlay-default',
-  /** Overlay inverse border color */
-  OverlayInverse = 'border-overlay-inverse',
-  /** Transparent border color */
-  Transparent = 'border-transparent',
-}
-
 /**
  * ButtonBase - size
  */
diff --git a/packages/design-system-shared/src/index.ts b/packages/design-system-shared/src/index.ts
index 4f3c81b05..03ffc1c8f 100644
--- a/packages/design-system-shared/src/index.ts
+++ b/packages/design-system-shared/src/index.ts
@@ -117,3 +117,16 @@ export { type CheckboxPropsShared } from './types/Checkbox';
 
 // Tag types (ADR-0003 + ADR-0004)
 export { TagSeverity, type TagPropsShared } from './types/Tag';
+
+// Box types (ADR-0003 + ADR-0004)
+export {
+  BoxFlexDirection,
+  BoxFlexWrap,
+  BoxAlignItems,
+  BoxJustifyContent,
+  BoxBackgroundColor,
+  BoxBorderColor,
+  type BoxSpacing,
+  type BoxBorderWidth,
+  type BoxPropsShared,
+} from './types/Box';
diff --git a/packages/design-system-shared/src/types/Box/Box.types.ts b/packages/design-system-shared/src/types/Box/Box.types.ts
new file mode 100644
index 000000000..13945171a
--- /dev/null
+++ b/packages/design-system-shared/src/types/Box/Box.types.ts
@@ -0,0 +1,308 @@
+/**
+ * Box - all spacing-related props
+ */
+export type BoxSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
+/**
+ * Box - border width values (only valid Tailwind CSS border width utilities)
+ */
+export type BoxBorderWidth = 0 | 1 | 2 | 4 | 8;
+
+/**
+ * Box - flexDirection
+ * Convert from enum to const object (ADR-0003)
+ */
+export const BoxFlexDirection = {
+  Row: 'flex-row',
+  RowReverse: 'flex-row-reverse',
+  Column: 'flex-col',
+  ColumnReverse: 'flex-col-reverse',
+} as const;
+export type BoxFlexDirection =
+  (typeof BoxFlexDirection)[keyof typeof BoxFlexDirection];
+
+/**
+ * Box - flexWrap
+ * Convert from enum to const object (ADR-0003)
+ */
+export const BoxFlexWrap = {
+  NoWrap: 'flex-nowrap',
+  Wrap: 'flex-wrap',
+  WrapReverse: 'flex-wrap-reverse',
+} as const;
+export type BoxFlexWrap = (typeof BoxFlexWrap)[keyof typeof BoxFlexWrap];
+
+/**
+ * Box - alignItems
+ * Convert from enum to const object (ADR-0003)
+ */
+export const BoxAlignItems = {
+  Start: 'items-start',
+  Center: 'items-center',
+  End: 'items-end',
+  Stretch: 'items-stretch',
+  Baseline: 'items-baseline',
+} as const;
+export type BoxAlignItems = (typeof BoxAlignItems)[keyof typeof BoxAlignItems];
+
+/**
+ * Box - justifyContent
+ * Convert from enum to const object (ADR-0003)
+ */
+export const BoxJustifyContent = {
+  Start: 'justify-start',
+  Center: 'justify-center',
+  End: 'justify-end',
+  Between: 'justify-between',
+  Around: 'justify-around',
+  Evenly: 'justify-evenly',
+} as const;
+export type BoxJustifyContent =
+  (typeof BoxJustifyContent)[keyof typeof BoxJustifyContent];
+
+/**
+ * Box - backgroundColor
+ * Convert from enum to const object (ADR-0003)
+ */
+export const BoxBackgroundColor = {
+  /** Default background color */
+  BackgroundDefault: 'bg-default',
+  /** Alternative background color */
+  BackgroundAlternative: 'bg-alternative',
+  /** Section background color */
+  BackgroundSection: 'bg-section',
+  /** Subsection background color */
+  BackgroundSubsection: 'bg-subsection',
+  /** Muted background color */
+  BackgroundMuted: 'bg-muted',
+  /** Primary default background color */
+  PrimaryDefault: 'bg-primary-default',
+  /** Primary alternative background color */
+  PrimaryAlternative: 'bg-primary-alternative',
+  /** Primary muted background color */
+  PrimaryMuted: 'bg-primary-muted',
+  /** Primary inverse background color */
+  PrimaryInverse: 'bg-primary-inverse',
+  /** Error default background color */
+  ErrorDefault: 'bg-error-default',
+  /** Error alternative background color */
+  ErrorAlternative: 'bg-error-alternative',
+  /** Error muted background color */
+  ErrorMuted: 'bg-error-muted',
+  /** Error inverse background color */
+  ErrorInverse: 'bg-error-inverse',
+  /** Warning default background color */
+  WarningDefault: 'bg-warning-default',
+  /** Warning alternative background color */
+  WarningAlternative: 'bg-warning-alternative',
+  /** Warning muted background color */
+  WarningMuted: 'bg-warning-muted',
+  /** Warning inverse background color */
+  WarningInverse: 'bg-warning-inverse',
+  /** Success default background color */
+  SuccessDefault: 'bg-success-default',
+  /** Success alternative background color */
+  SuccessAlternative: 'bg-success-alternative',
+  /** Success muted background color */
+  SuccessMuted: 'bg-success-muted',
+  /** Success inverse background color */
+  SuccessInverse: 'bg-success-inverse',
+  /** Info default background color */
+  InfoDefault: 'bg-info-default',
+  /** Info muted background color */
+  InfoMuted: 'bg-info-muted',
+  /** Info inverse background color */
+  InfoInverse: 'bg-info-inverse',
+  /** Flask default background color */
+  FlaskDefault: 'bg-flask-default',
+  /** Flask inverse background color */
+  FlaskInverse: 'bg-flask-inverse',
+  /** Overlay alternative background color */
+  OverlayAlternative: 'bg-overlay-alternative',
+  /** Overlay default background color */
+  OverlayDefault: 'bg-overlay-default',
+  /** Overlay inverse background color */
+  OverlayInverse: 'bg-overlay-inverse',
+  /** Transparent background color */
+  Transparent: 'bg-transparent',
+} as const;
+export type BoxBackgroundColor =
+  (typeof BoxBackgroundColor)[keyof typeof BoxBackgroundColor];
+
+/**
+ * Box - borderColor
+ * Convert from enum to const object (ADR-0003)
+ */
+export const BoxBorderColor = {
+  /** Background default for cut out effect */
+  BackgroundDefault: 'border-background-default',
+  /** Default border color */
+  BorderDefault: 'border-default',
+  /** Muted border color */
+  BorderMuted: 'border-muted',
+  /** Primary default border color */
+  PrimaryDefault: 'border-primary-default',
+  /** Primary alternative border color */
+  PrimaryAlternative: 'border-primary-alternative',
+  /** Primary muted border color */
+  PrimaryMuted: 'border-primary-muted',
+  /** Primary inverse border color */
+  PrimaryInverse: 'border-primary-inverse',
+  /** Error default border color */
+  ErrorDefault: 'border-error-default',
+  /** Error alternative border color */
+  ErrorAlternative: 'border-error-alternative',
+  /** Error muted border color */
+  ErrorMuted: 'border-error-muted',
+  /** Error inverse border color */
+  ErrorInverse: 'border-error-inverse',
+  /** Warning default border color */
+  WarningDefault: 'border-warning-default',
+  /** Warning alternative border color */
+  WarningAlternative: 'border-warning-alternative',
+  /** Warning muted border color */
+  WarningMuted: 'border-warning-muted',
+  /** Warning inverse border color */
+  WarningInverse: 'border-warning-inverse',
+  /** Success default border color */
+  SuccessDefault: 'border-success-default',
+  /** Success alternative border color */
+  SuccessAlternative: 'border-success-alternative',
+  /** Success muted border color */
+  SuccessMuted: 'border-success-muted',
+  /** Success inverse border color */
+  SuccessInverse: 'border-success-inverse',
+  /** Info default border color */
+  InfoDefault: 'border-info-default',
+  /** Info alternative border color */
+  InfoAlternative: 'border-info-alternative',
+  /** Info muted border color */
+  InfoMuted: 'border-info-muted',
+  /** Info inverse border color */
+  InfoInverse: 'border-info-inverse',
+  /** Flask default border color */
+  FlaskDefault: 'border-flask-default',
+  /** Flask inverse border color */
+  FlaskInverse: 'border-flask-inverse',
+  /** Overlay alternative border color */
+  OverlayAlternative: 'border-overlay-alternative',
+  /** Overlay default border color */
+  OverlayDefault: 'border-overlay-default',
+  /** Overlay inverse border color */
+  OverlayInverse: 'border-overlay-inverse',
+  /** Transparent border color */
+  Transparent: 'border-transparent',
+} as const;
+export type BoxBorderColor =
+  (typeof BoxBorderColor)[keyof typeof BoxBorderColor];
+
+/**
+ * Box component shared props (ADR-0004)
+ * Platform-independent properties shared across React and React Native.
+ */
+export type BoxPropsShared = {
+  /**
+   * The flex-direction style of the component.
+   */
+  flexDirection?: BoxFlexDirection;
+  /**
+   * The flex-wrap style of the component.
+   */
+  flexWrap?: BoxFlexWrap;
+  /**
+   * The gap between the component's children.
+   * Use 0-12 for a gap of 0px-48px.
+   */
+  gap?: BoxSpacing;
+  /**
+   * The align-items style of the component.
+   */
+  alignItems?: BoxAlignItems;
+  /**
+   * The justify-content style of the component.
+   */
+  justifyContent?: BoxJustifyContent;
+  /**
+   * The margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  margin?: BoxSpacing;
+  /**
+   * The top margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  marginTop?: BoxSpacing;
+  /**
+   * The right margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  marginRight?: BoxSpacing;
+  /**
+   * The bottom margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  marginBottom?: BoxSpacing;
+  /**
+   * The left margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  marginLeft?: BoxSpacing;
+  /**
+   * The horizontal margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  marginHorizontal?: BoxSpacing;
+  /**
+   * The vertical margin of the component.
+   * Use 0-12 for margin of 0px-48px.
+   */
+  marginVertical?: BoxSpacing;
+  /**
+   * The padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  padding?: BoxSpacing;
+  /**
+   * The top padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  paddingTop?: BoxSpacing;
+  /**
+   * The right padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  paddingRight?: BoxSpacing;
+  /**
+   * The bottom padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  paddingBottom?: BoxSpacing;
+  /**
+   * The left padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  paddingLeft?: BoxSpacing;
+  /**
+   * The horizontal padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  paddingHorizontal?: BoxSpacing;
+  /**
+   * The vertical padding of the component.
+   * Use 0-12 for padding of 0px-48px.
+   */
+  paddingVertical?: BoxSpacing;
+  /**
+   * The border width of the component.
+   * Use 0, 1, 2, 4, or 8 for border width of 0px, 1px, 2px, 4px, or 8px.
+   */
+  borderWidth?: BoxBorderWidth;
+  /**
+   * The border color of the component.
+   */
+  borderColor?: BoxBorderColor;
+  /**
+   * The background color of the component.
+   */
+  backgroundColor?: BoxBackgroundColor;
+};
diff --git a/packages/design-system-shared/src/types/Box/index.ts b/packages/design-system-shared/src/types/Box/index.ts
new file mode 100644
index 000000000..7b4f9957b
--- /dev/null
+++ b/packages/design-system-shared/src/types/Box/index.ts
@@ -0,0 +1,11 @@
+export {
+  BoxFlexDirection,
+  BoxFlexWrap,
+  BoxAlignItems,
+  BoxJustifyContent,
+  BoxBackgroundColor,
+  BoxBorderColor,
+  type BoxSpacing,
+  type BoxBorderWidth,
+  type BoxPropsShared,
+} from './Box.types';

From 62e91f0706886b4d1c699084430b4bf9b8866a31 Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Sat, 11 Apr 2026 14:06:37 -0700
Subject: [PATCH 2/9] chore: lint fix

---
 .../src/components/BannerBase/BannerBase.tsx                | 6 +-----
 .../src/components/Box/Box.stories.tsx                      | 1 +
 .../src/components/BannerBase/BannerBase.tsx                | 6 +-----
 .../design-system-react/src/components/Box/Box.stories.tsx  | 1 +
 4 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx b/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx
index 55a662dc9..77a765576 100644
--- a/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx
+++ b/packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx
@@ -8,11 +8,7 @@ import {
 import React from 'react';
 import { GestureResponderEvent } from 'react-native';
 
-import {
-  ButtonIconSize,
-  ButtonSize,
-  IconName,
-} from '../../types';
+import { ButtonIconSize, ButtonSize, IconName } from '../../types';
 import { Box } from '../Box';
 import { Button } from '../Button';
 import { ButtonIcon } from '../ButtonIcon';
diff --git a/packages/design-system-react-native/src/components/Box/Box.stories.tsx b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
index 7fde07f9e..cfb85ead7 100644
--- a/packages/design-system-react-native/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
@@ -10,6 +10,7 @@ import {
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 import { ScrollView } from 'react-native';
+
 import { Text } from '../Text';
 
 import { Box } from './Box';
diff --git a/packages/design-system-react/src/components/BannerBase/BannerBase.tsx b/packages/design-system-react/src/components/BannerBase/BannerBase.tsx
index d5a47596f..e9c554820 100644
--- a/packages/design-system-react/src/components/BannerBase/BannerBase.tsx
+++ b/packages/design-system-react/src/components/BannerBase/BannerBase.tsx
@@ -7,11 +7,7 @@ import {
 } from '@metamask/design-system-shared';
 import React, { forwardRef } from 'react';
 
-import {
-  ButtonIconSize,
-  ButtonSize,
-  IconName,
-} from '../../types';
+import { ButtonIconSize, ButtonSize, IconName } from '../../types';
 import { twMerge } from '../../utils/tw-merge';
 import { Box } from '../Box';
 import { Button } from '../Button';
diff --git a/packages/design-system-react/src/components/Box/Box.stories.tsx b/packages/design-system-react/src/components/Box/Box.stories.tsx
index bd0d40a48..f422a8943 100644
--- a/packages/design-system-react/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react/src/components/Box/Box.stories.tsx
@@ -9,6 +9,7 @@ import {
 } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';
+
 import { Text } from '../Text';
 
 import { Box } from './Box';

From 5f311ae5bd6bb612b21f8795d7aa9c4bb0710a24 Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Wed, 15 Apr 2026 15:37:30 -0700
Subject: [PATCH 3/9] fix: remove stale InfoAlternative border color token

The info-alternative design token was removed from design-tokens.
Removes the stale BoxBorderColor.InfoAlternative entry and its
story usage in both React and React Native.
---
 .../src/components/Box/Box.stories.tsx                   | 9 ---------
 .../src/components/Box/Box.stories.tsx                   | 9 ---------
 packages/design-system-shared/src/types/Box/Box.types.ts | 2 --
 3 files changed, 20 deletions(-)

diff --git a/packages/design-system-react-native/src/components/Box/Box.stories.tsx b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
index cfb85ead7..24b1a0911 100644
--- a/packages/design-system-react-native/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
@@ -1025,15 +1025,6 @@ export const BorderColor: Story = {
         >
           <Text>InfoDefault</Text>
         </Box>
-        <Box
-          {...args}
-          padding={3}
-          backgroundColor={BoxBackgroundColor.InfoMuted}
-          borderColor={BoxBorderColor.InfoAlternative}
-          borderWidth={2}
-        >
-          <Text>InfoAlternative</Text>
-        </Box>
         <Box
           {...args}
           padding={3}
diff --git a/packages/design-system-react/src/components/Box/Box.stories.tsx b/packages/design-system-react/src/components/Box/Box.stories.tsx
index f422a8943..a02e1627a 100644
--- a/packages/design-system-react/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react/src/components/Box/Box.stories.tsx
@@ -1359,15 +1359,6 @@ export const BorderColor: Story = {
       >
         <Text>InfoDefault</Text>
       </Box>
-      <Box
-        {...args}
-        padding={3}
-        backgroundColor={BoxBackgroundColor.InfoMuted}
-        borderColor={BoxBorderColor.InfoAlternative}
-        borderWidth={2}
-      >
-        <Text>InfoAlternative</Text>
-      </Box>
       <Box
         {...args}
         padding={3}
diff --git a/packages/design-system-shared/src/types/Box/Box.types.ts b/packages/design-system-shared/src/types/Box/Box.types.ts
index 13945171a..83b453d12 100644
--- a/packages/design-system-shared/src/types/Box/Box.types.ts
+++ b/packages/design-system-shared/src/types/Box/Box.types.ts
@@ -174,8 +174,6 @@ export const BoxBorderColor = {
   SuccessInverse: 'border-success-inverse',
   /** Info default border color */
   InfoDefault: 'border-info-default',
-  /** Info alternative border color */
-  InfoAlternative: 'border-info-alternative',
   /** Info muted border color */
   InfoMuted: 'border-info-muted',
   /** Info inverse border color */

From dd92e86c122560d16fca1a5a9d357e74c5f7bd0f Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Wed, 15 Apr 2026 15:42:34 -0700
Subject: [PATCH 4/9] fix: remove stale WarningAlternative and
 SuccessAlternative color tokens

These tokens were removed from design-tokens in v4.0.0. Removes stale
entries from BoxBackgroundColor and BoxBorderColor, and their story usage.
---
 .../src/components/Box/Box.stories.tsx        | 36 -------------------
 .../src/components/Box/Box.stories.tsx        | 36 -------------------
 .../src/types/Box/Box.types.ts                |  8 -----
 3 files changed, 80 deletions(-)

diff --git a/packages/design-system-react-native/src/components/Box/Box.stories.tsx b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
index 24b1a0911..0d8ec2369 100644
--- a/packages/design-system-react-native/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react-native/src/components/Box/Box.stories.tsx
@@ -949,15 +949,6 @@ export const BorderColor: Story = {
         >
           <Text>WarningDefault</Text>
         </Box>
-        <Box
-          {...args}
-          padding={3}
-          backgroundColor={BoxBackgroundColor.WarningMuted}
-          borderColor={BoxBorderColor.WarningAlternative}
-          borderWidth={2}
-        >
-          <Text>WarningAlternative</Text>
-        </Box>
         <Box
           {...args}
           padding={3}
@@ -987,15 +978,6 @@ export const BorderColor: Story = {
         >
           <Text>SuccessDefault</Text>
         </Box>
-        <Box
-          {...args}
-          padding={3}
-          backgroundColor={BoxBackgroundColor.SuccessMuted}
-          borderColor={BoxBorderColor.SuccessAlternative}
-          borderWidth={2}
-        >
-          <Text>SuccessAlternative</Text>
-        </Box>
         <Box
           {...args}
           padding={3}
@@ -1254,15 +1236,6 @@ export const BackgroundColor: Story = {
         >
           <Text>WarningDefault</Text>
         </Box>
-        <Box
-          {...args}
-          padding={3}
-          backgroundColor={BoxBackgroundColor.WarningAlternative}
-          borderColor={BoxBorderColor.WarningDefault}
-          borderWidth={1}
-        >
-          <Text>WarningAlternative</Text>
-        </Box>
         <Box
           {...args}
           padding={3}
@@ -1292,15 +1265,6 @@ export const BackgroundColor: Story = {
         >
           <Text>SuccessDefault</Text>
         </Box>
-        <Box
-          {...args}
-          padding={3}
-          backgroundColor={BoxBackgroundColor.SuccessAlternative}
-          borderColor={BoxBorderColor.SuccessDefault}
-          borderWidth={1}
-        >
-          <Text>SuccessAlternative</Text>
-        </Box>
         <Box
           {...args}
           padding={3}
diff --git a/packages/design-system-react/src/components/Box/Box.stories.tsx b/packages/design-system-react/src/components/Box/Box.stories.tsx
index a02e1627a..c11b4b256 100644
--- a/packages/design-system-react/src/components/Box/Box.stories.tsx
+++ b/packages/design-system-react/src/components/Box/Box.stories.tsx
@@ -1283,15 +1283,6 @@ export const BorderColor: Story = {
       >
         <Text>WarningDefault</Text>
       </Box>
-      <Box
-        {...args}
-        padding={3}
-        backgroundColor={BoxBackgroundColor.WarningMuted}
-        borderColor={BoxBorderColor.WarningAlternative}
-        borderWidth={2}
-      >
-        <Text>WarningAlternative</Text>
-      </Box>
       <Box
         {...args}
         padding={3}
@@ -1321,15 +1312,6 @@ export const BorderColor: Story = {
       >
         <Text>SuccessDefault</Text>
       </Box>
-      <Box
-        {...args}
-        padding={3}
-        backgroundColor={BoxBackgroundColor.SuccessMuted}
-        borderColor={BoxBorderColor.SuccessAlternative}
-        borderWidth={2}
-      >
-        <Text>SuccessAlternative</Text>
-      </Box>
       <Box
         {...args}
         padding={3}
@@ -1642,15 +1624,6 @@ export const BackgroundColor: Story = {
       >
         <Text>WarningDefault</Text>
       </Box>
-      <Box
-        {...args}
-        padding={3}
-        backgroundColor={BoxBackgroundColor.WarningAlternative}
-        borderColor={BoxBorderColor.WarningDefault}
-        borderWidth={1}
-      >
-        <Text>WarningAlternative</Text>
-      </Box>
       <Box
         {...args}
         padding={3}
@@ -1680,15 +1653,6 @@ export const BackgroundColor: Story = {
       >
         <Text>SuccessDefault</Text>
       </Box>
-      <Box
-        {...args}
-        padding={3}
-        backgroundColor={BoxBackgroundColor.SuccessAlternative}
-        borderColor={BoxBorderColor.SuccessDefault}
-        borderWidth={1}
-      >
-        <Text>SuccessAlternative</Text>
-      </Box>
       <Box
         {...args}
         padding={3}
diff --git a/packages/design-system-shared/src/types/Box/Box.types.ts b/packages/design-system-shared/src/types/Box/Box.types.ts
index 83b453d12..b46389eda 100644
--- a/packages/design-system-shared/src/types/Box/Box.types.ts
+++ b/packages/design-system-shared/src/types/Box/Box.types.ts
@@ -93,16 +93,12 @@ export const BoxBackgroundColor = {
   ErrorInverse: 'bg-error-inverse',
   /** Warning default background color */
   WarningDefault: 'bg-warning-default',
-  /** Warning alternative background color */
-  WarningAlternative: 'bg-warning-alternative',
   /** Warning muted background color */
   WarningMuted: 'bg-warning-muted',
   /** Warning inverse background color */
   WarningInverse: 'bg-warning-inverse',
   /** Success default background color */
   SuccessDefault: 'bg-success-default',
-  /** Success alternative background color */
-  SuccessAlternative: 'bg-success-alternative',
   /** Success muted background color */
   SuccessMuted: 'bg-success-muted',
   /** Success inverse background color */
@@ -158,16 +154,12 @@ export const BoxBorderColor = {
   ErrorInverse: 'border-error-inverse',
   /** Warning default border color */
   WarningDefault: 'border-warning-default',
-  /** Warning alternative border color */
-  WarningAlternative: 'border-warning-alternative',
   /** Warning muted border color */
   WarningMuted: 'border-warning-muted',
   /** Warning inverse border color */
   WarningInverse: 'border-warning-inverse',
   /** Success default border color */
   SuccessDefault: 'border-success-default',
-  /** Success alternative border color */
-  SuccessAlternative: 'border-success-alternative',
   /** Success muted border color */
   SuccessMuted: 'border-success-muted',
   /** Success inverse border color */

From 86c80bd910fb30885704796e735fffcee61de18e Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Wed, 15 Apr 2026 15:45:38 -0700
Subject: [PATCH 5/9] docs: add Box migration docs for type imports and stale
 token removal

Documents in all three MIGRATION.md files:
- Box types now sourced from @metamask/design-system-shared
- Removed stale -alternative color tokens (warning, success, info)
---
 .../design-system-react-native/MIGRATION.md   | 24 +++++++++++
 packages/design-system-react/MIGRATION.md     | 29 +++++++++++++
 packages/design-system-shared/MIGRATION.md    | 41 +++++++++++++++++++
 3 files changed, 94 insertions(+)

diff --git a/packages/design-system-react-native/MIGRATION.md b/packages/design-system-react-native/MIGRATION.md
index 9d48e84a9..1aa8731a1 100644
--- a/packages/design-system-react-native/MIGRATION.md
+++ b/packages/design-system-react-native/MIGRATION.md
@@ -99,6 +99,30 @@ If TypeScript now flags props you were previously passing to `Icon`, those props
 </View>
 ```
 
+#### Box: Type imports moved to `@metamask/design-system-shared`
+
+`BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, and `BoxBorderWidth` are now defined in `@metamask/design-system-shared` and re-exported from `@metamask/design-system-react-native`. All existing import paths through `@metamask/design-system-react-native` continue to work without change.
+
+```tsx
+// Both of these work — shared is the source of truth
+import { BoxBackgroundColor } from '@metamask/design-system-react-native';
+import { BoxBackgroundColor } from '@metamask/design-system-shared';
+```
+
+#### Box: Removed stale `-alternative` color tokens
+
+The following `BoxBackgroundColor` and `BoxBorderColor` entries have been removed. These tokens were removed from `@metamask/design-tokens` in v4.0.0 but were incorrectly carried over into the Box const objects:
+
+| Removed Entry                           | Replacement                         |
+| --------------------------------------- | ----------------------------------- |
+| `BoxBackgroundColor.WarningAlternative` | `BoxBackgroundColor.WarningDefault` |
+| `BoxBackgroundColor.SuccessAlternative` | `BoxBackgroundColor.SuccessDefault` |
+| `BoxBorderColor.WarningAlternative`     | `BoxBorderColor.WarningDefault`     |
+| `BoxBorderColor.SuccessAlternative`     | `BoxBorderColor.SuccessDefault`     |
+| `BoxBorderColor.InfoAlternative`        | `BoxBorderColor.InfoDefault`        |
+
+These tokens had no backing CSS custom property, so any usage was already producing no visible style. Replace with `-default` or `-muted` as appropriate.
+
 ---
 
 ### From version 0.16.0 to 0.17.0
diff --git a/packages/design-system-react/MIGRATION.md b/packages/design-system-react/MIGRATION.md
index bbb735b76..386ab4d62 100644
--- a/packages/design-system-react/MIGRATION.md
+++ b/packages/design-system-react/MIGRATION.md
@@ -14,6 +14,7 @@ This guide provides detailed instructions for migrating your project from one ve
   - [Icon Component](#icon-component)
   - [Checkbox Component](#checkbox-component)
 - [Version Updates](#version-updates)
+  - [From version 0.17.0 to 0.18.0](#from-version-0170-to-0180)
   - [From version 0.16.0 to 0.17.0](#from-version-0160-to-0170)
   - [From version 0.12.0 to 0.13.0](#from-version-0120-to-0130)
   - [From version 0.10.0 to 0.11.0](#from-version-0100-to-0110)
@@ -670,6 +671,34 @@ import { Checkbox } from '@metamask/design-system-react';
 
 This section covers version-to-version breaking changes within `@metamask/design-system-react`.
 
+## From version 0.17.0 to 0.18.0
+
+### Box: Type imports moved to `@metamask/design-system-shared`
+
+`BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, and `BoxBorderWidth` are now defined in `@metamask/design-system-shared` and re-exported from `@metamask/design-system-react`. All existing import paths through `@metamask/design-system-react` continue to work without change.
+
+```tsx
+// Both of these work — shared is the source of truth
+import { BoxBackgroundColor } from '@metamask/design-system-react';
+import { BoxBackgroundColor } from '@metamask/design-system-shared';
+```
+
+### Box: Removed stale `-alternative` color tokens
+
+The following `BoxBackgroundColor` and `BoxBorderColor` entries have been removed. These tokens were removed from `@metamask/design-tokens` in v4.0.0 but were incorrectly carried over into the Box const objects:
+
+| Removed Entry                           | Replacement                            |
+| --------------------------------------- | -------------------------------------- |
+| `BoxBackgroundColor.WarningAlternative` | `BoxBackgroundColor.WarningDefault`    |
+| `BoxBackgroundColor.SuccessAlternative` | `BoxBackgroundColor.SuccessDefault`    |
+| `BoxBorderColor.WarningAlternative`     | `BoxBorderColor.WarningDefault`        |
+| `BoxBorderColor.SuccessAlternative`     | `BoxBorderColor.SuccessDefault`        |
+| `BoxBorderColor.InfoAlternative`        | `BoxBorderColor.InfoDefault`           |
+
+These tokens had no backing CSS custom property, so any usage was already producing no visible style. Replace with `-default` or `-muted` as appropriate.
+
+---
+
 ## From version 0.16.0 to 0.17.0
 
 ### Text: Typography const values moved to `@metamask/design-system-shared`
diff --git a/packages/design-system-shared/MIGRATION.md b/packages/design-system-shared/MIGRATION.md
index beafbbc5a..cdc414fc5 100644
--- a/packages/design-system-shared/MIGRATION.md
+++ b/packages/design-system-shared/MIGRATION.md
@@ -11,6 +11,47 @@ This guide provides detailed instructions for migrating your project from one ve
 
 ### From version 0.11.0 to 0.12.0
 
+#### Removed: Stale `BoxBackgroundColor` and `BoxBorderColor` `-alternative` tokens
+
+**What Changed:**
+
+The following `BoxBackgroundColor` and `BoxBorderColor` entries have been removed. These tokens were removed from `@metamask/design-tokens` in v4.0.0 but were incorrectly carried over into the Box const objects:
+
+| Removed Entry                            | Reason                                          |
+| ---------------------------------------- | ----------------------------------------------- |
+| `BoxBackgroundColor.WarningAlternative`  | `--color-warning-alternative` removed in v4.0.0 |
+| `BoxBackgroundColor.SuccessAlternative`  | `--color-success-alternative` removed in v4.0.0 |
+| `BoxBorderColor.WarningAlternative`      | `--color-warning-alternative` removed in v4.0.0 |
+| `BoxBorderColor.SuccessAlternative`      | `--color-success-alternative` removed in v4.0.0 |
+| `BoxBorderColor.InfoAlternative`         | `--color-info-alternative` removed in v4.0.0    |
+
+**Migration:**
+
+These tokens had no backing CSS custom property, so any usage was already producing no visible style. Remove references and use the corresponding `-default` or `-muted` token instead:
+
+```tsx
+// Before (0.11.0)
+<Box backgroundColor={BoxBackgroundColor.WarningAlternative} />
+<Box backgroundColor={BoxBackgroundColor.SuccessAlternative} />
+<Box borderColor={BoxBorderColor.WarningAlternative} />
+<Box borderColor={BoxBorderColor.SuccessAlternative} />
+<Box borderColor={BoxBorderColor.InfoAlternative} />
+
+// After (0.12.0) — use -default or -muted as appropriate
+<Box backgroundColor={BoxBackgroundColor.WarningDefault} />
+<Box backgroundColor={BoxBackgroundColor.SuccessDefault} />
+<Box borderColor={BoxBorderColor.WarningDefault} />
+<Box borderColor={BoxBorderColor.SuccessDefault} />
+<Box borderColor={BoxBorderColor.InfoDefault} />
+```
+
+**Impact:**
+
+- Any reference to the removed entries will produce a TypeScript error after upgrading.
+- No visual regression — the removed tokens had no backing design token since `@metamask/design-tokens` v4.0.0.
+
+---
+
 #### Removed: `isReactNodeRenderable` utility
 
 **What Changed:**

From 06c8ae34b67a76a28ff0d2914c9b796baf831422 Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Wed, 15 Apr 2026 15:46:12 -0700
Subject: [PATCH 6/9] chore: fix prettier formatting

---
 packages/design-system-react/MIGRATION.md  | 14 +++++++-------
 packages/design-system-shared/MIGRATION.md | 14 +++++++-------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/packages/design-system-react/MIGRATION.md b/packages/design-system-react/MIGRATION.md
index 386ab4d62..5126f8a19 100644
--- a/packages/design-system-react/MIGRATION.md
+++ b/packages/design-system-react/MIGRATION.md
@@ -687,13 +687,13 @@ import { BoxBackgroundColor } from '@metamask/design-system-shared';
 
 The following `BoxBackgroundColor` and `BoxBorderColor` entries have been removed. These tokens were removed from `@metamask/design-tokens` in v4.0.0 but were incorrectly carried over into the Box const objects:
 
-| Removed Entry                           | Replacement                            |
-| --------------------------------------- | -------------------------------------- |
-| `BoxBackgroundColor.WarningAlternative` | `BoxBackgroundColor.WarningDefault`    |
-| `BoxBackgroundColor.SuccessAlternative` | `BoxBackgroundColor.SuccessDefault`    |
-| `BoxBorderColor.WarningAlternative`     | `BoxBorderColor.WarningDefault`        |
-| `BoxBorderColor.SuccessAlternative`     | `BoxBorderColor.SuccessDefault`        |
-| `BoxBorderColor.InfoAlternative`        | `BoxBorderColor.InfoDefault`           |
+| Removed Entry                           | Replacement                         |
+| --------------------------------------- | ----------------------------------- |
+| `BoxBackgroundColor.WarningAlternative` | `BoxBackgroundColor.WarningDefault` |
+| `BoxBackgroundColor.SuccessAlternative` | `BoxBackgroundColor.SuccessDefault` |
+| `BoxBorderColor.WarningAlternative`     | `BoxBorderColor.WarningDefault`     |
+| `BoxBorderColor.SuccessAlternative`     | `BoxBorderColor.SuccessDefault`     |
+| `BoxBorderColor.InfoAlternative`        | `BoxBorderColor.InfoDefault`        |
 
 These tokens had no backing CSS custom property, so any usage was already producing no visible style. Replace with `-default` or `-muted` as appropriate.
 
diff --git a/packages/design-system-shared/MIGRATION.md b/packages/design-system-shared/MIGRATION.md
index cdc414fc5..5720ae816 100644
--- a/packages/design-system-shared/MIGRATION.md
+++ b/packages/design-system-shared/MIGRATION.md
@@ -17,13 +17,13 @@ This guide provides detailed instructions for migrating your project from one ve
 
 The following `BoxBackgroundColor` and `BoxBorderColor` entries have been removed. These tokens were removed from `@metamask/design-tokens` in v4.0.0 but were incorrectly carried over into the Box const objects:
 
-| Removed Entry                            | Reason                                          |
-| ---------------------------------------- | ----------------------------------------------- |
-| `BoxBackgroundColor.WarningAlternative`  | `--color-warning-alternative` removed in v4.0.0 |
-| `BoxBackgroundColor.SuccessAlternative`  | `--color-success-alternative` removed in v4.0.0 |
-| `BoxBorderColor.WarningAlternative`      | `--color-warning-alternative` removed in v4.0.0 |
-| `BoxBorderColor.SuccessAlternative`      | `--color-success-alternative` removed in v4.0.0 |
-| `BoxBorderColor.InfoAlternative`         | `--color-info-alternative` removed in v4.0.0    |
+| Removed Entry                           | Reason                                          |
+| --------------------------------------- | ----------------------------------------------- |
+| `BoxBackgroundColor.WarningAlternative` | `--color-warning-alternative` removed in v4.0.0 |
+| `BoxBackgroundColor.SuccessAlternative` | `--color-success-alternative` removed in v4.0.0 |
+| `BoxBorderColor.WarningAlternative`     | `--color-warning-alternative` removed in v4.0.0 |
+| `BoxBorderColor.SuccessAlternative`     | `--color-success-alternative` removed in v4.0.0 |
+| `BoxBorderColor.InfoAlternative`        | `--color-info-alternative` removed in v4.0.0    |
 
 **Migration:**
 

From e68b4b06c02539b825c214e6d39bdf55fa3b2318 Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Thu, 16 Apr 2026 17:29:01 -0700
Subject: [PATCH 7/9] fix(react): re-export BoxBorderWidth from barrel

---
 packages/design-system-react/src/components/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/design-system-react/src/components/index.ts b/packages/design-system-react/src/components/index.ts
index 2f6496818..962f7a8ed 100644
--- a/packages/design-system-react/src/components/index.ts
+++ b/packages/design-system-react/src/components/index.ts
@@ -64,7 +64,7 @@ export {
   BoxBorderColor,
   Box,
 } from './Box';
-export type { BoxSpacing, BoxProps } from './Box';
+export type { BoxSpacing, BoxProps, BoxBorderWidth } from './Box';
 
 export { Button, ButtonSize, ButtonVariant } from './Button';
 export type { ButtonProps } from './Button';

From 9a6f3fcd4569909cf9111ebcd1221b20da3bc36f Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Thu, 16 Apr 2026 18:01:43 -0700
Subject: [PATCH 8/9] fix(rn): update Box story imports after shared type
 migration

---
 .../src/components/HeaderSearch/HeaderSearch.stories.tsx    | 3 ++-
 .../components/KeyValueColumn/KeyValueColumn.stories.tsx    | 2 +-
 .../src/components/KeyValueRow/KeyValueRow.stories.tsx      | 6 ++++--
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/design-system-react-native/src/components/HeaderSearch/HeaderSearch.stories.tsx b/packages/design-system-react-native/src/components/HeaderSearch/HeaderSearch.stories.tsx
index 55c23dcb2..a71e1d090 100644
--- a/packages/design-system-react-native/src/components/HeaderSearch/HeaderSearch.stories.tsx
+++ b/packages/design-system-react-native/src/components/HeaderSearch/HeaderSearch.stories.tsx
@@ -1,7 +1,8 @@
+import { BoxFlexDirection } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React, { useState } from 'react';
 
-import { BoxFlexDirection, TextVariant } from '../../types';
+import { TextVariant } from '../../types';
 import { Box } from '../Box';
 import { Text } from '../Text';
 
diff --git a/packages/design-system-react-native/src/components/KeyValueColumn/KeyValueColumn.stories.tsx b/packages/design-system-react-native/src/components/KeyValueColumn/KeyValueColumn.stories.tsx
index 84841f97a..46d8f9f60 100644
--- a/packages/design-system-react-native/src/components/KeyValueColumn/KeyValueColumn.stories.tsx
+++ b/packages/design-system-react-native/src/components/KeyValueColumn/KeyValueColumn.stories.tsx
@@ -1,7 +1,7 @@
+import { BoxFlexDirection } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 
-import { BoxFlexDirection } from '../../types';
 import { AvatarAccount, AvatarAccountSize } from '../AvatarAccount';
 import { AvatarToken, AvatarTokenSize } from '../AvatarToken';
 import { SAMPLE_AVATARTOKEN_URIS } from '../AvatarToken/AvatarToken.dev';
diff --git a/packages/design-system-react-native/src/components/KeyValueRow/KeyValueRow.stories.tsx b/packages/design-system-react-native/src/components/KeyValueRow/KeyValueRow.stories.tsx
index cffd63715..1e1756aa8 100644
--- a/packages/design-system-react-native/src/components/KeyValueRow/KeyValueRow.stories.tsx
+++ b/packages/design-system-react-native/src/components/KeyValueRow/KeyValueRow.stories.tsx
@@ -1,8 +1,10 @@
-import { KeyValueRowVariant } from '@metamask/design-system-shared';
+import {
+  BoxFlexDirection,
+  KeyValueRowVariant,
+} from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 
-import { BoxFlexDirection } from '../../types';
 import { AvatarAccount, AvatarAccountSize } from '../AvatarAccount';
 import { AvatarToken, AvatarTokenSize } from '../AvatarToken';
 import { SAMPLE_AVATARTOKEN_URIS } from '../AvatarToken/AvatarToken.dev';

From c2ba5409b29cbccaf405fcd881fd19e2ccf88ae9 Mon Sep 17 00:00:00 2001
From: georgewrmarshall <george.marshall@consensys.net>
Date: Tue, 21 Apr 2026 12:37:00 -0700
Subject: [PATCH 9/9] fix(rn): import Tag Box color from shared

---
 .../src/components/Tag/Tag.constants.ts                   | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/design-system-react-native/src/components/Tag/Tag.constants.ts b/packages/design-system-react-native/src/components/Tag/Tag.constants.ts
index 2e4606ce9..aaa1af396 100644
--- a/packages/design-system-react-native/src/components/Tag/Tag.constants.ts
+++ b/packages/design-system-react-native/src/components/Tag/Tag.constants.ts
@@ -1,6 +1,10 @@
-import { TagSeverity, TextColor } from '@metamask/design-system-shared';
+import {
+  BoxBackgroundColor,
+  TagSeverity,
+  TextColor,
+} from '@metamask/design-system-shared';
 
-import { BoxBackgroundColor, IconColor } from '../../types';
+import { IconColor } from '../../types';
 
 export const MAP_TAG_SEVERITY_BACKGROUND: Record<
   TagSeverity,