Skip to content

chore: [DSYS-616] create/update Box migration docs #1092

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cursor wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

chore: [DSYS-616] create/update Box migration docs #1092

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 68 additions & 53 deletions packages/design-system-react-native/MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1229,87 +1229,102 @@ The DS `BottomSheetFooter` adds `twClassName` for Tailwind utility class overrid

### Box Component

The Box component has breaking changes when migrating from the mobile component-library. For custom spacing patterns or values outside the BoxSpacing range, use Tailwind classes via `twClassName`.
The Box component has breaking changes when migrating from mobile legacy Box implementations to `@metamask/design-system-react-native`.

Source audit notes:

- No `app/component-library/components/Box` path was found on `main` during this run.
- The current mobile legacy Box source is `app/components/UI/Box/Box.tsx` and `app/components/UI/Box/box.types.ts`.

#### Breaking Changes

##### Spacing Values
##### Prop Surface Changes

The design system Box uses `BoxSpacing` values (0-12 for 0px-48px). For custom spacing values outside this range or responsive spacing patterns, use Tailwind classes via `twClassName`.
Legacy mobile `Box` (`app/components/UI/Box`) is a smaller API focused on layout primitives (`display`, `flexDirection`, `justifyContent`, `alignItems`, `textAlign`, `gap`, `color`, `backgroundColor`) plus `style` from `ViewProps`. MMDS RN `Box` is spacing/token focused and uses Tailwind class utilities under the hood.

| Mobile Pattern | Design System Migration |
| -------------------------------- | ----------------------------------------- |
| Custom margin/padding values | Use `twClassName` with Tailwind utilities |
| Responsive spacing | Use `twClassName="m-2 md:m-4"` |
| Auto margins | Use `twClassName="m-auto"` |
| Custom margin/padding with style | Use `twClassName` instead of `style` prop |
| Legacy Mobile Prop | MMDS RN Migration |
| ------------------ | ----------------- |
| `display` | Use `twClassName`, for example `twClassName="hidden"` |
| `textAlign` | Apply text alignment on child text components |
| `color` | Apply text/icon color on child components |
| `backgroundColor?: string` | Use `backgroundColor={BoxBackgroundColor.*}` token values |
| `gap?: number` | Use `gap?: BoxSpacing` (`0..12`) |

##### Margin Inline Props
##### Newly Available Spacing Props

If the mobile Box had `marginInline`, `marginInlineStart`, or `marginInlineEnd` props, the design system Box uses `marginHorizontal` or Tailwind classes instead.
Legacy mobile `Box` does not expose dedicated spacing props like `margin`, `padding`, `marginHorizontal`, etc. MMDS RN `Box` adds these.

| Mobile Pattern | Design System Migration |
| ----------------------- | ---------------------------------------------- |
| `marginInline={4}` | `marginHorizontal={4}` or `twClassName="mx-4"` |
| `marginInlineStart={2}` | `twClassName="ms-2"` |
| `marginInlineEnd={2}` | `twClassName="me-2"` |
| MMDS RN Added Prop Group |
| ------------------------ |
| `margin`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft` |
| `marginHorizontal`, `marginVertical` |
| `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` |
| `paddingHorizontal`, `paddingVertical` |
| `borderWidth`, `borderColor` |

##### Padding Inline Props
##### Type and Value Changes

If the mobile Box had `paddingInline`, `paddingInlineStart`, or `paddingInlineEnd` props, the design system Box uses `paddingHorizontal` or Tailwind classes instead.
| Legacy Mobile Type | MMDS RN Type | Notes |
| ------------------ | ------------ | ----- |
| `backgroundColor?: string` | `backgroundColor?: BoxBackgroundColor` | tokenized values only |
| `gap?: number` | `gap?: BoxSpacing` (`0..12`) | constrained spacing scale |
| `style`-driven spacing values | prop-based `BoxSpacing` or `twClassName` | prefer explicit spacing props for token alignment |

| Mobile Pattern | Design System Migration |
| ------------------------ | ----------------------------------------------- |
| `paddingInline={4}` | `paddingHorizontal={4}` or `twClassName="px-4"` |
| `paddingInlineStart={2}` | `twClassName="ps-2"` |
| `paddingInlineEnd={2}` | `twClassName="pe-2"` |
##### Default / Behavior Notes

#### Migration Examples
| Area | Legacy Mobile Box (`app/components/UI/Box`) | MMDS RN Box |
| ---- | -------------------------------------------- | ----------- |
| Container render behavior | Always renders `View` | Always renders `View` |
| Flex behavior when no props provided | No explicit base flex class | Adds base `flex` class by default |
| Spacing strategy | typically `style` object | `BoxSpacing` props and `twClassName` |
| Border behavior | style-driven | explicit `borderWidth` + `borderColor` props |

#### Migration Example

##### Before (Mobile)

```tsx
import { Box } from '../../../component-library/components/Box';

// Custom spacing with style prop
<Box style={{ margin: 20, padding: 20 }}>
Custom spacing
</Box>
import { Box, Display, FlexDirection } from '../../../components/UI/Box/Box';

// Inline props (if they existed)
<Box marginInline={4} paddingInlineStart={2}>
Inline spacing
<Box
display={Display.Block}
flexDirection={FlexDirection.Row}
gap={6}
backgroundColor="background-default"
style={{ marginHorizontal: 20, paddingVertical: 12 }}
>
Legacy mobile layout
</Box>
```

##### After (Design System)

```tsx
import { Box } from '@metamask/design-system-react-native';

// Custom spacing - use twClassName for values outside BoxSpacing range
<Box twClassName="m-5 p-5">
Custom spacing
</Box>
import {
Box,
BoxBackgroundColor,
BoxFlexDirection,
} from '@metamask/design-system-react-native';

// Inline props - use marginHorizontal or twClassName
<Box marginHorizontal={4} twClassName="ps-2">
Inline spacing
<Box
flexDirection={BoxFlexDirection.Row}
gap={6}
backgroundColor={BoxBackgroundColor.BackgroundDefault}
marginHorizontal={5}
paddingVertical={3}
>
MMDS mobile layout
</Box>
```

#### Spacing Props Available

The design system Box provides these margin/padding props:

- ✅ `margin`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`
- ✅ `marginHorizontal`
- ✅ `marginVertical`
- ✅ `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`
- ✅ `paddingHorizontal`
- ✅ `paddingVertical`
#### Quick Mapping Summary

For spacing values 0-12 (0px-48px), use these props. For custom values, responsive spacing, or inline-start/end positioning, use `twClassName` with Tailwind utilities.
| Category | Legacy Mobile Box | MMDS RN Box |
| -------- | ----------------- | ----------- |
| Removed or moved usage | `display`, `textAlign`, `color` on container | move to `twClassName`/child components |
| Type changes | freeform `string` background / numeric `gap` | tokenized background + `BoxSpacing` gap |
| Newly available | no dedicated spacing props | full margin/padding/border prop set |
| Behavior notes | no default flex class | base `flex` class applied |

### BannerAlert Component

Expand Down
4 changes: 4 additions & 0 deletions packages/design-system-react-native/src/components/Box/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,10 @@ export const StyleExample = () => (
);
```

## Migration Guide

Migrating from a legacy Box in MetaMask Mobile? See the [Box Migration Guide](../../MIGRATION.md#box-component) for source-audited API mappings, breaking changes, and before/after examples.

## References

[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)
146 changes: 81 additions & 65 deletions packages/design-system-react/MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,105 +141,121 @@ The design system Button adds these props:

### Box Component

The Box component has breaking changes when migrating from the extension component-library, particularly around responsive spacing and certain margin/padding props.
The Box component has breaking changes when migrating from extension `ui/components/component-library/box` to `@metamask/design-system-react`.

#### Breaking Changes

##### Responsive Spacing
##### Prop Surface Reduction (Removed Props)

The extension Box supported responsive arrays for margin and padding props. The design system Box does not support this pattern. Use Tailwind responsive classes via `className` instead.
The legacy extension Box exposed broad style utility props that are not on MMDS `Box`.

| Extension Pattern | Design System Migration |
| ------------------------------------------ | ----------------------------------------------- |
| `margin={[2, 4]}` | `margin={2} className="md:m-4"` |
| `padding={[2, 4, 6]}` | `padding={2} className="md:p-4 lg:p-6"` |
| `marginTop={[1, 2]}` | `marginTop={1} className="md:mt-2"` |
| Responsive spacing at multiple breakpoints | Use Tailwind responsive prefixes in `className` |
| Legacy Extension Prop | MMDS Migration |
| --------------------- | -------------- |
| `as` (polymorphic element) | `asChild` plus explicit child element |
| `display` | `className`, for example `className="inline-flex"` |
| `textAlign` | `className`, for example `className="text-center"` |
| `width`, `minWidth`, `height` | `className`, for example `className="w-1/2 min-w-40 h-10"` |
| `color` | Apply color on text/icon children (or utility classes on descendants), not on container `Box` |
| `borderRadius`, `borderStyle` | `className`, for example `className="rounded-md border-dashed"` |

##### Margin Inline Props
##### Responsive Array Values Removed

The extension Box had `marginInline`, `marginInlineStart`, and `marginInlineEnd` props. The design system Box uses `marginHorizontal` or Tailwind classes instead.
Legacy extension `Box` accepted responsive arrays (for example `[base, sm, md, lg]`) for many props. MMDS `Box` does not.

| Extension Pattern | Design System Migration |
| ----------------------- | -------------------------------------------- |
| `marginInline={4}` | `marginHorizontal={4}` or `className="mx-4"` |
| `marginInlineStart={2}` | `className="ms-2"` |
| `marginInlineEnd={2}` | `className="me-2"` |
| Legacy Pattern | MMDS Migration |
| -------------- | -------------- |
| `margin={[2, 4]}` | `margin={2} className="sm:m-4"` |
| `padding={[2, 4, 6]}` | `padding={2} className="sm:p-4 md:p-6"` |
| `alignItems={[AlignItems.flexStart, AlignItems.center]}` | `alignItems={BoxAlignItems.Start} className="sm:items-center"` |
| `flexDirection={[FlexDirection.Row, FlexDirection.Column]}` | `flexDirection={BoxFlexDirection.Row} className="sm:flex-col"` |

##### Padding Inline Props
##### Renamed Inline Spacing Props

The extension Box had `paddingInline`, `paddingInlineStart`, and `paddingInlineEnd` props. The design system Box uses `paddingHorizontal` or Tailwind classes instead.
Legacy inline spacing props were removed/renamed in MMDS.

| Extension Pattern | Design System Migration |
| ------------------------ | --------------------------------------------- |
| `paddingInline={4}` | `paddingHorizontal={4}` or `className="px-4"` |
| `paddingInlineStart={2}` | `className="ps-2"` |
| `paddingInlineEnd={2}` | `className="pe-2"` |
| Legacy Extension Prop | MMDS Migration |
| --------------------- | -------------- |
| `marginInline` | `marginHorizontal` or `className="mx-*"` |
| `paddingInline` | `paddingHorizontal` or `className="px-*"` |
| `marginInlineStart`, `marginInlineEnd` | `className="ms-*"` / `className="me-*"` |
| `paddingInlineStart`, `paddingInlineEnd` | `className="ps-*"` / `className="pe-*"` |

##### Margin Auto
##### Spacing Type/Value Changes

The extension Box supported `margin="auto"`. The design system Box does not support this value. Use Tailwind classes instead.
Spacing value types changed in MMDS:

| Extension Pattern | Design System Migration |
| ----------------- | ----------------------- |
| `margin="auto"` | `className="m-auto"` |
| Legacy Type/Value | MMDS Type/Value | Migration |
| ----------------- | --------------- | --------- |
| `margin`, `marginTop`, etc. allow `'auto'` | `BoxSpacing` only (`0..12`) | Use `className="m-auto"`, `className="mt-auto"`, etc. |
| spacing props allow `null` | `null` not supported | Remove `null` and omit the prop |
| `borderWidth` supports `0..12` | `BoxBorderWidth` is `0 | 1 | 2 | 4 | 8` | Use nearest MMDS value or `className` for custom width |

##### Border Behavior Change

Legacy extension `Box` auto-added a visible border in some cases (`borderStyle` defaults and implicit width when only `borderColor` was set). MMDS `Box` does not infer this behavior.

| Legacy Behavior | MMDS Behavior | Migration |
| --------------- | ------------- | --------- |
| `borderColor` alone could still render a border via helper logic | `borderColor` alone does not set border width | Set both, for example `borderColor={BoxBorderColor.BorderDefault}` and `borderWidth={1}` |

#### Migration Examples

##### Before (Extension)

```tsx
import { Box } from '../../component-library';

// Responsive spacing
<Box margin={[2, 4]} padding={[2, 4]}>
import { Box, AlignItems, FlexDirection } from '../../component-library/box';

<Box
as="section"
margin={[2, 4]}
paddingInline={3}
marginInlineStart={2}
width="1/2"
borderColor="border-muted"
borderWidth={3}
flexDirection={[FlexDirection.Row, FlexDirection.Column]}
alignItems={[AlignItems.flexStart, AlignItems.center]}
>
Responsive spacing
</Box>

// Inline props
<Box marginInline={4} paddingInlineStart={2}>
Inline spacing
</Box>

// Auto margin
<Box margin="auto">
Centered with auto margin
</Box>
```

##### After (Design System)

```tsx
import { Box } from '@metamask/design-system-react';
import {
Box,
BoxAlignItems,
BoxBorderColor,
BoxFlexDirection,
} from '@metamask/design-system-react';

// Responsive spacing - use className for responsive values
<Box margin={2} padding={2} className="md:m-4 md:p-4">
<Box
asChild
margin={2}
paddingHorizontal={3}
className="sm:m-4 ms-2 w-1/2"
borderColor={BoxBorderColor.BorderMuted}
borderWidth={2}
flexDirection={BoxFlexDirection.Row}
alignItems={BoxAlignItems.Start}
>
<section className="sm:flex-col sm:items-center">
Responsive spacing
</Box>

// Inline props - use marginHorizontal or className
<Box marginHorizontal={4} className="ps-2">
Inline spacing
</Box>

// Auto margin - use className
<Box className="m-auto">
Centered with auto margin
</section>
</Box>
```

#### Spacing Props Still Available

Most extension Box margin/padding props work the same in the design system:
#### Quick Mapping Summary

- ✅ `margin`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`
- ✅ `marginHorizontal` (replaces `marginInline`)
- ✅ `marginVertical`
- ✅ `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`
- ✅ `paddingHorizontal` (replaces `paddingInline`)
- ✅ `paddingVertical`
| Category | Legacy Extension | MMDS React |
| -------- | ---------------- | ---------- |
| Removed | `display`, `textAlign`, `width`, `minWidth`, `height`, `color`, `borderRadius`, `borderStyle` | Move to `className` / child styling |
| Renamed | `marginInline`, `paddingInline` | `marginHorizontal`, `paddingHorizontal` |
| Type changes | responsive arrays, `null`, `'auto'`, broader `borderWidth` range | scalar values only, no `null`/`'auto'`, `borderWidth` restricted |
| Behavior change | implicit border behavior in legacy helper | explicit border width required |

For simple, non-responsive spacing, continue using these props. Use `className` with Tailwind utilities for responsive spacing, auto values, or inline-start/end positioning.
For responsive values and one-off style parity, prefer `className` with Tailwind utilities in MMDS.

### BannerAlert Component

Expand Down
4 changes: 4 additions & 0 deletions packages/design-system-react/src/components/Box/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,10 @@ The `style` prop should primarily be used for dynamic inline styles that cannot

<Controls of={BoxStories.Default} />

## Migration Guide

Migrating from `ui/components/component-library/box` in MetaMask Extension? See the [Box Migration Guide](../../MIGRATION.md#box-component) for API mappings, before/after examples, and breaking changes.

## References

[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)
Loading