docs: add component-migration.md cursor rule by georgewrmarshall · Pull Request #946 · MetaMask/metamask-design-system

georgewrmarshall · 2026-02-26T16:17:39Z

Description

Adds component-migration.md cursor rule providing the PRIORITY workflow for bringing components from MetaMask extension or mobile codebases into the design system monorepo. This is the primary workflow AI agents should use for component work, as most components originate from consumer applications rather than being created from scratch.

Complete migration workflow documented:

Assess component - Determine if extension/mobile component is suitable for design system
Scaffold - Use create-component:react and create-component:react-native scripts
Extract implementation - Preserve logic, behavior, and tests from source
Create shared types - Move to @metamask/design-system-shared (ADR-0004)
Transform code - Replace raw elements with Box/Text primitives and design tokens
Implement both platforms - Ensure cross-platform consistency
Create documentation - Storybook stories and README files
Verify quality - Build, test, lint must pass

Critical patterns:

Two-file export structure: .types.ts imports only, index.ts exports only
Shared types in @metamask/design-system-shared package (ADR-0004)
Const objects with as const instead of TypeScript enums (ADR-0003)
Cross-platform consistency between React and React Native
References component-creation.md for technical scaffolding details

When to use this workflow:
✅ Bringing component from extension or mobile (PRIORITY)
✅ Component exists in consumer app but not in design system
✅ User references extension or mobile component

NOT for:
❌ Brand new components with no prior implementation (use component-creation.md)
❌ Internal monorepo refactoring (use component-enum-union-migration.md)

Why this matters:
Most design system components originate from MetaMask extension or mobile applications. This workflow ensures proper migration that maintains functionality while adopting design system patterns. The BadgeCount migration (PR #942) validated these patterns, particularly the importance of correct export structure for test coverage.

Relationship to other rules:

Depends on: component-architecture.md (foundational patterns)
Uses: component-creation.md (references for technical scaffolding steps)
Different from: component-enum-union-migration.md (internal refactoring only)

References:

Golden path: BadgeStatus component (complete implementation)
Validation: BadgeCount PR refactor: migrate BadgeCount to union and shared types #942 (demonstrated coverage issue and fix)
Scripts: create-component:react and create-component:react-native

Related issues

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

Manual testing steps

Review the cursor rule file: .cursor/rules/component-migration.md
Verify it clearly marks this as PRIORITY workflow for extension/mobile components
Check workflow steps are comprehensive (assess → scaffold → extract → transform → implement)
Confirm it references component-creation.md for scaffolding details
Verify it clarifies when NOT to use this workflow
Check golden path examples reference BadgeStatus
Confirm verification checklist covers assessment, implementation, and quality
Verify CLAUDE.md includes reference to this new rule
Confirm it references BadgeCount PR refactor: migrate BadgeCount to union and shared types #942

Screenshots/Recordings

N/A - Documentation only

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 (N/A - documentation)
I've documented my code using JSDoc format if applicable (N/A - markdown)
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

Low Risk
Low risk documentation-only change that adds guidance for future migrations without altering runtime code or build behavior.

Overview
Adds a new Cursor rule, .cursor/rules/component-migration.md, documenting the primary workflow for migrating components from MetaMask Extension/Mobile into the monorepo, including audit steps, shared-type layering guidance, conservative vs unified alignment strategies, and verification checklists.

Updates CLAUDE.md to reference this new rule in the list of AI-agent conventions.

^{Written by Cursor Bugbot for commit d8b8736. This will update automatically on new commits. Configure here.}

github-actions · 2026-02-26T16:18:58Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-02-27T02:20:31Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-02-27T15:52:48Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-02-27T21:02:04Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall · 2026-03-03T21:26:23Z

+
+Guide for migrating components from MetaMask Extension and Mobile component-library folders into the design system monorepo.
+
+## Purpose


This cursor rule defines the PRIMARY workflow for migrating components from Extension and Mobile component-library folders. It addresses the most common development task: consolidating existing consumer components into the monorepo while applying ADR-0003/0004 patterns.

georgewrmarshall · 2026-03-03T21:26:30Z

+
+- **Conservative:** Accept partial alignment, document gaps for Phase 2
+- **Unified:** Consolidate props immediately with `@deprecated` transition
+


Two migration strategies accommodate different scenarios: Conservative approach defers breaking changes for components with high usage (accepting partial alignment initially), while Unified approach consolidates props immediately for low-usage components (using @deprecated for graceful migration).

georgewrmarshall · 2026-03-03T21:26:36Z

+- Brand new components from scratch → @.cursor/rules/component-creation.md
+
+## Migration Strategy Decision
+


Decision tree helps AI agents choose the appropriate strategy based on component usage level and whether consumers can be updated in the same PR. This prevents unnecessary breaking changes while allowing consolidation when feasible.

github-actions · 2026-03-03T21:26:40Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall · 2026-03-03T21:26:41Z

+   - Which props are platform-specific? (onClick/onPress, className/twClassName)
+   - Are there naming conflicts? (disabled vs isDisabled)
+   - What's the unified API that serves both platforms?
+


Prop alignment principles explicitly permit partial alignment. Shared types are created for any matching props, even minimal overlap, while accepting platform-specific differences. This pragmatic approach balances consistency with platform idioms.

georgewrmarshall · 2026-03-03T21:26:46Z

+- Event handlers from base types (onClick/onPress)
+
+### Phase 2.5: Implementation Patterns
+


Conservative approach pattern provides concrete examples of documenting alignment gaps. GitHub issues track Phase 2 work for future major version upgrades, preventing migration blockers while maintaining clear technical debt visibility.

georgewrmarshall · 2026-03-03T21:26:52Z

+Labels: phase-2, alignment, breaking-change
+```
+
+#### Unified Approach Pattern


Unified approach pattern demonstrates complete migration workflow with deprecation strategy. JSDoc @deprecated tags provide IDE warnings, effectiveDisabled pattern maintains backwards compatibility, and migration map guides consumers through prop changes.

georgewrmarshall · 2026-03-03T21:26:58Z

+3. Tests (props render, variants apply, interactive states work)
+4. Figma Code Connect (if applicable) - see @.cursor/rules/figma-integration.md
+
+**React:** README.mdx with Canvas blocks


Anti-patterns section targets common AI agent mistakes observed during component migrations. Each example contrasts wrong approach (direct copy, hardcoded values, platform props in shared) with correct monorepo patterns to prevent repeated errors.

georgewrmarshall · 2026-03-03T21:27:03Z

+
+// ✅ Correct - className only in platform package
+export type ButtonPropsShared = {
+  variant?: ButtonVariant;


Comprehensive verification checklist ensures AI agents complete all migration phases. Covers audit, API design, implementation, documentation, and build verification with concrete checklist items for both conservative and unified approaches.

georgewrmarshall · 2026-03-03T21:27:11Z

+
+- [ ] Storybook stories, README, tests for both platforms
+- [ ] Figma Code Connect (if applicable)
+- [ ] Migration documented in centralized MIGRATION.md (preferred)


References section provides structured navigation to all related documentation. Links to required reading (architecture, creation, styling, documentation rules), migration strategy docs, source repositories, ADRs, and MetaMask contributor standards guide agents to comprehensive context.

georgewrmarshall · 2026-03-03T21:27:21Z

 - @.cursor/rules/component-architecture.md
 - @.cursor/rules/component-creation.md
 - @.cursor/rules/component-enum-union-migration.md
+- @.cursor/rules/component-migration.md


CLAUDE.md update adds component-migration.md to the cursor rules list, ensuring AI agents automatically load this PRIMARY workflow for bringing Extension and Mobile components into the monorepo. Positioned after component-enum-union-migration.md to maintain logical ordering.

github-actions · 2026-03-03T22:57:11Z

📖 Storybook Preview

View PR Storybook

## Description - migrate MainActionButton from MetaMask Mobile component-library temp components into @metamask/design-system-react-native - add component source, types, constants, styles, stories, tests, and README under packages/design-system-react-native/src/components/MainActionButton - export MainActionButton from RN components barrel ## Related issue - https://consensyssoftware.atlassian.net/browse/DSYS-296 ## Screenshots ### Mobile https://github.com/user-attachments/assets/7f8cc1d5-f829-4308-8415-c3a2f622ca8c ### MMDS https://github.com/user-attachments/assets/bcc0e97c-9ffa-4552-83a6-aea3ae625461 ## Notes - migration followed the component migration rule from PR #946 and existing component creation/documentation/styling rules in this repo  --- > [!NOTE] > **Low Risk** > Low risk: primarily adds a new UI component and Storybook/test coverage with minimal impact on existing runtime logic aside from a new public export. > > **Overview** > Introduces `MainActionButton` into `@metamask/design-system-react-native`, implementing the component (press/disabled behavior, Tailwind-based styling, icon+single-line label) along with `MainActionButtonProps`, README documentation, Storybook stories, and a test suite. > > Updates the RN components barrel export and Storybook requires list to surface the new stories, and makes a tiny cleanup in `TabEmptyState` Storybook story (removes an eslint-disable comment). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit a19f71a. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>

georgewrmarshall force-pushed the docs/component-migration-cursor-rule branch from 2dd5a84 to cbd95ff Compare February 27, 2026 02:19

georgewrmarshall force-pushed the docs/component-migration-cursor-rule branch from 25957ad to 7d17b72 Compare February 27, 2026 21:00

georgewrmarshall mentioned this pull request Mar 3, 2026

feat: migrate MainActionButton to design-system-react-native #952

Merged

georgewrmarshall force-pushed the docs/component-migration-cursor-rule branch from 75dd567 to 26fd0a6 Compare March 3, 2026 21:24

docs: component migration cursor rule

03c1bb5

georgewrmarshall force-pushed the docs/component-migration-cursor-rule branch from 26fd0a6 to 03c1bb5 Compare March 3, 2026 21:25

georgewrmarshall commented Mar 3, 2026

View reviewed changes

georgewrmarshall marked this pull request as ready for review March 3, 2026 21:27

georgewrmarshall requested a review from a team as a code owner March 3, 2026 21:27

georgewrmarshall commented Mar 3, 2026

View reviewed changes

brianacnguyen approved these changes Mar 3, 2026

View reviewed changes

georgewrmarshall enabled auto-merge (squash) March 3, 2026 22:55

Merge branch 'main' into docs/component-migration-cursor-rule

d8b8736

georgewrmarshall merged commit ed7f1e5 into main Mar 3, 2026
43 checks passed

georgewrmarshall deleted the docs/component-migration-cursor-rule branch March 3, 2026 22:59


		Guide for migrating components from MetaMask Extension and Mobile component-library folders into the design system monorepo.

		## Purpose


		- Conservative: Accept partial alignment, document gaps for Phase 2
		- Unified: Consolidate props immediately with `@deprecated` transition

		- Brand new components from scratch → @.cursor/rules/component-creation.md

		## Migration Strategy Decision

		- Event handlers from base types (onClick/onPress)

		### Phase 2.5: Implementation Patterns

Uh oh!

Conversation

georgewrmarshall commented Feb 26, 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

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

github-actions Bot commented Feb 26, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Feb 27, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Feb 27, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Feb 27, 2026

📖 Storybook Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 3, 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!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 3, 2026

📖 Storybook Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 3, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 3, 2026

📖 Storybook Preview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

georgewrmarshall commented Feb 26, 2026 •

edited by cursor Bot

Loading

georgewrmarshall Mar 3, 2026 •

edited

Loading

georgewrmarshall Mar 3, 2026 •

edited

Loading