[1/N] feat: `ModalOverlay` migration (extension) by kirillzyusko · Pull Request #1120 · MetaMask/metamask-design-system

kirillzyusko · 2026-04-28T12:31:14Z

Description

Added ModalOverlay component to DSRN (react).

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-306

Manual testing steps

Open storybook
Check ModalOverlay

Screenshots/Recordings

Before

Screen.Recording.2026-04-28.at.14.31.29.mov

After

Screen.Recording.2026-04-28.at.14.26.21.mov

Pre-merge author checklist

I've followed MetaMask Contributor Docs
I've completed the PR template to the best of my ability
I’ve included tests if applicable
I’ve documented my code using JSDoc format if applicable
I’ve applied the right labels on the PR (see labeling guidelines). 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.

Note

Medium Risk
Mostly additive, but it extends the shared Tailwind preset with a new fade-in keyframe/animation and introduces a new exported component API, which could affect consumers relying on Tailwind config output or overlay styling/animation expectations.

Overview
Adds a new ModalOverlay component to @metamask/design-system-react, implemented as a Box-backed full-viewport overlay with default bg-overlay-default, fixed positioning, and a motion-safe:animate-fade-in class while forwarding refs and native div props.

Introduces Storybook stories, MDX docs, and RTL tests for the new component, exports it from the package barrel, and updates MIGRATION.md with extension-to-design-system guidance and breaking-change notes.

Extends design-system-tailwind-preset with a fade-in keyframe and animate-fade-in animation (300ms linear) to support the overlay’s mount animation.

^{Reviewed by Cursor Bugbot for commit 9dae9ab. Bugbot is set up for automated code reviews on this repo. Configure here.}

…lated CI

github-actions · 2026-04-28T12:46:30Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-04-28T12:57:03Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-04-28T13:05:54Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall

ModalOverlay looks close, but the migration/docs pass is not complete yet. The component itself preserves the core extension behavior, but the README links to a migration entry that does not exist yet.

georgewrmarshall · 2026-04-29T01:57:36Z

+
+## Migration Guide
+
+Migrating from `ui/components/component-library/modal-overlay` in MetaMask Extension? See the [ModalOverlay Migration Guide](../../../MIGRATION.md#modaloverlay-component) for prop mappings, before/after examples, and breaking changes.


blocking: This README links to ../../../MIGRATION.md#modaloverlay-component, but packages/design-system-react/MIGRATION.md does not have a ModalOverlay section yet. Since this PR is part of the extension migration flow, can we add the ModalOverlay migration entry before merging so consumers have the actual prop mapping / before-after examples?

georgewrmarshall · 2026-04-29T01:57:36Z

+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { Button, ButtonVariant } from '../Button';


suggestion: I just merged #1034 so ButtonVariant is a shared const, so per .cursor/rules/component-architecture.md it should come from @metamask/design-system-shared rather than through a sibling component export.

github-actions · 2026-04-29T11:17:26Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall

I rechecked the current head against the earlier review round. The missing ModalOverlay migration entry is in place now, the README link resolves correctly, and the focused ModalOverlay test file passes on the PR head. I don’t have any remaining findings.

github-actions · 2026-04-30T20:35:47Z

📖 Storybook Preview

View PR Storybook

## Release 38.0.0 This release updates the shared, web, native, tokens, and Tailwind packages with new cross-platform input and avatar-group contracts, new modal building blocks for React, a breaking React Native Toast API redesign, and Tailwind CSS v4 support for web consumers. ### 📦 Package Versions - `@metamask/design-system-shared`: **0.16.0** - `@metamask/design-system-react`: **0.21.0** - `@metamask/design-system-react-native`: **0.23.0** - `@metamask/design-system-tailwind-preset`: **0.7.0** - `@metamask/design-tokens`: **8.4.0** ### 🔄 Shared Type Updates (0.16.0) #### Input and AvatarGroup shared contracts ([#1043](#1043), [#1067](#1067)) **What Changed:** - Added shared `Input` contracts for controlled `value`, `isReadOnly`, and `isStateStylesDisabled` - Added shared `AvatarGroup` size, variant, and prop contracts - Added the shared `Merge` icon export ([#1155](#1155)) **Impact:** - React and React Native consumers can build against one aligned input and avatar-group API surface - Cross-platform wrappers can depend on `@metamask/design-system-shared` instead of maintaining platform-specific type assumptions ### 🌐 React Web Updates (0.21.0) #### Added - Added `ModalOverlay`, `ModalBody`, `ModalFocus`, and `ModalFooter` to support Extension modal migrations into `@metamask/design-system-react` ([#1120](#1120), [#1121](#1121), [#1128](#1128), [#1132](#1132)) - Added the `Merge` icon to the React icon set ([#1155](#1155)) #### Changed - Updated `Input` to follow the shared controlled input API and use `isReadOnly` as the public readonly prop name ([#1043](#1043)) - Updated `AvatarGroup` to use shared cross-platform size and variant contracts ([#1067](#1067)) ### 📱 React Native Updates (0.23.0) #### Added - Added the `Merge` icon to the React Native icon set ([#1155](#1155)) #### Changed - **BREAKING:** Redesigned `Toast` to use a single mounted `<Toast />` plus static `Toast.show(...)` and `Toast.hide()` methods for application usage ([#1104](#1104)) - Removed `ToastContext`, `ToastContextWrapper`, and `ToastContextParams` from the public export surface - Renamed `ToastVariants` to `ToastVariant`, changed icon-only close buttons to `ToastCloseButtonVariant.Icon`, and renamed `customBottomOffset` to `bottomOffset` - `Toast.show()` and `Toast.hide()` now throw a descriptive error if called before `<Toast />` mounts - See the [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0220-to-0230) - Updated `Input` to follow the shared controlled input API and rename `isReadonly` to `isReadOnly` ([#1043](#1043)) - Updated `AvatarGroup` to use shared cross-platform size and variant contracts ([#1067](#1067)) ### 🎨 Tokens and Tailwind Updates #### `@metamask/design-tokens` 8.4.0 - Added `@metamask/design-tokens/tailwind/theme.css` for Tailwind CSS v4 consumers, providing a single import for token variables, theme values, typography, fonts, and shadow utilities ([#1117](#1117)) #### `@metamask/design-system-tailwind-preset` 0.7.0 - Added a `fade-in` animation utility so consumers can use `animate-fade-in` for simple opacity entrance transitions, including the new `ModalOverlay` web migration path ([#1120](#1120)) - Clarified that Tailwind CSS v3 consumers should keep using this preset, while Tailwind CSS v4 consumers should migrate to `@metamask/design-tokens/tailwind/theme.css` ([#1117](#1117)) ### ⚠️ Breaking Changes #### Toast API redesign (React Native) **What Changed:** - `Toast` application usage moved from context/service patterns to static `Toast.show(...)` and `Toast.hide()` methods - `ToastContext`, `ToastContextWrapper`, and `ToastContextParams` were removed from the public API - `ToastVariants` was renamed to `ToastVariant` - Icon-only close buttons now use `ToastCloseButtonVariant.Icon` - `customBottomOffset` was renamed to `bottomOffset` **Impact:** - Existing `@metamask/design-system-react-native` consumers using the old Toast context flow need import, root-mount, and call-site updates - Existing app code must ensure `<Toast />` is mounted before invoking `Toast.show()` / `Toast.hide()` See migration guides for complete instructions: - [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0220-to-0230) ### ✅ Checklist - [x] Changelogs updated with human-readable descriptions - [x] Changelog validation passed (`yarn workspace <package> changelog:validate`) - [x] Version bumps follow semantic versioning - [x] design-system-shared: minor (`0.15.0` → `0.16.0`) - new shared `Input`, `AvatarGroup`, and icon exports - [x] design-system-react: minor (`0.20.0` → `0.21.0`) - new modal components, icon, and shared API alignment - [x] design-system-react-native: minor (`0.22.0` → `0.23.0`) - breaking Toast redesign, icon, and shared API alignment - [x] design-system-tailwind-preset: minor (`0.6.1` → `0.7.0`) - new `fade-in` utility and Tailwind CSS v4 migration guidance - [x] design-tokens: minor (`8.3.0` → `8.4.0`) - Tailwind CSS v4 `theme.css` export - [x] Breaking changes documented with migration guidance - [x] Migration guides updated with before/after examples (if breaking changes) - [x] PR references included in changelog entries ## **Pre-merge author checklist** - [ ] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) - [ ] I've reviewed the [Release Workflow](./.cursor/rules/release-workflow.md) cursor rule - [ ] All tests pass (`yarn build && yarn test && yarn lint`) - [x] Changelog validation passes (`yarn changelog:validate`) ## **Pre-merge reviewer checklist** - [ ] I've reviewed the [Reviewing Release PRs](./docs/reviewing-release-prs.md) guide - [ ] Package versions follow semantic versioning - [ ] Changelog entries are consumer-facing (not commit message regurgitation) - [ ] Breaking changes are documented in MIGRATION.md with examples - [ ] All unreleased changes are accounted for in changelogs

feat: ModalOverlay migration

13ac07b

kirillzyusko self-assigned this Apr 28, 2026

kirillzyusko added 3 commits April 28, 2026 14:39

fix: include tokens in dev deps to successfully build projects in iso…

99b6ee6

…lated CI

fix: include tokens in dev deps to successfully build projects in iso…

badcc46

…lated CI

fix: give up and inline the constant

61e057a

fix: types issue

0b6252a

fix: lint

2fd397b

kirillzyusko marked this pull request as ready for review April 28, 2026 13:07

kirillzyusko requested a review from a team as a code owner April 28, 2026 13:07

georgewrmarshall requested changes Apr 29, 2026

View reviewed changes

fix: PR comments

49c77bf

kirillzyusko requested a review from georgewrmarshall April 29, 2026 11:17

kirillzyusko changed the title ~~feat: ModalOverlay migration (extension)~~ [3/N] feat: ModalOverlay migration (extension) Apr 30, 2026

kirillzyusko changed the title ~~[3/N] feat: ModalOverlay migration (extension)~~ [1/N] feat: ModalOverlay migration (extension) Apr 30, 2026

georgewrmarshall approved these changes Apr 30, 2026

View reviewed changes

Merge branch 'main' into feat/modal-overlay-migration

9dae9ab

kirillzyusko enabled auto-merge (squash) April 30, 2026 20:34

kirillzyusko merged commit 842d29d into main Apr 30, 2026
44 checks passed

kirillzyusko deleted the feat/modal-overlay-migration branch April 30, 2026 20:38

georgewrmarshall mentioned this pull request May 5, 2026

Release 38.0.0 #1156

Merged

20 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[1/N] feat: `ModalOverlay` migration (extension)#1120

[1/N] feat: `ModalOverlay` migration (extension)#1120
kirillzyusko merged 8 commits intomainfrom
feat/modal-overlay-migration

kirillzyusko commented Apr 28, 2026 •

edited by cursor Bot

Loading

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

georgewrmarshall left a comment

Uh oh!

georgewrmarshall Apr 29, 2026

Uh oh!

georgewrmarshall Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026

Uh oh!

georgewrmarshall left a comment

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Migration Guide

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

Uh oh!

Conversation

kirillzyusko commented Apr 28, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

georgewrmarshall left a comment

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 29, 2026

📖 Storybook Preview

Uh oh!

georgewrmarshall left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 30, 2026

📖 Storybook Preview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kirillzyusko commented Apr 28, 2026 •

edited by cursor Bot

Loading

georgewrmarshall Apr 29, 2026 •

edited

Loading