MetaMask / MetaMask/metamask-extension
Replace deprecated extension UI components with MMDS components
- Dominant language
- TypeScript
- Stars
- 13.2k
- Forks
- 5.6k
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 451
Description
## Goal
Migrate deprecated extension UI component usages to MMDS components from `@metamask/design-system-react`, in small easy-to-review PRs.
This is an evergreen tracker. Do not try to complete every deprecated usage in one PR.
## Visual Evidence Is Required
Before/after visual assets are the key output of this automation.
Every PR must include visual evidence for the changed UI so reviewers can confirm there was no regression without manually rebuilding the branch.
Required:
- A **before** screenshot from current `main`.
- An **after** screenshot from the PR branch.
- A short note identifying the route, Storybook story, state setup, or `mm` flow used to capture the screenshots.
- Screenshots must show the migrated component in context, not only a cropped DOM fragment or isolated code diff.
Preferred:
- Use the MetaMask visual-testing skill or `mm` flow. Repo guidance lives in `test/e2e/playwright/llm-workflow/`.
- Use the same viewport, state, account, network, and route for before and after screenshots.
- Include any relevant interaction state if the migrated component has hover, disabled, loading, selected, expanded, or error states.
Fallback:
- If the UI is unreachable or dead code, the PR must include `rg` evidence proving that and explain why screenshots cannot be captured.
- Dead-code evidence is a fallback, not a replacement for screenshots when a visual path exists.
PRs without screenshots or clear unreachable/dead-code evidence do not satisfy this issue.
## Agent Instructions
1. Pick one product file by default.
2. Start in `ui/pages` first, then work outward into directly used child components only when needed to complete the selected page-level migration.
3. In the selected file, migrate all deprecated extension UI components that have MMDS replacements.
4. Use `@metamask/design-system-react` as the destination.
5. Do not migrate from `ui/components/ui/*` to `ui/components/component-library/*` when an MMDS replacement exists.
6. Link the PR with `Part of #43340`, not `Fixes`, `Closes`, or `Resolves`.
Up to three product files may be included only when they are tightly related, low risk, and keep the diff small.
## Product File Selection Priority
Start with page-level files because they are closer to user-facing flows and usually easier to validate visually.
Priority order:
1. `ui/pages/home`
2. `ui/pages/asset`
3. `ui/pages/confirmations`
4. `ui/pages/permissions-connect`
5. Other high-traffic files under `ui/pages`
6. Direct child components used by those pages, when the page migration requires it
7. Broader shared components only after page-level opportunities are exhausted
Prefer files that:
- are reachable with `mm`, Storybook, or an existing test flow
- have existing Jest tests or nearby test coverage
- contain multiple deprecated MMDS-replaceable usages in one file
- can be migrated without broad snapshot churn
Avoid starting with:
- stories-only files
- tests-only files
- dead or orphaned routes
- components that are themselves deprecated wrappers
- files whose main purpose is to expose the old component-library API, constants, or types
- shared component-library implementation files such as `ui/components/component-library/*`
Be especially careful with files that re-export or adapt old component-library APIs and types. Do not change those public APIs as part of this tracker unless the PR explicitly scopes and validates that compatibility change. Prefer migrating product usage sites instead.
## Find Eligible Components
Use these sources in order:
1. MetaMask shared UI guidance:
- Run `yarn skills` if skills are not synced.
- Read `.skills-cache/metamask-skills/domains/ui/skills/ui-development/repos/metamask-extension.md`.
2. MMDS migration guide:
- https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md
3. Deprecated component search:
- `rg "@deprecated|@metamask/design-system-react" ui/components/component-library`
4. Installed MMDS types if docs are incomplete:
- `node_modules/@metamask/design-system-react/dist/components`
- `node_modules/@metamask/design-system-react/dist/types`
Good candidates include `AvatarBase`, `AvatarFavicon`, `AvatarIcon`, `AvatarNetwork`, `AvatarToken`, `BadgeWrapper`, `BannerAlert`, `BannerBase`, `Box`, `Button`, `ButtonBase`, `ButtonIcon`, `ButtonPrimary`, `ButtonSecondary`, `ButtonLink`, `Checkbox`, `Icon`, `Input`, and `Text`.
For `ButtonLink` or link-style button behavior, use the documented MMDS alternative such as `TextButton` or `Button` with the correct variant.
## Implementation Rules
- Follow the `ui-development` skill hierarchy: prefer `@metamask/design-system-react` first.
- Use MMDS components, props, constants, and types where available.
- Use `Box` for layout where appropriate and `Text` for typography.
- Prefer Tailwind classes and design-system props.
- Do not add new SASS.
- Audit props and types; this is not an import-only migration.
- Replace incompatible legacy props with supported MMDS props or Tailwind `className` utilities.
- Do not add broad `any`, unsafe casts, or type suppressions.
- Keep unrelated refactors, broad style cleanups, dependency changes, and compatibility-layer changes out of scope.
## Required Validation
- Capture before/after screenshots or provide clear unreachable/dead-code evidence as described above.
- Run `yarn lint:changed:fix` before opening or updating the PR.
- Run relevant Jest tests for touched files.
- Use the MetaMask visual-testing skill or `mm` flow when available. Repo guidance lives in `test/e2e/playwright/llm-workflow/`.
## Acceptance Criteria
- Selected product file no longer imports eligible deprecated extension UI components that have MMDS replacements.
- Selected product file imports replacement components, constants, and types from `@metamask/design-system-react`.
- Deprecated props, enum values, variants, sizes, styling props, and types are migrated using the MMDS migration guide, installed MMDS types, and the `ui-development` skill.
- No deprecated wrapper/component implementation files are migrated unless explicitly required by the selected product usage.
- Old component-library public API/type compatibility layers are not changed unless explicitly scoped and validated.
- No new SASS is added.
- No new unsafe casts, broad `any`, or type suppressions are added.
- PR scope is one product file by default, or up to three tightly related low-risk product files.
- PR links this issue with `Part of #43340`.
- Relevant tests and `yarn lint:changed:fix` pass.
- Before/after screenshots are included for reachable UI with matching context, or dead-code/unreachable UI evidence is provided.
If these criteria are not met, PRs may be closed.
## References
- Prior focused trackers: #17670, #18896, #19526
- Slack initiative: `#ai-bug-fixes`
Contributor guide
Research direction
Start in ui/pages/home and inspect eligible usages with the provided rg command; read the MMDS migration guide, the ui-development skill, and installed component types before choosing one reachable product file. Migrate that file's deprecated components, validate with relevant Jest tests and yarn lint:changed:fix, and provide matching before/after screenshots or documented dead-code evidence.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- design, frontend, testing
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100