MetaMask / MetaMask/metamask-design-system

[Docs] Add migration documentation for priority components

Open
#989 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
TypeScript
Stars
37
Forks
14
Avg merge
1d 9h
Merged PRs (30d)
60

Description

## Summary

Add migration documentation for components that have been migrated from Extension/Mobile component-libraries to MMDS. This is documentation work for already-migrated components.

## Definition of Done

1. **MIGRATION.md sections**: Add component sections with API maps to:
- `packages/design-system-react/MIGRATION.md`
- `packages/design-system-react-native/MIGRATION.md`

2. **README links**: Add migration section to each component's README.mdx:
- Link to relevant MIGRATION.md section

3. **@deprecated updates**: Add migration links to JSDoc in:
- Extension: `ui/components/component-library/[component]`
- Mobile: `app/component-library/components/[component]`

## Components to Document

### High Priority (most aligned, stable APIs)

| Component | React | React Native | Extension Source | Mobile Source |
|-----------|-------|--------------|-------------------|---------------|
| **Avatar family** (7) | ❌ | ❌ | ✅ @deprecated | ✅ @deprecated |
| **Badge family** (5) | ❌ | ❌ | ✅ @deprecated | ✅ @deprecated |
| **Button** | ❌ | ❌ | ✅ @deprecated | ❌ |
| **ButtonBase** | ❌ | ❌ | ✅ @deprecated | ❌ |
| **Checkbox** | ❌ | ❌ | ✅ @deprecated | ❌ |
| **TextButton** | ❌ | ❌ | ✅ @deprecated | ❌ |
| **BannerBase** | ❌ | ❌ | ❌ | ❌ |

### Existing (need README links check)

| Component | MIGRATION.md | README Link | Notes |
|-----------|--------------|-------------|-------|
| Box | ✅ React + RN | ❓ | Check if link exists |
| BannerAlert | ✅ React + RN | ❓ | Check if link exists |
| Text | ✅ React + RN | ✅ | Link exists |
| Icon | ✅ React + RN | ✅ | Link exists |

## Migration Guide Template

Each component section should include:

```markdown
### [ComponentName] Component

The [ComponentName] component has [X] breaking changes when migrating from the [Extension|Mobile] component-library.

#### Breaking Changes

##### [Change 1]
| Extension Pattern | Design System Migration |
|------------------|------------------------|
| ... | ... |

#### Migration Example

##### Before (Extension/Mobile)
\`\`\`tsx
// old import and usage
\`\`\`

##### After (Design System)
\`\`\`tsx
// new import and usage
\`\`\`
```

## Example References

- Text component migration: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#text-component
- Box component migration: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#box-component

## Labels
documentation

## Related
- Epic: DSYS-272 (Extension)
- Epic: DSYS-302 (Mobile)

Contributor guide

Open the contributing guide

Research direction

Start with the existing Text and Box sections in packages/design-system-react/MIGRATION.md and packages/design-system-react-native/MIGRATION.md, then inspect the listed component README.mdx files and deprecated Extension and Mobile component paths. Document the priority components using the migration template, add README links and JSDoc migration links, and verify existing Box and BannerAlert links.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
design, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.