feat(shared): migrate Box to ADR-0003 and ADR-0004 shared types (DSYS-482)#1026
Merged
georgewrmarshall merged 9 commits intomainfrom Apr 22, 2026
Merged
Conversation
Contributor
📖 Storybook Preview |
Contributor
|
@metamaskbot publish-preview |
Contributor
|
Preview builds have been published. See these instructions for more information about preview builds. Expand for full list of packages and versions. |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
69c659c to
a73a010
Compare
Contributor
|
@metamaskbot publish-preview |
| */ | ||
| export const BoxBorderColor = { | ||
| /** Background default for cut out effect */ | ||
| BackgroundDefault: 'border-background-default', |
Contributor
There was a problem hiding this comment.
ADR-0003: const objects are runtime backwards-compatible with the old enums.
The old enum BoxFlexDirection { Row = 'flex-row' } and the new const BoxFlexDirection = { Row: 'flex-row' } as const produce identical runtime values — BoxFlexDirection.Row === 'flex-row' in both. Consumers who access members by name (BoxFlexDirection.Row) require no code changes. The only behavioral difference is TypeScript narrows the derived union type ('flex-row' | 'flex-row-reverse' | ...) instead of treating it as an opaque enum — which is strictly more permissive for string literal assignments.
Contributor
📖 Storybook Preview |
| * The background color of the component. | ||
| */ | ||
| backgroundColor?: BoxBackgroundColor; | ||
| }; |
Contributor
There was a problem hiding this comment.
Why are className, twClassName, and asChild absent from BoxPropsShared?
These are platform-specific concerns: className is web-only CSS, twClassName is React Native TWRNC, and asChild is the Radix UI polymorphic pattern used only in React web. Per ADR-0004, shared props must be platform-independent — only layout/spacing/color props that map to the same Tailwind class names on both platforms belong here. Each platform's BoxProps adds its own extension props on top.
| * @default false | ||
| */ | ||
| asChild?: boolean; | ||
| }; |
Contributor
There was a problem hiding this comment.
~130 lines collapsed to ~17: the full reduction enabled by ADR-0004.
All spacing/layout/color prop declarations now live in BoxPropsShared in the shared package. The React BoxProps only needs to add the two web-specific props: className (Tailwind CSS override) and asChild (Radix UI slot pattern for polymorphic rendering). This is the intended outcome of the centralized types architecture — platform files become thin extension layers.
| type BoxBorderWidth, | ||
| } from '@metamask/design-system-shared'; | ||
| export { Box } from './Box'; | ||
| export type { BoxProps } from './Box.types'; |
Contributor
There was a problem hiding this comment.
Why BoxBorderWidth is now exported from index.ts when it wasn't before.
The React package previously only re-exported BoxSpacing (not BoxBorderWidth) from its index.ts. Now that both types live in the shared package, both are exported here to maintain a complete public API from the component barrel. This brings React into parity with React Native, which already needed BoxBorderWidth for its constants file.
| } from '../../types'; | ||
| } from '@metamask/design-system-shared'; | ||
|
|
||
| import { IconColor, IconName } from '../../types'; |
Contributor
There was a problem hiding this comment.
This split-import pattern is the correct ADR-0004 boundary in practice.
BannerAlertSeverity, BoxBackgroundColor, and BoxBorderColor are cross-platform design system tokens → imported from @metamask/design-system-shared. IconColor and IconName are still platform-specific (React Native Icon enum values differ from React) → stay in ../../types. This file is a good example of where the shared/platform boundary sits for a real consuming component.
Contributor
|
Preview builds have been published. See these instructions for more information about preview builds. Expand for full list of packages and versions. |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
a73a010 to
af0a205
Compare
Contributor
📖 Storybook Preview |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
af0a205 to
fdf2765
Compare
Contributor
📖 Storybook Preview |
Contributor
📖 Storybook Preview |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
📖 Storybook Preview |
Contributor
📖 Storybook Preview |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
e47c090 to
a32f511
Compare
Contributor
📖 Storybook Preview |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
a32f511 to
4be78b1
Compare
Contributor
📖 Storybook Preview |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
4be78b1 to
108d5b3
Compare
| {...args} | ||
| padding={3} | ||
| backgroundColor={BoxBackgroundColor.InfoMuted} | ||
| borderColor={BoxBorderColor.InfoAlternative} |
Contributor
There was a problem hiding this comment.
Removing colors that no longer exist was an existing bug
Contributor
📖 Storybook Preview |
Contributor
📖 Storybook Preview |
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
704c60b to
9f8f77d
Compare
Contributor
📖 Storybook Preview |
kirillzyusko
previously approved these changes
Apr 21, 2026
…-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 <[email protected]>
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.
These tokens were removed from design-tokens in v4.0.0. Removes stale entries from BoxBackgroundColor and BoxBorderColor, and their story usage.
Documents in all three MIGRATION.md files: - Box types now sourced from @metamask/design-system-shared - Removed stale -alternative color tokens (warning, success, info)
georgewrmarshall
force-pushed
the
cursor/enum-shared-type-migration-8196
branch
from
9f8f77d to
9a6f3fc
Compare
Contributor
Author
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 9a6f3fc. Configure here.
Contributor
📖 Storybook Preview |
georgewrmarshall
approved these changes
Apr 21, 2026
kirillzyusko
approved these changes
Apr 22, 2026
georgewrmarshall
added a commit
that referenced
this pull request
Apr 23, 2026
## Release 35.0.0 This release adds new React Native title primitives, continues the enum-to-const-object/string-union migration for public type exports, and updates the release documentation so breaking changes are consumer-focused and migration-oriented. ### Package Versions - `@metamask/design-system-shared`: **0.13.0** - `@metamask/design-system-react`: **0.18.0** - `@metamask/design-system-react-native`: **0.20.0** - `@metamask/design-system-tailwind-preset`: **0.6.2** ### Shared Type Updates (0.13.0) #### Added (#1051, #1053, #1059) **What Changed:** - Added `TitleStandardPropsShared` and `TitleSubpagePropsShared` - Added `TagSeverity` and `TagPropsShared` **Impact:** - Supports the new React Native `TitleStandard`, `TitleSubpage`, and `Tag` APIs #### Changed (#1026, #1042) **What Changed:** - **BREAKING:** Updated shared `Box` and `Icon` exports from enums to const objects with derived string-union types - Removed stale Box `WarningAlternative`, `SuccessAlternative`, and `InfoAlternative` color entries that no longer map to design tokens **Impact:** - Affects consumers of `@metamask/design-system-shared` directly - Platform package consumers should continue importing from `@metamask/design-system-react` or `@metamask/design-system-react-native` ### React Web Updates (0.18.0) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042, #1101) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### React Native Updates (0.20.0) #### Added - Added `TitleStandard` for mobile title layouts with optional top and bottom accessory rows (#1051) - Added `TitleSubpage` for subpage headers with avatar, title, subtitle, amount, and bottom-label layouts (#1059) - Added `Tag` for compact severity-based metadata labels with optional icons or custom accessories (#1053) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - `Box` now forwards refs to the underlying `View` (#1102) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### Tailwind Preset Updates (0.6.2) #### Changed - No consumer-facing API or behavior changes in this release; this patch republishes the existing preset without requiring changes in consuming apps ### Breaking Changes #### Icon and Box enum exports migrated to const objects plus string unions (Both Platforms) **What Changed:** - `IconName`, `IconColor`, and `IconSize` now use const objects with derived string-union types instead of enums - `BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, and `BoxBorderWidth` now use const objects with derived string-union types instead of enums - Removed stale Box color entries with no backing design token: - `BoxBackgroundColor.WarningAlternative` - `BoxBackgroundColor.SuccessAlternative` - `BoxBorderColor.WarningAlternative` - `BoxBorderColor.SuccessAlternative` - `BoxBorderColor.InfoAlternative` **Migration:** ```tsx // Before import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningAlternative} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> // After import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningDefault} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> ``` **Impact:** - Affects consumers relying on enum-specific TypeScript behavior for `Icon*` and `Box*` exports - Import paths stay the same for platform-package consumers - Any use of the removed Box `*Alternative` color entries will need to switch to the corresponding `*Default` or `*Muted` token See migration guides for complete instructions: - [React Migration Guide](./packages/design-system-react/MIGRATION.md#from-version-0170-to-0180) - [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0190-to-0200) ### Validation - `yarn changelog:validate` <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Medium risk because it publishes new versions with **breaking TypeScript surface changes** (Box/Icon enums → const-object/string-union and removal of stale Box color members), which can break downstream builds despite minimal runtime behavior changes. > > **Overview** > Bumps the monorepo release to `35.0.0` and publishes new package versions for `@metamask/design-system-react` (`0.18.0`), `@metamask/design-system-react-native` (`0.20.0`), and `@metamask/design-system-shared` (`0.13.0`). > > Updates changelogs/migration guides to reflect the release: adds React Native primitives (`TitleStandard`, `TitleSubpage`, `Tag`) and shared prop contracts, and documents **breaking** shifts of `Box*` and `Icon*` exports from enums to const-object + string-union types (plus removal of stale `*Alternative` Box color entries) with consumer-facing migration steps. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit addbae5. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
georgewrmarshall
added a commit
that referenced
this pull request
Apr 27, 2026
…-482) (#1026) ## **Description** Migrates the `Box` component to follow [ADR-0003 (String Unions)](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0003-enum-to-string-union-migration.md) and [ADR-0004 (Centralized Types Architecture)](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0004-centralized-types-architecture.md) as part of the DSYS-468 epic. No visual regressions — the component renders identically before and after. Also fixed incorrect `-alternative` color tokens (`WarningAlternative`, `SuccessAlternative`, `InfoAlternative`) that were removed from `@metamask/design-tokens` in v4.0.0 but incorrectly carried over into the Box const objects. **What changed:** - Created `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 — already primitive literal types) - `BoxPropsShared` new shared props type with all platform-independent properties (ADR-0004) - Exported all Box types from `@metamask/design-system-shared` index - Updated React package `Box.types.ts` to extend `BoxPropsShared` from shared - Updated React package `Box/index.ts` to export const objects from shared (single source of truth) - Updated React Native package `Box.types.ts` to extend `BoxPropsShared` from shared - Updated React Native package `Box/index.ts` to export const objects from shared - Removed old Box enums from both platform `src/types/index.ts` files - Updated all files importing Box types directly from `../../types` to import from `@metamask/design-system-shared` (BannerBase, BannerAlert, BoxRow, BoxColumn, and various story files) - Removed stale `-alternative` color tokens from `BoxBackgroundColor` and `BoxBorderColor` that had no backing design token since `@metamask/design-tokens` v4.0.0 - Updated MIGRATION.md docs for all three packages ## **Related issues** Fixes: [DSYS-482](https://consensyssoftware.atlassian.net/browse/DSYS-482) ## **Manual testing steps** 1. Run `yarn build` from repo root — should succeed 2. Run `yarn test` from repo root — all Box tests should pass with 100% coverage 3. Run `yarn lint` from repo root — no new lint errors ## **Screenshots/Recordings** ### **Before** `BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor` were enums duplicated in both `design-system-react/src/types/index.ts` and `design-system-react-native/src/types/index.ts` with no shared source. https://github.com/user-attachments/assets/665c8556-2e99-48e2-ae92-04d1aeb512b9 ### **After** All Box enums are now const objects in `@metamask/design-system-shared`, with a single `BoxPropsShared` type containing all platform-independent props. Both React and React Native packages extend `BoxPropsShared` and add their platform-specific props (`className`/`asChild` for React, `twClassName` for React Native). Stale `-alternative` color tokens have been removed. https://github.com/user-attachments/assets/10b643b5-fe9e-4840-b29f-cd71930b2518 ## **Pre-merge author checklist** - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) - [x] I've completed the PR template to the best of my ability - [x] I've included tests if applicable - [x] I've documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [ ] I've applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. ## **Pre-merge reviewer checklist** - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Touches public type exports across `design-system-shared`, `design-system-react`, and `design-system-react-native`, so downstream TypeScript builds may break if they relied on removed Box color tokens or enum semantics. Runtime/visual behavior should be unchanged, but type-level regressions and import mismatches are possible. > > **Overview** > Moves the canonical `Box` type surface (`BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, `BoxBorderWidth`, and new `BoxPropsShared`) into `@metamask/design-system-shared`, converting the Box enums to `as const` objects (string unions) and re-exporting them from the React and React Native packages. > > Updates Box prop types in both platforms to extend `BoxPropsShared`, rewires component/tests/stories to import Box tokens from `@metamask/design-system-shared`, and removes the duplicated Box type definitions from each package’s `src/types/index.ts`. > > Removes stale `*-Alternative` Box warning/success/info color tokens (and story usage) and documents these changes in the migration guides for `design-system-shared`, `design-system-react`, and `design-system-react-native`. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit c2ba540. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Cursor Agent <[email protected]> Co-authored-by: George Marshall <[email protected]> Co-authored-by: georgewrmarshall <[email protected]>
georgewrmarshall
added a commit
that referenced
this pull request
Apr 27, 2026
## Release 35.0.0 This release adds new React Native title primitives, continues the enum-to-const-object/string-union migration for public type exports, and updates the release documentation so breaking changes are consumer-focused and migration-oriented. ### Package Versions - `@metamask/design-system-shared`: **0.13.0** - `@metamask/design-system-react`: **0.18.0** - `@metamask/design-system-react-native`: **0.20.0** - `@metamask/design-system-tailwind-preset`: **0.6.2** ### Shared Type Updates (0.13.0) #### Added (#1051, #1053, #1059) **What Changed:** - Added `TitleStandardPropsShared` and `TitleSubpagePropsShared` - Added `TagSeverity` and `TagPropsShared` **Impact:** - Supports the new React Native `TitleStandard`, `TitleSubpage`, and `Tag` APIs #### Changed (#1026, #1042) **What Changed:** - **BREAKING:** Updated shared `Box` and `Icon` exports from enums to const objects with derived string-union types - Removed stale Box `WarningAlternative`, `SuccessAlternative`, and `InfoAlternative` color entries that no longer map to design tokens **Impact:** - Affects consumers of `@metamask/design-system-shared` directly - Platform package consumers should continue importing from `@metamask/design-system-react` or `@metamask/design-system-react-native` ### React Web Updates (0.18.0) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042, #1101) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### React Native Updates (0.20.0) #### Added - Added `TitleStandard` for mobile title layouts with optional top and bottom accessory rows (#1051) - Added `TitleSubpage` for subpage headers with avatar, title, subtitle, amount, and bottom-label layouts (#1059) - Added `Tag` for compact severity-based metadata labels with optional icons or custom accessories (#1053) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - `Box` now forwards refs to the underlying `View` (#1102) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### Tailwind Preset Updates (0.6.2) #### Changed - No consumer-facing API or behavior changes in this release; this patch republishes the existing preset without requiring changes in consuming apps ### Breaking Changes #### Icon and Box enum exports migrated to const objects plus string unions (Both Platforms) **What Changed:** - `IconName`, `IconColor`, and `IconSize` now use const objects with derived string-union types instead of enums - `BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, and `BoxBorderWidth` now use const objects with derived string-union types instead of enums - Removed stale Box color entries with no backing design token: - `BoxBackgroundColor.WarningAlternative` - `BoxBackgroundColor.SuccessAlternative` - `BoxBorderColor.WarningAlternative` - `BoxBorderColor.SuccessAlternative` - `BoxBorderColor.InfoAlternative` **Migration:** ```tsx // Before import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningAlternative} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> // After import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningDefault} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> ``` **Impact:** - Affects consumers relying on enum-specific TypeScript behavior for `Icon*` and `Box*` exports - Import paths stay the same for platform-package consumers - Any use of the removed Box `*Alternative` color entries will need to switch to the corresponding `*Default` or `*Muted` token See migration guides for complete instructions: - [React Migration Guide](./packages/design-system-react/MIGRATION.md#from-version-0170-to-0180) - [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0190-to-0200) ### Validation - `yarn changelog:validate` <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Medium risk because it publishes new versions with **breaking TypeScript surface changes** (Box/Icon enums → const-object/string-union and removal of stale Box color members), which can break downstream builds despite minimal runtime behavior changes. > > **Overview** > Bumps the monorepo release to `35.0.0` and publishes new package versions for `@metamask/design-system-react` (`0.18.0`), `@metamask/design-system-react-native` (`0.20.0`), and `@metamask/design-system-shared` (`0.13.0`). > > Updates changelogs/migration guides to reflect the release: adds React Native primitives (`TitleStandard`, `TitleSubpage`, `Tag`) and shared prop contracts, and documents **breaking** shifts of `Box*` and `Icon*` exports from enums to const-object + string-union types (plus removal of stale `*Alternative` Box color entries) with consumer-facing migration steps. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit addbae5. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
georgewrmarshall
added a commit
that referenced
this pull request
Apr 28, 2026
## Release 35.0.0 This release adds new React Native title primitives, continues the enum-to-const-object/string-union migration for public type exports, and updates the release documentation so breaking changes are consumer-focused and migration-oriented. ### Package Versions - `@metamask/design-system-shared`: **0.13.0** - `@metamask/design-system-react`: **0.18.0** - `@metamask/design-system-react-native`: **0.20.0** - `@metamask/design-system-tailwind-preset`: **0.6.2** ### Shared Type Updates (0.13.0) #### Added (#1051, #1053, #1059) **What Changed:** - Added `TitleStandardPropsShared` and `TitleSubpagePropsShared` - Added `TagSeverity` and `TagPropsShared` **Impact:** - Supports the new React Native `TitleStandard`, `TitleSubpage`, and `Tag` APIs #### Changed (#1026, #1042) **What Changed:** - **BREAKING:** Updated shared `Box` and `Icon` exports from enums to const objects with derived string-union types - Removed stale Box `WarningAlternative`, `SuccessAlternative`, and `InfoAlternative` color entries that no longer map to design tokens **Impact:** - Affects consumers of `@metamask/design-system-shared` directly - Platform package consumers should continue importing from `@metamask/design-system-react` or `@metamask/design-system-react-native` ### React Web Updates (0.18.0) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042, #1101) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### React Native Updates (0.20.0) #### Added - Added `TitleStandard` for mobile title layouts with optional top and bottom accessory rows (#1051) - Added `TitleSubpage` for subpage headers with avatar, title, subtitle, amount, and bottom-label layouts (#1059) - Added `Tag` for compact severity-based metadata labels with optional icons or custom accessories (#1053) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - `Box` now forwards refs to the underlying `View` (#1102) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### Tailwind Preset Updates (0.6.2) #### Changed - No consumer-facing API or behavior changes in this release; this patch republishes the existing preset without requiring changes in consuming apps ### Breaking Changes #### Icon and Box enum exports migrated to const objects plus string unions (Both Platforms) **What Changed:** - `IconName`, `IconColor`, and `IconSize` now use const objects with derived string-union types instead of enums - `BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, and `BoxBorderWidth` now use const objects with derived string-union types instead of enums - Removed stale Box color entries with no backing design token: - `BoxBackgroundColor.WarningAlternative` - `BoxBackgroundColor.SuccessAlternative` - `BoxBorderColor.WarningAlternative` - `BoxBorderColor.SuccessAlternative` - `BoxBorderColor.InfoAlternative` **Migration:** ```tsx // Before import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningAlternative} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> // After import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningDefault} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> ``` **Impact:** - Affects consumers relying on enum-specific TypeScript behavior for `Icon*` and `Box*` exports - Import paths stay the same for platform-package consumers - Any use of the removed Box `*Alternative` color entries will need to switch to the corresponding `*Default` or `*Muted` token See migration guides for complete instructions: - [React Migration Guide](./packages/design-system-react/MIGRATION.md#from-version-0170-to-0180) - [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0190-to-0200) ### Validation - `yarn changelog:validate` <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Medium risk because it publishes new versions with **breaking TypeScript surface changes** (Box/Icon enums → const-object/string-union and removal of stale Box color members), which can break downstream builds despite minimal runtime behavior changes. > > **Overview** > Bumps the monorepo release to `35.0.0` and publishes new package versions for `@metamask/design-system-react` (`0.18.0`), `@metamask/design-system-react-native` (`0.20.0`), and `@metamask/design-system-shared` (`0.13.0`). > > Updates changelogs/migration guides to reflect the release: adds React Native primitives (`TitleStandard`, `TitleSubpage`, `Tag`) and shared prop contracts, and documents **breaking** shifts of `Box*` and `Icon*` exports from enums to const-object + string-union types (plus removal of stale `*Alternative` Box color entries) with consumer-facing migration steps. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit addbae5. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
cursor Bot
added a commit
that referenced
this pull request
Apr 28, 2026
…-482) (#1026) ## **Description** Migrates the `Box` component to follow [ADR-0003 (String Unions)](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0003-enum-to-string-union-migration.md) and [ADR-0004 (Centralized Types Architecture)](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0004-centralized-types-architecture.md) as part of the DSYS-468 epic. No visual regressions — the component renders identically before and after. Also fixed incorrect `-alternative` color tokens (`WarningAlternative`, `SuccessAlternative`, `InfoAlternative`) that were removed from `@metamask/design-tokens` in v4.0.0 but incorrectly carried over into the Box const objects. **What changed:** - Created `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 — already primitive literal types) - `BoxPropsShared` new shared props type with all platform-independent properties (ADR-0004) - Exported all Box types from `@metamask/design-system-shared` index - Updated React package `Box.types.ts` to extend `BoxPropsShared` from shared - Updated React package `Box/index.ts` to export const objects from shared (single source of truth) - Updated React Native package `Box.types.ts` to extend `BoxPropsShared` from shared - Updated React Native package `Box/index.ts` to export const objects from shared - Removed old Box enums from both platform `src/types/index.ts` files - Updated all files importing Box types directly from `../../types` to import from `@metamask/design-system-shared` (BannerBase, BannerAlert, BoxRow, BoxColumn, and various story files) - Removed stale `-alternative` color tokens from `BoxBackgroundColor` and `BoxBorderColor` that had no backing design token since `@metamask/design-tokens` v4.0.0 - Updated MIGRATION.md docs for all three packages ## **Related issues** Fixes: [DSYS-482](https://consensyssoftware.atlassian.net/browse/DSYS-482) ## **Manual testing steps** 1. Run `yarn build` from repo root — should succeed 2. Run `yarn test` from repo root — all Box tests should pass with 100% coverage 3. Run `yarn lint` from repo root — no new lint errors ## **Screenshots/Recordings** ### **Before** `BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor` were enums duplicated in both `design-system-react/src/types/index.ts` and `design-system-react-native/src/types/index.ts` with no shared source. https://github.com/user-attachments/assets/665c8556-2e99-48e2-ae92-04d1aeb512b9 ### **After** All Box enums are now const objects in `@metamask/design-system-shared`, with a single `BoxPropsShared` type containing all platform-independent props. Both React and React Native packages extend `BoxPropsShared` and add their platform-specific props (`className`/`asChild` for React, `twClassName` for React Native). Stale `-alternative` color tokens have been removed. https://github.com/user-attachments/assets/10b643b5-fe9e-4840-b29f-cd71930b2518 ## **Pre-merge author checklist** - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) - [x] I've completed the PR template to the best of my ability - [x] I've included tests if applicable - [x] I've documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [ ] I've applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. ## **Pre-merge reviewer checklist** - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Touches public type exports across `design-system-shared`, `design-system-react`, and `design-system-react-native`, so downstream TypeScript builds may break if they relied on removed Box color tokens or enum semantics. Runtime/visual behavior should be unchanged, but type-level regressions and import mismatches are possible. > > **Overview** > Moves the canonical `Box` type surface (`BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, `BoxBorderWidth`, and new `BoxPropsShared`) into `@metamask/design-system-shared`, converting the Box enums to `as const` objects (string unions) and re-exporting them from the React and React Native packages. > > Updates Box prop types in both platforms to extend `BoxPropsShared`, rewires component/tests/stories to import Box tokens from `@metamask/design-system-shared`, and removes the duplicated Box type definitions from each package’s `src/types/index.ts`. > > Removes stale `*-Alternative` Box warning/success/info color tokens (and story usage) and documents these changes in the migration guides for `design-system-shared`, `design-system-react`, and `design-system-react-native`. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit c2ba540. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Cursor Agent <[email protected]> Co-authored-by: George Marshall <[email protected]> Co-authored-by: georgewrmarshall <[email protected]>
cursor Bot
pushed a commit
that referenced
this pull request
Apr 28, 2026
## Release 35.0.0 This release adds new React Native title primitives, continues the enum-to-const-object/string-union migration for public type exports, and updates the release documentation so breaking changes are consumer-focused and migration-oriented. ### Package Versions - `@metamask/design-system-shared`: **0.13.0** - `@metamask/design-system-react`: **0.18.0** - `@metamask/design-system-react-native`: **0.20.0** - `@metamask/design-system-tailwind-preset`: **0.6.2** ### Shared Type Updates (0.13.0) #### Added (#1051, #1053, #1059) **What Changed:** - Added `TitleStandardPropsShared` and `TitleSubpagePropsShared` - Added `TagSeverity` and `TagPropsShared` **Impact:** - Supports the new React Native `TitleStandard`, `TitleSubpage`, and `Tag` APIs #### Changed (#1026, #1042) **What Changed:** - **BREAKING:** Updated shared `Box` and `Icon` exports from enums to const objects with derived string-union types - Removed stale Box `WarningAlternative`, `SuccessAlternative`, and `InfoAlternative` color entries that no longer map to design tokens **Impact:** - Affects consumers of `@metamask/design-system-shared` directly - Platform package consumers should continue importing from `@metamask/design-system-react` or `@metamask/design-system-react-native` ### React Web Updates (0.18.0) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042, #1101) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### React Native Updates (0.20.0) #### Added - Added `TitleStandard` for mobile title layouts with optional top and bottom accessory rows (#1051) - Added `TitleSubpage` for subpage headers with avatar, title, subtitle, amount, and bottom-label layouts (#1059) - Added `Tag` for compact severity-based metadata labels with optional icons or custom accessories (#1053) #### Changed - **BREAKING:** Updated `IconName`, `IconColor`, and `IconSize` exports to use const-object + string-union types instead of enums (#1042) - **BREAKING:** Updated `Box` type exports to use const-object + string-union types and removed stale Box color entries (#1026) - `Box` now forwards refs to the underlying `View` (#1102) - Updated `ButtonTertiary` to use the default text color for more consistent contrast across states (#1099) ### Tailwind Preset Updates (0.6.2) #### Changed - No consumer-facing API or behavior changes in this release; this patch republishes the existing preset without requiring changes in consuming apps ### Breaking Changes #### Icon and Box enum exports migrated to const objects plus string unions (Both Platforms) **What Changed:** - `IconName`, `IconColor`, and `IconSize` now use const objects with derived string-union types instead of enums - `BoxFlexDirection`, `BoxFlexWrap`, `BoxAlignItems`, `BoxJustifyContent`, `BoxBackgroundColor`, `BoxBorderColor`, `BoxSpacing`, and `BoxBorderWidth` now use const objects with derived string-union types instead of enums - Removed stale Box color entries with no backing design token: - `BoxBackgroundColor.WarningAlternative` - `BoxBackgroundColor.SuccessAlternative` - `BoxBorderColor.WarningAlternative` - `BoxBorderColor.SuccessAlternative` - `BoxBorderColor.InfoAlternative` **Migration:** ```tsx // Before import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningAlternative} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> // After import { BoxBackgroundColor, IconColor, IconName, } from '@metamask/design-system-react-native'; <Box backgroundColor={BoxBackgroundColor.WarningDefault} /> <Icon name={IconName.Add} color={IconColor.IconDefault} /> ``` **Impact:** - Affects consumers relying on enum-specific TypeScript behavior for `Icon*` and `Box*` exports - Import paths stay the same for platform-package consumers - Any use of the removed Box `*Alternative` color entries will need to switch to the corresponding `*Default` or `*Muted` token See migration guides for complete instructions: - [React Migration Guide](./packages/design-system-react/MIGRATION.md#from-version-0170-to-0180) - [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0190-to-0200) ### Validation - `yarn changelog:validate` <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Medium risk because it publishes new versions with **breaking TypeScript surface changes** (Box/Icon enums → const-object/string-union and removal of stale Box color members), which can break downstream builds despite minimal runtime behavior changes. > > **Overview** > Bumps the monorepo release to `35.0.0` and publishes new package versions for `@metamask/design-system-react` (`0.18.0`), `@metamask/design-system-react-native` (`0.20.0`), and `@metamask/design-system-shared` (`0.13.0`). > > Updates changelogs/migration guides to reflect the release: adds React Native primitives (`TitleStandard`, `TitleSubpage`, `Tag`) and shared prop contracts, and documents **breaking** shifts of `Box*` and `Icon*` exports from enums to const-object + string-union types (plus removal of stale `*Alternative` Box color entries) with consumer-facing migration steps. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit addbae5. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Migrates the
Boxcomponent to follow ADR-0003 (String Unions) and ADR-0004 (Centralized Types Architecture) as part of the DSYS-468 epic.No visual regressions — the component renders identically before and after. Also fixed incorrect
-alternativecolor tokens (WarningAlternative,SuccessAlternative,InfoAlternative) that were removed from@metamask/design-tokensin v4.0.0 but incorrectly carried over into the Box const objects.What changed:
packages/design-system-shared/src/types/Box/Box.types.tswith:BoxFlexDirection,BoxFlexWrap,BoxAlignItems,BoxJustifyContent,BoxBackgroundColor,BoxBorderColorconverted from enums to const objects (ADR-0003)BoxSpacing,BoxBorderWidthtype aliases (unchanged — already primitive literal types)BoxPropsSharednew shared props type with all platform-independent properties (ADR-0004)@metamask/design-system-sharedindexBox.types.tsto extendBoxPropsSharedfrom sharedBox/index.tsto export const objects from shared (single source of truth)Box.types.tsto extendBoxPropsSharedfrom sharedBox/index.tsto export const objects from sharedsrc/types/index.tsfiles../../typesto import from@metamask/design-system-shared(BannerBase, BannerAlert, BoxRow, BoxColumn, and various story files)-alternativecolor tokens fromBoxBackgroundColorandBoxBorderColorthat had no backing design token since@metamask/design-tokensv4.0.0Related issues
Fixes: DSYS-482
Manual testing steps
yarn buildfrom repo root — should succeedyarn testfrom repo root — all Box tests should pass with 100% coverageyarn lintfrom repo root — no new lint errorsScreenshots/Recordings
Before
BoxFlexDirection,BoxFlexWrap,BoxAlignItems,BoxJustifyContent,BoxBackgroundColor,BoxBorderColorwere enums duplicated in bothdesign-system-react/src/types/index.tsanddesign-system-react-native/src/types/index.tswith no shared source.Box.Before.720.mov
After
All Box enums are now const objects in
@metamask/design-system-shared, with a singleBoxPropsSharedtype containing all platform-independent props. Both React and React Native packages extendBoxPropsSharedand add their platform-specific props (className/asChildfor React,twClassNamefor React Native). Stale-alternativecolor tokens have been removed.Box.After720.mov
Pre-merge author checklist
Pre-merge reviewer checklist
Note
Medium Risk
Touches public type exports across
design-system-shared,design-system-react, anddesign-system-react-native, so downstream TypeScript builds may break if they relied on removed Box color tokens or enum semantics. Runtime/visual behavior should be unchanged, but type-level regressions and import mismatches are possible.Overview
Moves the canonical
Boxtype surface (BoxFlexDirection,BoxFlexWrap,BoxAlignItems,BoxJustifyContent,BoxBackgroundColor,BoxBorderColor,BoxSpacing,BoxBorderWidth, and newBoxPropsShared) into@metamask/design-system-shared, converting the Box enums toas constobjects (string unions) and re-exporting them from the React and React Native packages.Updates Box prop types in both platforms to extend
BoxPropsShared, rewires component/tests/stories to import Box tokens from@metamask/design-system-shared, and removes the duplicated Box type definitions from each package’ssrc/types/index.ts.Removes stale
*-AlternativeBox warning/success/info color tokens (and story usage) and documents these changes in the migration guides fordesign-system-shared,design-system-react, anddesign-system-react-native.Reviewed by Cursor Bugbot for commit c2ba540. Bugbot is set up for automated code reviews on this repo. Configure here.