diff --git a/packages/design-system-react-native/MIGRATION.md b/packages/design-system-react-native/MIGRATION.md index cc39dd448..2947d8762 100644 --- a/packages/design-system-react-native/MIGRATION.md +++ b/packages/design-system-react-native/MIGRATION.md @@ -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 - - Custom spacing - +import { Box, Display, FlexDirection } from '../../../components/UI/Box/Box'; -// Inline props (if they existed) - - Inline spacing + + Legacy mobile layout ``` ##### After (Design System) ```tsx -import { Box } from '@metamask/design-system-react-native'; - -// Custom spacing - use twClassName for values outside BoxSpacing range - - Custom spacing - +import { + Box, + BoxBackgroundColor, + BoxFlexDirection, +} from '@metamask/design-system-react-native'; -// Inline props - use marginHorizontal or twClassName - - Inline spacing + + MMDS mobile layout ``` -#### 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 diff --git a/packages/design-system-react-native/src/components/Box/README.md b/packages/design-system-react-native/src/components/Box/README.md index 1a6016af0..a5ca7e24e 100644 --- a/packages/design-system-react-native/src/components/Box/README.md +++ b/packages/design-system-react-native/src/components/Box/README.md @@ -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) diff --git a/packages/design-system-react/MIGRATION.md b/packages/design-system-react/MIGRATION.md index bbb735b76..717ca11f6 100644 --- a/packages/design-system-react/MIGRATION.md +++ b/packages/design-system-react/MIGRATION.md @@ -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 - +import { Box, AlignItems, FlexDirection } from '../../component-library/box'; + + Responsive spacing - -// Inline props - - Inline spacing - - -// Auto margin - - Centered with auto margin - ``` ##### 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 - + +
Responsive spacing - - -// Inline props - use marginHorizontal or className - - Inline spacing - - -// Auto margin - use className - - Centered with auto margin +
``` -#### 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 diff --git a/packages/design-system-react/src/components/Box/README.mdx b/packages/design-system-react/src/components/Box/README.mdx index 954170b9b..ccac3f8be 100644 --- a/packages/design-system-react/src/components/Box/README.mdx +++ b/packages/design-system-react/src/components/Box/README.mdx @@ -431,6 +431,10 @@ The `style` prop should primarily be used for dynamic inline styles that cannot +## 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)