MetaMask / MetaMask/metamask-design-system
[Docs] Add migration documentation for priority components
- 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
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