From e35d4bd5a99f488e733e54cc072f5aa6dba103e3 Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Mon, 23 Mar 2026 16:32:57 -0700 Subject: [PATCH 01/13] docs: add component migration tracking documentation - Add component-migration-project.md with project overview and status - Add extension-migration-tracker.md with Extension component status - Add mobile-migration-tracker.md with Mobile component status - Add jira-ticket-creation.md with ticket creation workflows - Add component-migration-tracking.md cursor rule for tracking workflow --- .cursor/rules/component-migration-tracking.md | 227 ++++++++++++ docs/component-migration-project.md | 173 +++++++++ docs/extension-migration-tracker.md | 154 ++++++++ docs/jira-ticket-creation.md | 350 ++++++++++++++++++ docs/mobile-migration-tracker.md | 200 ++++++++++ 5 files changed, 1104 insertions(+) create mode 100644 .cursor/rules/component-migration-tracking.md create mode 100644 docs/component-migration-project.md create mode 100644 docs/extension-migration-tracker.md create mode 100644 docs/jira-ticket-creation.md create mode 100644 docs/mobile-migration-tracker.md diff --git a/.cursor/rules/component-migration-tracking.md b/.cursor/rules/component-migration-tracking.md new file mode 100644 index 000000000..1b8c18030 --- /dev/null +++ b/.cursor/rules/component-migration-tracking.md @@ -0,0 +1,227 @@ +# Component Migration Tracking + +Guide for tracking component migrations and updating Jira tickets during the migration process. + +## Purpose + +**This rule** provides guidance for: + +- Tracking migration progress in the migration trackers +- Creating Jira tickets for new migrations +- Updating existing tickets with PR links and status + +**NOT for:** + +- Actually implementing the migration (see @.cursor/rules/component-migration.md) + +## When to Use This + +Use this rule when: + +- Starting a new component migration +- Updating migration progress +- Creating adoption tickets for extension/mobile + +## Migration Trackers + +### Extension Tracker + +`docs/extension-migration-tracker.md` + +### Mobile Tracker + +`docs/mobile-migration-tracker.md` + +### Project Overview + +`docs/component-migration-project.md` + +## Workflow + +### 1. Starting a New Migration + +When starting a new component migration: + +```bash +# 1. Update the tracker to mark component as "In Progress" +# Edit docs/extension-migration-tracker.md or docs/mobile-migration-tracker.md + +# 2. Create Jira ticket +gh issue create \ + --title "Migrate [ComponentName] to MMDS" \ + --body "$(cat <<'EOF' +## Summary +Migrate [ComponentName] from [Extension|Mobile] component-library to MMDS + +## Details +- **Source:** ui/components/component-library/[path]/ +- **Target:** @metamask/design-system-[react|react-native] +- **Epic:** [DSYS-272|DSYS-302] + +## Acceptance Criteria +- [ ] Shared types created in design-system-shared +- [ ] React implementation complete +- [ ] React Native implementation complete (if applicable) +- [ ] Storybook stories added +- [ ] Figma Code Connect files added (if applicable) +- [ ] Tests added +- [ ] Migration guide added to package MIGRATION.md +- [ ] Adoption ticket created for [Extension|Mobile] +EOF +)" \ + --label "component-migration" \ + --label "needs-pr" \ + --project "Design System" +``` + +### 2. Updating Progress + +When the migration is complete: + +```bash +# 1. Update tracker status to "Migrated" +# Edit the appropriate tracker file + +# 2. Update Jira ticket with PR link +gh issue close [ticket-number] +# or +gh issue edit [ticket-number] --add-label "done" +``` + +### 3. Creating Adoption Tickets + +After migration is complete, create tickets for adoption in extension/mobile: + +```bash +# Extension Adoption Ticket +gh issue create \ + --title "[Extension] Adopt [ComponentName] from MMDS" \ + --body "$(cat <<'EOF' +## Summary +Replace [ComponentName] in extension with @metamask/design-system-react + +## Migration Guide +See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#[component] + +## Replacement +- Old: import from '../../component-library/[component]' +- New: import from '@metamask/design-system-react' + +## Components to Update +[List all files that need updating] + +## Verification +- [ ] All imports updated +- [ ] Tests pass +- [ ] No TypeScript errors +- [ ] Storybook renders correctly +EOF +)" \ + --label "adoption" \ + --label "extension" + +# Mobile Adoption Ticket +gh issue create \ + --title "[Mobile] Adopt [ComponentName] from MMDS" \ + --body "$(cat <<'EOF' +## Summary +Replace [ComponentName] in mobile with @metamask/design-system-react-native + +## Migration Guide +See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#[component] + +## Replacement +- Old: import from '../../../component-library/components/[ComponentPath]' +- New: import from '@metamask/design-system-react-native' + +## Platforms +- [ ] iOS +- [ ] Android + +## Verification +- [ ] All imports updated +- [ ] Tests pass +- [ ] No TypeScript errors +- [ ] Renders correctly on both platforms +EOF +)" \ + --label "adoption" \ + --label "mobile" +``` + +## Jira API Alternative + +If using the Jira API directly: + +```bash +# Get auth token from environment or config +JIRA_TOKEN="your-token" +JIRA_BASE_URL="https://consensyssoftware.atlassian.net" + +# Create issue under epic +curl -X POST \ + -H "Authorization: Bearer $JIRA_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "fields": { + "project": {"key": "DSYS"}, + "summary": "Migrate ComponentName to MMDS", + "description": { + "type": "doc", + "version": 1, + "content": [ + { + "type": "paragraph", + "content": [ + {"type": "text", "text": "Migration details..."} + ] + } + ] + }, + "issuetype": {"name": "Task"}, + "parent": {"key": "DSYS-272"}, + "labels": ["component-migration"] + } + }' \ + "$JIRA_BASE_URL/rest/api/3/issue" +``` + +## Tracker Update Checklist + +When marking a component as migrated, update ALL of: + +- [ ] `docs/component-migration-project.md` - Main tracker table +- [ ] `docs/extension-migration-tracker.md` OR `docs/mobile-migration-tracker.md` - Platform-specific tracker +- [ ] `packages/design-system-react/MIGRATION.md` OR `packages/design-system-react-native/MIGRATION.md` - Package migration guide +- [ ] Jira ticket - Update with PR link and close/complete + +## Quick Commands + +```bash +# Check if component is in trackers +grep -i "ComponentName" docs/*-migration-tracker.md docs/component-migration-project.md + +# List all migration tickets +gh issue list --label "component-migration" --state all + +# List adoption tickets +gh issue list --label "adoption" --state all + +# View epic progress +# DSYS-272: https://consensyssoftware.atlassian.net/browse/DSYS-272 +# DSYS-302: https://consensyssoftware.atlassian.net/browse/DSYS-302 +``` + +## Epic Links + +| Platform | Epic | URL | +| --------- | -------- | ------------------------------------------------------- | +| Extension | DSYS-272 | https://consensyssoftware.atlassian.net/browse/DSYS-272 | +| Mobile | DSYS-302 | https://consensyssoftware.atlassian.net/browse/DSYS-302 | + +## Related Documentation + +- @.cursor/rules/component-migration.md - Component migration implementation +- @docs/component-migration-project.md - Project overview +- @docs/extension-migration-tracker.md - Extension component tracker +- @docs/mobile-migration-tracker.md - Mobile component tracker diff --git a/docs/component-migration-project.md b/docs/component-migration-project.md new file mode 100644 index 000000000..960e7cb32 --- /dev/null +++ b/docs/component-migration-project.md @@ -0,0 +1,173 @@ +# Component Migration Project + +**Status:** Active +**Epic - Extension:** [DSYS-272](https://consensyssoftware.atlassian.net/browse/DSYS-272) +**Epic - Mobile:** [DSYS-302](https://consensyssoftware.atlassian.net/browse/DSYS-302) +**Last Updated:** 2026-03-23 + +## Overview + +This document tracks the comprehensive component migration from MetaMask Extension and Mobile component-libraries into the MetaMask Design System (MMDS) monorepo. + +## Migration Scope + +### Extension Components + +**Source:** [metamask-extension/ui/components/component-library](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) +**Target:** `@metamask/design-system-react` +**Epic:** DSYS-272 + +| Component | Status | Replacement | Jira Ticket | Notes | +| ------------- | -------------- | ----------- | ----------- | -------------------------------------------------------------------------------------- | +| BannerAlert | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#banneralert-component) | +| Box | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#box-component) | +| Button | πŸ”„ In Progress | - | - | - | +| ButtonBase | πŸ”„ In Progress | - | - | - | +| ButtonIcon | βœ… Migrated | - | - | - | +| Checkbox | πŸ”„ In Progress | - | - | - | +| Icon | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#icon-component) | +| Text | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#text-component) | +| TextButton | πŸ”„ In Progress | - | - | - | +| AvatarAccount | ⬜ Pending | - | - | - | +| AvatarBase | ⬜ Pending | - | - | - | +| AvatarFavicon | ⬜ Pending | - | - | - | +| AvatarGroup | ⬜ Pending | - | - | - | +| AvatarIcon | ⬜ Pending | - | - | - | +| AvatarNetwork | ⬜ Pending | - | - | - | +| AvatarToken | ⬜ Pending | - | - | - | +| BadgeCount | ⬜ Pending | - | - | - | +| BadgeIcon | ⬜ Pending | - | - | - | +| BadgeNetwork | ⬜ Pending | - | - | - | +| BadgeStatus | ⬜ Pending | - | - | - | +| BadgeWrapper | ⬜ Pending | - | - | - | +| BannerBase | ⬜ Pending | - | - | - | +| ButtonFilter | ⬜ Pending | - | - | - | +| ButtonHero | ⬜ Pending | - | - | - | +| Card | ⬜ Pending | - | - | - | +| HeaderBase | ⬜ Pending | - | - | - | +| Input | ⬜ Pending | - | - | - | +| Label | ⬜ Pending | - | - | - | +| ListItem | ⬜ Pending | - | - | - | +| Modal | ⬜ Pending | - | - | - | +| RadioButton | ⬜ Pending | - | - | - | +| SearchToken | ⬜ Pending | - | - | - | +| SensitiveText | ⬜ Pending | - | - | - | +| Skeleton | ⬜ Pending | - | - | - | +| Tag | ⬜ Pending | - | - | - | +| TextField | ⬜ Pending | - | - | - | +| Tooltip | ⬜ Pending | - | - | - | + +### Mobile Components + +**Source:** [metamask-mobile/app/component-library](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) +**Target:** `@metamask/design-system-react-native` +**Epic:** DSYS-302 + +| Component | Status | Replacement | Jira Ticket | Notes | +| ------------------ | -------------- | ----------- | ----------- | --------------------------------------------------------------------------------------------- | +| BannerAlert | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#banneralert-component) | +| Box | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#box-component) | +| Button | πŸ”„ In Progress | - | - | - | +| ButtonBase | πŸ”„ In Progress | - | - | - | +| ButtonIcon | βœ… Migrated | - | - | - | +| Checkbox | πŸ”„ In Progress | - | - | - | +| Icon | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#icon-component) | +| Text | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#text-component) | +| TextButton | πŸ”„ In Progress | - | - | - | +| AvatarAccount | ⬜ Pending | - | - | - | +| AvatarBase | ⬜ Pending | - | - | - | +| AvatarFavicon | ⬜ Pending | - | - | - | +| AvatarGroup | ⬜ Pending | - | - | - | +| AvatarIcon | ⬜ Pending | - | - | - | +| AvatarNetwork | ⬜ Pending | - | - | - | +| AvatarToken | ⬜ Pending | - | - | - | +| BadgeCount | ⬜ Pending | - | - | - | +| BadgeIcon | ⬜ Pending | - | - | - | +| BadgeNetwork | ⬜ Pending | - | - | - | +| BadgeStatus | ⬜ Pending | - | - | - | +| BadgeWrapper | ⬜ Pending | - | - | - | +| BannerBase | ⬜ Pending | - | - | - | +| BottomSheet | ⬜ Pending | - | - | - | +| BottomSheetDialog | ⬜ Pending | - | - | - | +| BottomSheetFooter | ⬜ Pending | - | - | - | +| BottomSheetHeader | ⬜ Pending | - | - | - | +| BottomSheetOverlay | ⬜ Pending | - | - | - | +| ButtonFilter | ⬜ Pending | - | - | - | +| ButtonHero | ⬜ Pending | - | - | - | +| ButtonSemantic | ⬜ Pending | - | - | - | +| Card | ⬜ Pending | - | - | - | +| HeaderBase | ⬜ Pending | - | - | - | +| Input | ⬜ Pending | - | - | - | +| KeyValueRow | ⬜ Pending | - | - | - | +| Label | ⬜ Pending | - | - | - | +| ListItem | ⬜ Pending | - | - | - | +| MainActionButton | ⬜ Pending | - | - | - | +| RadioButton | ⬜ Pending | - | - | - | +| SensitiveText | ⬜ Pending | - | - | - | +| Skeleton | ⬜ Pending | - | - | - | +| TabEmptyState | ⬜ Pending | - | - | - | +| TextField | ⬜ Pending | - | - | - | +| Toast | ⬜ Pending | - | - | - | + +## Status Legend + +| Symbol | Meaning | +| -------------- | --------------------------------------------------- | +| βœ… Migrated | Component migrated to MMDS, migration guide written | +| πŸ”„ In Progress | Migration currently underway | +| ⬜ Pending | Not yet started | +| ❌ Deprecated | Deprecated in source, replacement available | + +## Migration Checklist + +### Per Component (both platforms) + +- [ ] Create shared types in `packages/design-system-shared/src/types/ComponentName/` +- [ ] Create React implementation in `packages/design-system-react/src/components/ComponentName/` +- [ ] Create React Native implementation in `packages/design-system-react-native/src/components/ComponentName/` +- [ ] Add Storybook stories for both platforms +- [ ] Add Figma Code Connect files for both platforms +- [ ] Add tests for both platforms +- [ ] Update package MIGRATION.md with component-specific guide +- [ ] Create Jira ticket for adoption in Extension/Mobile +- [ ] Update this tracker with ticket number and status + +## Jira Ticket Template + +### Epic Tickets + +- **DSYS-272**: Extension Component Migration to MMDS +- **DSYS-302**: Mobile Component Migration to MMDS + +### Component Sub-task Template + +``` +## Summary +Migrate [ComponentName] from [Extension|Mobile] component-library to MMDS + +## Acceptance Criteria +- [ ] Component implemented in design-system-react (if applicable) +- [ ] Component implemented in design-system-react-native (if applicable) +- [ ] Shared types created in design-system-shared +- [ ] Storybook stories added +- [ ] Figma Code Connect files added +- [ ] Tests added +- [ ] Migration guide added to package MIGRATION.md +- [ ] Adoption ticket created for [Extension|Mobile] +``` + +## Related Documentation + +- [Component Migration Strategy](./component-migration-strategy.md) +- [React Migration Guide](../packages/design-system-react/MIGRATION.md) +- [React Native Migration Guide](../packages/design-system-react-native/MIGRATION.md) +- [Component Migration Cursor Rule](../.cursor/rules/component-migration.md) +- [Migration Tracking Cursor Rule](../.cursor/rules/component-migration-tracking.md) + +## References + +- [ADR-0003: Enum to String Union Migration](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0003-enum-to-string-union-migration.md) +- [ADR-0004: Centralized Types Architecture](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0004-centralized-types-architecture.md) +- [Extension component-library](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) +- [Mobile component-library](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) +- [MMDS Monorepo](https://github.com/MetaMask/metamask-design-system) diff --git a/docs/extension-migration-tracker.md b/docs/extension-migration-tracker.md new file mode 100644 index 000000000..97456b668 --- /dev/null +++ b/docs/extension-migration-tracker.md @@ -0,0 +1,154 @@ +# Extension Component Migration Tracker + +**Source:** [metamask-extension/ui/components/component-library](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) +**Target:** `@metamask/design-system-react` +**Epic:** [DSYS-272](https://consensyssoftware.atlassian.net/browse/DSYS-272) +**Last Updated:** 2026-03-23 + +## Summary + +| Status | Count | +| -------------- | ------ | +| βœ… Migrated | 5 | +| πŸ”„ In Progress | 4 | +| ⬜ Pending | 26 | +| **Total** | **35** | + +## βœ… Migrated Components + +These components have been migrated to MMDS and have migration guides. + +| Component | MMDS Location | Migration Guide | Notes | +| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------- | +| BannerAlert | `packages/design-system-react/src/components/BannerAlert/` | [Guide](../packages/design-system-react/MIGRATION.md#banneralert-component) | Severity values standardized | +| Box | `packages/design-system-react/src/components/Box/` | [Guide](../packages/design-system-react/MIGRATION.md#box-component) | Responsive spacing changed | +| ButtonIcon | `packages/design-system-react/src/components/ButtonIcon/` | [Guide](../packages/design-system-react/MIGRATION.md#from-version-0100-to-0110) | Variant prop replacement | +| Icon | `packages/design-system-react/src/components/Icon/` | [Guide](../packages/design-system-react/MIGRATION.md#icon-component) | Color enum changes | +| Text | `packages/design-system-react/src/components/Text/` | [Guide](../packages/design-system-react/MIGRATION.md#text-component) | Font weight separation | + +## πŸ”„ In Progress + +These components are currently being migrated. + +| Component | Owner | Ticket | PR | Notes | +| ---------- | ----- | ------ | --- | ----- | +| Button | - | - | - | - | +| ButtonBase | - | - | - | - | +| Checkbox | - | - | - | - | +| TextButton | - | - | - | - | + +## ⬜ Pending Components + +### Avatar Components + +| Component | Extension Path | Priority | Ticket | Notes | +| ------------- | ------------------------- | -------- | ------ | ----- | +| AvatarAccount | `avatars/avatar-account/` | Medium | - | - | +| AvatarBase | `avatars/avatar-base/` | Medium | - | - | +| AvatarFavicon | `avatars/avatar-favicon/` | Medium | - | - | +| AvatarGroup | `avatars/avatar-group/` | Medium | - | - | +| AvatarIcon | `avatars/avatar-icon/` | Medium | - | - | +| AvatarNetwork | `avatars/avatar-network/` | Medium | - | - | +| AvatarToken | `avatars/avatar-token/` | Medium | - | - | + +### Badge Components + +| Component | Extension Path | Priority | Ticket | Notes | +| ------------ | ---------------- | -------- | ------ | ----- | +| BadgeCount | `badge-count/` | Low | - | - | +| BadgeIcon | `badge-icon/` | Low | - | - | +| BadgeNetwork | `badge-network/` | Low | - | - | +| BadgeStatus | `badge-status/` | Low | - | - | +| BadgeWrapper | `badge-wrapper/` | Low | - | - | + +### Banner Components + +| Component | Extension Path | Priority | Ticket | Notes | +| ---------- | ---------------------- | -------- | ------ | ----- | +| BannerBase | `banners/banner/base/` | Medium | - | - | + +### Button Components + +| Component | Extension Path | Priority | Ticket | Notes | +| ------------ | ---------------- | -------- | ------ | ----- | +| ButtonFilter | `button-filter/` | Medium | - | - | +| ButtonHero | `button-hero/` | Medium | - | - | + +### Form Components + +| Component | Extension Path | Priority | Ticket | Notes | +| --------- | -------------------- | -------- | ------ | ----- | +| Input | `inputs/input/` | High | - | - | +| TextField | `inputs/text-field/` | High | - | - | + +### Layout Components + +| Component | Extension Path | Priority | Ticket | Notes | +| ---------- | -------------- | -------- | ------ | ----- | +| Card | `card/` | Medium | - | - | +| HeaderBase | `header/base/` | Medium | - | - | + +### Other Components + +| Component | Extension Path | Priority | Ticket | Notes | +| ------------- | -------------------- | -------- | ------ | ----- | +| Label | `label/` | Medium | - | - | +| ListItem | `list-items/` | High | - | - | +| Modal | `modal/` | High | - | - | +| RadioButton | `radio/RadioButton/` | Medium | - | - | +| SearchToken | `search-token/` | Low | - | - | +| SensitiveText | `sensitive-text/` | Low | - | - | +| Skeleton | `skeleton/` | Low | - | - | +| Tag | `tag/` | Low | - | - | +| Tooltip | `tooltip/` | Medium | - | - | + +## Migration Workflow + +### Step 1: Audit Component + +1. Locate component in extension: `ui/components/component-library/[component-path]/` +2. Document current API (props, types, variants) +3. Check if shared types already exist in `packages/design-system-shared/src/types/` + +### Step 2: Create Migration Plan + +1. Identify shared props vs platform-specific props +2. Decide on Conservative vs Unified approach +3. Create comparison table (Extension API vs MMDS patterns) + +### Step 3: Implement + +```bash +# Create component scaffolding +yarn create-component:react --name ComponentName --description "Brief description" + +# Follow component-migration.md workflow +``` + +### Step 4: Document + +1. Add migration section to `packages/design-system-react/MIGRATION.md` +2. Create adoption ticket for extension + +### Step 5: Track + +1. Update this tracker with: + - Jira ticket number + - PR link + - Migration completion date + +## Quick Reference + +| Task | Command | +| ---------------------- | ------------------------------------------------------------------- | +| Check component status | Search this file for component name | +| Update status | Edit this file and commit | +| Create ticket | Use Jira API or web UI with template | +| View epic | [DSYS-272](https://consensyssoftware.atlassian.net/browse/DSYS-272) | + +## Related Documentation + +- [Project Overview](./component-migration-project.md) +- [Migration Strategy](./component-migration-strategy.md) +- [Component Migration Cursor Rule](../.cursor/rules/component-migration.md) +- [Extension Source](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) diff --git a/docs/jira-ticket-creation.md b/docs/jira-ticket-creation.md new file mode 100644 index 000000000..d3a8b237d --- /dev/null +++ b/docs/jira-ticket-creation.md @@ -0,0 +1,350 @@ +# Jira Ticket Creation Guide + +Guide for creating and managing Jira tickets for component migrations. + +## Epic Structure + +| Platform | Epic | Key | URL | +| --------- | ----------------------------- | -------- | ------------------------------------------------------- | +| Extension | Extension Component Migration | DSYS-272 | https://consensyssoftware.atlassian.net/browse/DSYS-272 | +| Mobile | Mobile Component Migration | DSYS-302 | https://consensyssoftware.atlassian.net/browse/DSYS-302 | + +## Ticket Types + +### 1. Migration Ticket (Sub-task) + +Created under the epic when starting a component migration. + +**Template:** + +``` +Summary: Migrate [ComponentName] to MMDS +Type: Sub-task +Parent: DSYS-272 (Extension) or DSYS-302 (Mobile) +Labels: component-migration +``` + +**Acceptance Criteria:** + +``` +- [ ] Shared types created in design-system-shared +- [ ] React implementation complete (if applicable) +- [ ] React Native implementation complete (if applicable) +- [ ] Storybook stories added +- [ ] Figma Code Connect files added (if applicable) +- [ ] Tests added +- [ ] Migration guide added to package MIGRATION.md +- [ ] Adoption ticket created for [Extension|Mobile] +``` + +### 2. Adoption Ticket + +Created after migration is complete, to track adoption in the platform. + +**Template:** + +``` +Summary: [Extension|Mobile] - Adopt [ComponentName] from MMDS +Type: Task +Labels: adoption, extension OR mobile +Epic: DSYS-272 (Extension) or DSYS-302 (Mobile) +``` + +## Creating Tickets + +### Using GitHub CLI (Recommended) + +```bash +# Migration Ticket +gh issue create \ + --title "Migrate [ComponentName] to MMDS" \ + --body "$(cat <<'EOF' +## Summary +Migrate [ComponentName] from [Extension|Mobile] component-library to MMDS + +## Details +- **Source:** ui/components/component-library/[path]/ +- **Target:** @metamask/design-system-[react|react-native] +- **Epic:** DSYS-272 (Extension) or DSYS-302 (Mobile) + +## Migration Guide +See package MIGRATION.md for component-specific guidance. + +## Acceptance Criteria +- [ ] Shared types created in design-system-shared +- [ ] React implementation complete +- [ ] React Native implementation complete (if applicable) +- [ ] Storybook stories added +- [ ] Figma Code Connect files added (if applicable) +- [ ] Tests added +- [ ] Migration guide added to package MIGRATION.md +- [ ] Adoption ticket created for [Extension|Mobile] +EOF +)" \ + --label "component-migration" \ + --label "needs-pr" + +# Extension Adoption Ticket +gh issue create \ + --title "[Extension] Adopt [ComponentName] from MMDS" \ + --body "$(cat <<'EOF' +## Summary +Replace [ComponentName] in extension with @metamask/design-system-react + +## Migration Guide +See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#[component] + +## Replacement +- Old: import from '../../component-library/[component]' +- New: import from '@metamask/design-system-react' + +## Components to Update +[List all files that need updating] + +## Verification +- [ ] All imports updated +- [ ] Tests pass +- [ ] No TypeScript errors +- [ ] Storybook renders correctly +EOF +)" \ + --label "adoption" \ + --label "extension" + +# Mobile Adoption Ticket +gh issue create \ + --title "[Mobile] Adopt [ComponentName] from MMDS" \ + --body "$(cat <<'EOF' +## Summary +Replace [ComponentName] in mobile with @metamask/design-system-react-native + +## Migration Guide +See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#[component] + +## Replacement +- Old: import from '../../../component-library/components/[ComponentPath]' +- New: import from '@metamask/design-system-react-native' + +## Platforms +- [ ] iOS +- [ ] Android + +## Verification +- [ ] All imports updated +- [ ] Tests pass +- [ ] No TypeScript errors +- [ ] Renders correctly on both platforms +EOF +)" \ + --label "adoption" \ + --label "mobile" +``` + +### Using Jira REST API + +#### Authentication + +Set up your Jira API token: + +```bash +# Option 1: Environment variable +export JIRA_TOKEN="your-api-token" +export JIRA_EMAIL="your-email@consensys.net" +export JIRA_BASE_URL="https://consensyssoftware.atlassian.net" + +# Option 2: .env file (gitignored) +echo "JIRA_TOKEN=your-token" >> .env +echo "JIRA_EMAIL=your-email@consensys.net" >> .env +``` + +#### Create Migration Ticket + +```bash +curl -X POST \ + -H "Authorization: Basic $(echo -n $JIRA_EMAIL:$JIRA_TOKEN | base64)" \ + -H "Content-Type: application/json" \ + -d '{ + "fields": { + "project": {"key": "DSYS"}, + "summary": "Migrate ComponentName to MMDS", + "description": { + "type": "doc", + "version": 1, + "content": [ + { + "type": "heading", + "attrs": {"level": 2}, + "content": [{"type": "text", "text": "Summary"}] + }, + { + "type": "paragraph", + "content": [{"type": "text", "text": "Migrate ComponentName from [Extension|Mobile] component-library to MMDS."}] + }, + { + "type": "heading", + "attrs": {"level": 2}, + "content": [{"type": "text", "text": "Details"}] + }, + { + "type": "bulletList", + "content": [ + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Source: ui/components/component-library/[path]/"}]}]}, + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Target: @metamask/design-system-[react|react-native]"}]}]} + ] + }, + { + "type": "heading", + "attrs": {"level": 2}, + "content": [{"type": "text", "text": "Acceptance Criteria"}] + }, + { + "type": "orderedList", + "content": [ + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Shared types created in design-system-shared"}]}]}, + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "React implementation complete"}]}]}, + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "React Native implementation complete"}]}]}, + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Storybook stories added"}]}]}, + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Tests added"}]}]}, + {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Migration guide added"}]}]} + ] + } + ] + }, + "issuetype": {"name": "Sub-task"}, + "parent": {"key": "DSYS-272"}, + "labels": ["component-migration"] + } + }' \ + "$JIRA_BASE_URL/rest/api/3/issue" +``` + +#### Create Adoption Ticket + +```bash +curl -X POST \ + -H "Authorization: Basic $(echo -n $JIRA_EMAIL:$JIRA_TOKEN | base64)" \ + -H "Content-Type: application/json" \ + -d '{ + "fields": { + "project": {"key": "DSYS"}, + "summary": "[Extension] Adopt ComponentName from MMDS", + "description": { + "type": "doc", + "version": 1, + "content": [ + { + "type": "paragraph", + "content": [{"type": "text", "text": "Replace ComponentName in extension with @metamask/design-system-react."}] + }, + { + "type": "heading", + "attrs": {"level": 2}, + "content": [{"type": "text", "text": "Migration Guide"}] + }, + { + "type": "paragraph", + "content": [{"type": "text", "text": "See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#component"}] + }, + { + "type": "heading", + "attrs": {"level": 2}, + "content": [{"type": "text", "text": "Replacement"}] + }, + { + "type": "codeBlock", + "attrs": {"language": "typescript"}, + "content": [ + {"type": "text", "text": "// Old\nimport { ComponentName } from '../../component-library/component';\n\n// New\nimport { ComponentName } from '@metamask/design-system-react';"} + ] + } + ] + }, + "issuetype": {"name": "Task"}, + "labels": ["adoption", "extension"], + "priority": {"name": "Medium"} + } + }' \ + "$JIRA_BASE_URL/rest/api/3/issue" +``` + +## Bulk Ticket Creation + +To create tickets for all pending components: + +```bash +#!/bin/bash +# create-migration-tickets.sh + +COMPONENTS=( + "AvatarAccount" + "AvatarBase" + "AvatarFavicon" + "AvatarGroup" + "AvatarIcon" + "AvatarNetwork" + "AvatarToken" +) + +for component in "${COMPONENTS[@]}"; do + gh issue create \ + --title "Migrate $component to MMDS" \ + --body "## Summary +Migrate $component from extension component-library to MMDS + +## Details +- **Source:** ui/components/component-library/[component-path]/ +- **Target:** @metamask/design-system-react +- **Epic:** DSYS-272 + +## Acceptance Criteria +- [ ] Shared types created +- [ ] React implementation complete +- [ ] Storybook stories added +- [ ] Tests added +- [ ] Migration guide added +- [ ] Adoption ticket created" \ + --label "component-migration" \ + --label "needs-pr" + + echo "Created ticket for: $component" +done +``` + +## Ticket Labels + +| Label | Description | +| ------------------- | ---------------------------------------------- | +| component-migration | Ticket for migrating a component to MMDS | +| adoption | Ticket for adopting MMDS component in platform | +| extension | Extension-specific ticket | +| mobile | Mobile-specific ticket | +| needs-pr | Waiting for PR | +| blocked | Blocked on dependency | + +## Viewing Epic Progress + +### Web UI + +- Extension Epic: https://consensyssoftware.atlassian.net/browse/DSYS-272 +- Mobile Epic: https://consensyssoftware.atlassian.net/browse/DSYS-302 + +### CLI + +```bash +# List all component migration tickets +gh issue list --label "component-migration" --state all + +# List by platform +gh issue list --label "component-migration" --label "extension" --state open +gh issue list --label "component-migration" --label "mobile" --state open + +# List adoption tickets +gh issue list --label "adoption" --state open +``` + +## Related Documentation + +- @.cursor/rules/component-migration-tracking.md - Tracking workflow +- @docs/component-migration-project.md - Project overview +- @docs/extension-migration-tracker.md - Extension tracker +- @docs/mobile-migration-tracker.md - Mobile tracker diff --git a/docs/mobile-migration-tracker.md b/docs/mobile-migration-tracker.md new file mode 100644 index 000000000..8a85451a3 --- /dev/null +++ b/docs/mobile-migration-tracker.md @@ -0,0 +1,200 @@ +# Mobile Component Migration Tracker + +**Source:** [metamask-mobile/app/component-library](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) +**Target:** `@metamask/design-system-react-native` +**Epic:** [DSYS-302](https://consensyssoftware.atlassian.net/browse/DSYS-302) +**Last Updated:** 2026-03-23 + +## Summary + +| Status | Count | +| -------------- | ------ | +| βœ… Migrated | 5 | +| πŸ”„ In Progress | 4 | +| ⬜ Pending | 38 | +| **Total** | **47** | + +## βœ… Migrated Components + +These components have been migrated to MMDS and have migration guides. + +| Component | MMDS Location | Migration Guide | Notes | +| ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------ | +| BannerAlert | `packages/design-system-react-native/src/components/BannerAlert/` | [Guide](../packages/design-system-react-native/MIGRATION.md#banneralert-component) | Errorβ†’Danger rename | +| Box | `packages/design-system-react-native/src/components/Box/` | [Guide](../packages/design-system-react-native/MIGRATION.md#box-component) | Custom spacing via twClassName | +| ButtonIcon | `packages/design-system-react-native/src/components/ButtonIcon/` | [Guide](../packages/design-system-react-native/MIGRATION.md#from-version-0100-to-0110) | Variant prop replacement | +| Icon | `packages/design-system-react-native/src/components/Icon/` | [Guide](../packages/design-system-react-native/MIGRATION.md#icon-component) | Size/color enum changes | +| Text | `packages/design-system-react-native/src/components/Text/` | [Guide](../packages/design-system-react-native/MIGRATION.md#text-component) | Font weight separation | + +## πŸ”„ In Progress + +These components are currently being migrated. + +| Component | Owner | Ticket | PR | Notes | +| ---------- | ----- | ------ | --- | ----- | +| Button | - | - | - | - | +| ButtonBase | - | - | - | - | +| Checkbox | - | - | - | - | +| TextButton | - | - | - | - | + +## ⬜ Pending Components + +### Avatar Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ------------- | ----------------------------------- | -------- | ------ | ----- | +| AvatarAccount | `components/Avatars/AvatarAccount/` | Medium | - | - | +| AvatarBase | `components/Avatars/AvatarBase/` | Medium | - | - | +| AvatarFavicon | `components/Avatars/AvatarFavicon/` | Medium | - | - | +| AvatarGroup | `components/Avatars/AvatarGroup/` | Medium | - | - | +| AvatarIcon | `components/Avatars/AvatarIcon/` | Medium | - | - | +| AvatarNetwork | `components/Avatars/AvatarNetwork/` | Medium | - | - | +| AvatarToken | `components/Avatars/AvatarToken/` | Medium | - | - | + +### Badge Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ------------ | -------------------------------- | -------- | ------ | ----- | +| BadgeCount | `components/Badge/BadgeCount/` | Low | - | - | +| BadgeIcon | `components/Badge/BadgeIcon/` | Low | - | - | +| BadgeNetwork | `components/Badge/BadgeNetwork/` | Low | - | - | +| BadgeStatus | `components/Badge/BadgeStatus/` | Low | - | - | +| BadgeWrapper | `components/Badge/BadgeWrapper/` | Low | - | - | + +### Banner Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ---------- | --------------------------------- | -------- | ------ | ----- | +| BannerBase | `components/Banners/Banner/base/` | Medium | - | - | + +### Bottom Sheet Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ------------------ | -------------------------------------------- | -------- | ------ | ----- | +| BottomSheet | `components/BottomSheet/BottomSheet/` | High | - | - | +| BottomSheetDialog | `components/BottomSheet/BottomSheetDialog/` | High | - | - | +| BottomSheetFooter | `components/BottomSheet/BottomSheetFooter/` | High | - | - | +| BottomSheetHeader | `components/BottomSheet/BottomSheetHeader/` | High | - | - | +| BottomSheetOverlay | `components/BottomSheet/BottomSheetOverlay/` | High | - | - | + +### Button Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| -------------- | ----------------------------------- | -------- | ------ | ----- | +| ButtonFilter | `components/Button/ButtonFilter/` | Medium | - | - | +| ButtonHero | `components/Button/ButtonHero/` | Medium | - | - | +| ButtonSemantic | `components/Button/ButtonSemantic/` | Medium | - | - | + +### Card Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| --------- | ----------------------- | -------- | ------ | ----- | +| Card | `components/Card/Card/` | Medium | - | - | + +### Form Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| --------- | --------------------------------- | -------- | ------ | ----- | +| Input | `components/Input/Input/` | High | - | - | +| TextField | `components/TextField/TextField/` | High | - | - | + +### Header Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ---------- | ------------------------------- | -------- | ------ | ----- | +| HeaderBase | `components/Header/HeaderBase/` | Medium | - | - | + +### KeyValue Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ----------- | ------------------------- | -------- | ------ | ----- | +| KeyValueRow | `components/KeyValueRow/` | Medium | - | - | + +### Layout Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| --------- | --------------------------- | -------- | ------ | ----- | +| Label | `components/Label/` | Medium | - | - | +| ListItem | `components/List/ListItem/` | High | - | - | + +### Other Components + +| Component | Mobile Path | Priority | Ticket | Notes | +| ---------------- | ----------------------------------------- | -------- | ------ | ----- | +| MainActionButton | `components/Buttons/MainActionButton/` | Medium | - | - | +| RadioButton | `components/RadioButton/RadioButton/` | Medium | - | - | +| SensitiveText | `components/SensitiveText/SensitiveText/` | Low | - | - | +| Skeleton | `components/Skeleton/Skeleton/` | Low | - | - | +| TabEmptyState | `components/TabEmptyState/TabEmptyState/` | Low | - | - | +| Toast | `components/Toast/Toast/` | Medium | - | - | + +## Migration Workflow + +### Step 1: Audit Component + +1. Locate component in mobile: `app/component-library/components/[ComponentPath]/` +2. Document current API (props, types, variants) +3. Check if shared types already exist in `packages/design-system-shared/src/types/` + +### Step 2: Create Migration Plan + +1. Identify shared props vs platform-specific props +2. Decide on Conservative vs Unified approach +3. Create comparison table (Mobile API vs MMDS patterns) + +### Step 3: Implement + +```bash +# Create component scaffolding +yarn create-component:react-native --name ComponentName --description "Brief description" + +# Follow component-migration.md workflow +``` + +### Step 4: Document + +1. Add migration section to `packages/design-system-react-native/MIGRATION.md` +2. Create adoption ticket for mobile + +### Step 5: Track + +1. Update this tracker with: + - Jira ticket number + - PR link + - Migration completion date + +## Quick Reference + +| Task | Command | +| ---------------------- | ------------------------------------------------------------------- | +| Check component status | Search this file for component name | +| Update status | Edit this file and commit | +| Create ticket | Use Jira API or web UI with template | +| View epic | [DSYS-302](https://consensyssoftware.atlassian.net/browse/DSYS-302) | + +## Mobile-Specific Considerations + +### React Native Patterns + +- Use `twClassName` instead of `className` +- Use `Pressable` instead of `onClick` (use `onPress`) +- Use `twrnc` preset for Tailwind utilities +- Test on both iOS and Android + +### Native-Specific Components + +The following components are React Native specific (not in web package): + +- BottomSheet family +- Toast +- KeyValueRow +- MainActionButton +- TabEmptyState +- Skeleton + +## Related Documentation + +- [Project Overview](./component-migration-project.md) +- [Migration Strategy](./component-migration-strategy.md) +- [Component Migration Cursor Rule](../.cursor/rules/component-migration.md) +- [Mobile Source](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) From 58ccdd2aa9776c1e2a00976e579ca132b7c7c71a Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:39:21 -0700 Subject: [PATCH 02/13] chore(cursor): add Jira daily epic pickup rule for DSYS-468 Made-with: Cursor --- .cursor/rules/jira-daily-epic-pickup.mdc | 55 ++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .cursor/rules/jira-daily-epic-pickup.mdc diff --git a/.cursor/rules/jira-daily-epic-pickup.mdc b/.cursor/rules/jira-daily-epic-pickup.mdc new file mode 100644 index 000000000..f980d7027 --- /dev/null +++ b/.cursor/rules/jira-daily-epic-pickup.mdc @@ -0,0 +1,55 @@ +--- +description: Daily Jira pickup β€” select the next issue under epic DSYS-468, assign, and transition to in progress (Atlassian MCP) +globs: ['**/*'] +alwaysApply: false +--- + +When the user invokes this rule (e.g. `@jira-daily-epic-pickup` or asks to pick up today’s ticket from the ADR migration epic), do the following using **Atlassian Jira** tools (`consensyssoftware.atlassian.net`). + +## Scope (edit if your epic or identity changes) + +| Setting | Value | +|--------|--------| +| Epic | **DSYS-468** β€” *Component ADR Migration: Align with ADR-0003 and ADR-0004* | +| Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?assignee=6152e94cc7bea40069d6b9c3&issueParent=343549) | + +## 1. Find candidates + +Run JQL (company-managed / parent epic): + +```jql +parent = DSYS-468 AND statusCategory != "Done" ORDER BY Rank ASC +``` + +If the user only wants work already on their plate, narrow with: + +```jql +parent = DSYS-468 AND statusCategory != "Done" AND assignee = currentUser() ORDER BY Rank ASC +``` + +If they want the next **unclaimed** item: + +```jql +parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC +``` + +## 2. Choose one issue + +- Prefer **In Progress** already assigned to the user (continue that thread). +- Else prefer **To Do** assigned to the user. +- Else take the **first** issue from the unassigned `To Do` query (top of backlog order). + +## 3. Pick up in Jira + +- If unassigned, set **assignee** to the user (`editJiraIssue` with assignee account id, or equivalent field). +- If still in **To Do**, use `getTransitionsForJiraIssue` then `transitionJiraIssue` to move to **In Progress** (or the project’s equivalent β€œactive” state). + +## 4. Reply in chat + +- Issue key, summary, status, link (`https://consensyssoftware.atlassian.net/browse/`). +- One-line suggestion for what to do first in this repo (e.g. component name from the summary). +- If no issues match, say so and suggest checking epic **DSYS-468** or relaxing JQL. + +## Monorepo context + +Follow `CLAUDE.md` and `.cursor/rules/component-migration.md` (and related rules) when starting implementation work on the chosen ticket. From 0ad87f944354023c75e5d2f4d199bb79f1a5d570 Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:40:19 -0700 Subject: [PATCH 03/13] chore(cursor): move Jira daily pickup workflow to .cursor/automations - Add canonical steps and PR/GitHub auth notes in automations doc - Point rule at automations file for @-mention workflow Made-with: Cursor --- .cursor/automations/jira-daily-epic-pickup.md | 71 +++++++++++++++++++ .cursor/rules/jira-daily-epic-pickup.mdc | 52 +------------- 2 files changed, 74 insertions(+), 49 deletions(-) create mode 100644 .cursor/automations/jira-daily-epic-pickup.md diff --git a/.cursor/automations/jira-daily-epic-pickup.md b/.cursor/automations/jira-daily-epic-pickup.md new file mode 100644 index 000000000..a670d4d7f --- /dev/null +++ b/.cursor/automations/jira-daily-epic-pickup.md @@ -0,0 +1,71 @@ +# Daily Jira pickup β€” epic DSYS-468 + +Use this document as the **source of truth** for the workflow. In Chat, `@`-mention this file or the companion rule **Daily Jira pickup** so the agent follows these steps. + +## Scope (edit if your epic or identity changes) + +| Setting | Value | +|--------|--------| +| Epic | **DSYS-468** β€” *Component ADR Migration: Align with ADR-0003 and ADR-0004* | +| Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?assignee=6152e94cc7bea40069d6b9c3&issueParent=343549) | + +## 1. Find candidates + +Run JQL (company-managed / parent epic): + +```jql +parent = DSYS-468 AND statusCategory != "Done" ORDER BY Rank ASC +``` + +If you only want work already on your plate: + +```jql +parent = DSYS-468 AND statusCategory != "Done" AND assignee = currentUser() ORDER BY Rank ASC +``` + +Next **unclaimed** item: + +```jql +parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC +``` + +## 2. Choose one issue + +- Prefer **In Progress** already assigned to you (continue that thread). +- Else prefer **To Do** assigned to you. +- Else take the **first** issue from the unassigned `To Do` query (top of backlog order). + +## 3. Pick up in Jira + +- If unassigned, set **assignee** to you (`editJiraIssue`, or equivalent). +- If still in **To Do**, use `getTransitionsForJiraIssue` then `transitionJiraIssue` to move to **In Progress** (or the project’s equivalent β€œactive” state). + +## 4. Reply in chat + +- Issue key, summary, status, link (`https://consensyssoftware.atlassian.net/browse/`). +- One-line suggestion for what to do first in this repo (e.g. component name from the summary). +- If no issues match, say so and suggest checking epic **DSYS-468** or relaxing JQL. + +## 5. Open the PR as your GitHub user + +Yes β€” automation (or the agent running **`gh pr create`**) opens the PR **as whoever is authenticated** with the GitHub CLI in that environment. + +1. **Verify identity** before relying on it: + + ```bash + gh auth status + ``` + + The **logged-in account** is the one that will **create** the PR (you appear as the PR author in the UI). + +2. **Where the branch lives** (fork vs upstream): + - If your workflow uses a **personal fork**, push the branch to **`origin`** on your fork (`your-username/metamask-design-system`), then run `gh pr create` with the base repo set to the upstream org repo. The PR still shows **you** as the opener; the head ref is your fork. + - If you push a branch **directly on the org repo** and have permission, `gh pr create` still attributes the PR to the authenticated user. + +3. **Cursor / automation**: Scheduled or agent runs use the **same machine’s** `gh` credentials (or whatever GitHub integration the agent uses). If that session is logged in as you, PRs are yours. If not, log in with `gh auth login` (or fix the token) for that environment. + +4. **PR body**: Follow `.github/pull_request_template.md` and `@pr` / `.cursor/rules/pr.mdc` conventions when drafting the description. + +## Monorepo context + +Follow `CLAUDE.md` and `.cursor/rules/component-migration.md` (and related rules) when implementing work for the chosen ticket. diff --git a/.cursor/rules/jira-daily-epic-pickup.mdc b/.cursor/rules/jira-daily-epic-pickup.mdc index f980d7027..a2dc4ad4d 100644 --- a/.cursor/rules/jira-daily-epic-pickup.mdc +++ b/.cursor/rules/jira-daily-epic-pickup.mdc @@ -1,55 +1,9 @@ --- -description: Daily Jira pickup β€” select the next issue under epic DSYS-468, assign, and transition to in progress (Atlassian MCP) +description: Daily Jira pickup β€” select the next issue under epic DSYS-468, assign, transition, and open PR as the authenticated GitHub user globs: ['**/*'] alwaysApply: false --- -When the user invokes this rule (e.g. `@jira-daily-epic-pickup` or asks to pick up today’s ticket from the ADR migration epic), do the following using **Atlassian Jira** tools (`consensyssoftware.atlassian.net`). +When invoked (e.g. `@jira-daily-epic-pickup` or β€œpick up today’s DSYS-468 ticket”), follow **every step** in `@.cursor/automations/jira-daily-epic-pickup.md` using Atlassian Jira for `consensyssoftware.atlassian.net`. -## Scope (edit if your epic or identity changes) - -| Setting | Value | -|--------|--------| -| Epic | **DSYS-468** β€” *Component ADR Migration: Align with ADR-0003 and ADR-0004* | -| Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?assignee=6152e94cc7bea40069d6b9c3&issueParent=343549) | - -## 1. Find candidates - -Run JQL (company-managed / parent epic): - -```jql -parent = DSYS-468 AND statusCategory != "Done" ORDER BY Rank ASC -``` - -If the user only wants work already on their plate, narrow with: - -```jql -parent = DSYS-468 AND statusCategory != "Done" AND assignee = currentUser() ORDER BY Rank ASC -``` - -If they want the next **unclaimed** item: - -```jql -parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC -``` - -## 2. Choose one issue - -- Prefer **In Progress** already assigned to the user (continue that thread). -- Else prefer **To Do** assigned to the user. -- Else take the **first** issue from the unassigned `To Do` query (top of backlog order). - -## 3. Pick up in Jira - -- If unassigned, set **assignee** to the user (`editJiraIssue` with assignee account id, or equivalent field). -- If still in **To Do**, use `getTransitionsForJiraIssue` then `transitionJiraIssue` to move to **In Progress** (or the project’s equivalent β€œactive” state). - -## 4. Reply in chat - -- Issue key, summary, status, link (`https://consensyssoftware.atlassian.net/browse/`). -- One-line suggestion for what to do first in this repo (e.g. component name from the summary). -- If no issues match, say so and suggest checking epic **DSYS-468** or relaxing JQL. - -## Monorepo context - -Follow `CLAUDE.md` and `.cursor/rules/component-migration.md` (and related rules) when starting implementation work on the chosen ticket. +That file is the canonical workflow (JQL, pickup order, Jira updates, PR authorship via `gh`, link to the PR template). From b05a5ba9066e69bcf9782201a2bdf4780f16d75a Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:41:03 -0700 Subject: [PATCH 04/13] chore(cursor): rename automation to enum-shared-type-migration Made-with: Cursor --- ...aily-epic-pickup.md => enum-shared-type-migration.md} | 4 ++-- .cursor/rules/enum-shared-type-migration.mdc | 9 +++++++++ .cursor/rules/jira-daily-epic-pickup.mdc | 9 --------- 3 files changed, 11 insertions(+), 11 deletions(-) rename .cursor/automations/{jira-daily-epic-pickup.md => enum-shared-type-migration.md} (90%) create mode 100644 .cursor/rules/enum-shared-type-migration.mdc delete mode 100644 .cursor/rules/jira-daily-epic-pickup.mdc diff --git a/.cursor/automations/jira-daily-epic-pickup.md b/.cursor/automations/enum-shared-type-migration.md similarity index 90% rename from .cursor/automations/jira-daily-epic-pickup.md rename to .cursor/automations/enum-shared-type-migration.md index a670d4d7f..2e88faaf8 100644 --- a/.cursor/automations/jira-daily-epic-pickup.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -1,6 +1,6 @@ -# Daily Jira pickup β€” epic DSYS-468 +# enum-shared-type-migration -Use this document as the **source of truth** for the workflow. In Chat, `@`-mention this file or the companion rule **Daily Jira pickup** so the agent follows these steps. +Daily Jira pickup for epic **DSYS-468** (*Component ADR Migration* / ADR-0003 & ADR-0004). This file is the **source of truth**. In Chat, `@`-mention `.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** so the agent follows these steps. ## Scope (edit if your epic or identity changes) diff --git a/.cursor/rules/enum-shared-type-migration.mdc b/.cursor/rules/enum-shared-type-migration.mdc new file mode 100644 index 000000000..79caad51f --- /dev/null +++ b/.cursor/rules/enum-shared-type-migration.mdc @@ -0,0 +1,9 @@ +--- +description: enum-shared-type-migration β€” Jira pickup for DSYS-468, assign, transition, open PR as authenticated GitHub user +globs: ['**/*'] +alwaysApply: false +--- + +When invoked (e.g. `@enum-shared-type-migration` or β€œrun enum shared type migration pickup”), follow **every step** in `@.cursor/automations/enum-shared-type-migration.md` using Atlassian Jira for `consensyssoftware.atlassian.net`. + +That file is the canonical workflow (JQL, pickup order, Jira updates, PR authorship via `gh`, link to the PR template). diff --git a/.cursor/rules/jira-daily-epic-pickup.mdc b/.cursor/rules/jira-daily-epic-pickup.mdc deleted file mode 100644 index a2dc4ad4d..000000000 --- a/.cursor/rules/jira-daily-epic-pickup.mdc +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: Daily Jira pickup β€” select the next issue under epic DSYS-468, assign, transition, and open PR as the authenticated GitHub user -globs: ['**/*'] -alwaysApply: false ---- - -When invoked (e.g. `@jira-daily-epic-pickup` or β€œpick up today’s DSYS-468 ticket”), follow **every step** in `@.cursor/automations/jira-daily-epic-pickup.md` using Atlassian Jira for `consensyssoftware.atlassian.net`. - -That file is the canonical workflow (JQL, pickup order, Jira updates, PR authorship via `gh`, link to the PR template). From 576e451599cdb4bd9dd8d14423c134bf12df5add Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:41:37 -0700 Subject: [PATCH 05/13] docs(cursor): align enum-shared-type-migration with Cloud Automations docs Made-with: Cursor --- .../automations/enum-shared-type-migration.md | 32 ++++++++++++------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 2e88faaf8..897546ddc 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -48,23 +48,33 @@ parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC ## 5. Open the PR as your GitHub user -Yes β€” automation (or the agent running **`gh pr create`**) opens the PR **as whoever is authenticated** with the GitHub CLI in that environment. +### Cursor Cloud Automations ([docs](https://cursor.com/docs/cloud-agent/automations)) -1. **Verify identity** before relying on it: +Create and manage automations at [cursor.com/automations](https://cursor.com/automations). Flow: pick a **trigger** (schedule, GitHub event, Slack, webhook, Linear, PagerDuty, etc.), write the **prompt**, enable **tools** (e.g. Open pull request, MCP). - ```bash - gh auth status - ``` +**Who opens the PR** (per Cursor docs β€” *Identity*): - The **logged-in account** is the one that will **create** the PR (you appear as the PR author in the UI). +| Automation permission | Pull requests opened as | +|----------------------|-------------------------| +| **Private** or **Team Visible** | **Your** GitHub account | +| **Team Owned** | The **`cursor`** service account (not your user) | -2. **Where the branch lives** (fork vs upstream): - - If your workflow uses a **personal fork**, push the branch to **`origin`** on your fork (`your-username/metamask-design-system`), then run `gh pr create` with the base repo set to the upstream org repo. The PR still shows **you** as the opener; the head ref is your fork. - - If you push a branch **directly on the org repo** and have permission, `gh pr create` still attributes the PR to the authenticated user. +GitHub **comments**, **review approvals**, and **reviewer requests** run as **`cursor`** regardless. **Slack** sends as the Cursor bot. -3. **Cursor / automation**: Scheduled or agent runs use the **same machine’s** `gh` credentials (or whatever GitHub integration the agent uses). If that session is logged in as you, PRs are yours. If not, log in with `gh auth login` (or fix the token) for that environment. +**Billing**: Automations use cloud agents; cost follows the automation’s permission scope (team pool for Team Owned, creator for Private / Team Visible). Enable **Open pull request** when the automation should commit and open a PR. -4. **PR body**: Follow `.github/pull_request_template.md` and `@pr` / `.cursor/rules/pr.mdc` conventions when drafting the description. +For **scheduled** (or Slack, etc.) triggers you choose **repository and branch** explicitly β€” Cursor does not infer them from a PR. + +### Local agent / `gh` on your machine + +When **you** run the agent in the IDE and it uses **`gh pr create`**, the PR author is whoever is logged into the GitHub CLI: + +```bash +gh auth status +``` + +- **Fork workflow**: push to your fork’s `origin`, then `gh pr create` toward upstream β€” you remain the opener. +- **PR body**: Follow `.github/pull_request_template.md` and `@pr` / `.cursor/rules/pr.mdc`. ## Monorepo context From f96f7264c940ae6a29c910ec988b4e017ba3bf70 Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:48:45 -0700 Subject: [PATCH 06/13] docs(cursor): tie enum-shared-type-migration to ADR refactor rules and cloud prompt Made-with: Cursor --- .../automations/enum-shared-type-migration.md | 54 ++++++++++++++++++- .cursor/rules/enum-shared-type-migration.mdc | 4 +- 2 files changed, 55 insertions(+), 3 deletions(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 897546ddc..820e00d3d 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -31,10 +31,24 @@ parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC ## 2. Choose one issue +### Interactive (IDE / manual run) + - Prefer **In Progress** already assigned to you (continue that thread). - Else prefer **To Do** assigned to you. - Else take the **first** issue from the unassigned `To Do` query (top of backlog order). +### Scheduled Cursor Cloud Automation (β€œalways take backlog”) + +Use **only** unclaimed work so each run picks a new ticket: + +```jql +parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC +``` + +Take the **first** result. If the list is empty, stop (no PR); optionally comment in the run log or Slack. + +**Jira + cloud agent:** Enable your **Atlassian/Jira MCP** (or equivalent) on the automation so the agent can search JQL, assign, and transition. Without Jira tools, the automation cannot claim tickets by itself. + ## 3. Pick up in Jira - If unassigned, set **assignee** to you (`editJiraIssue`, or equivalent). @@ -76,6 +90,42 @@ gh auth status - **Fork workflow**: push to your fork’s `origin`, then `gh pr create` toward upstream β€” you remain the opener. - **PR body**: Follow `.github/pull_request_template.md` and `@pr` / `.cursor/rules/pr.mdc`. -## Monorepo context +## 6. Implement the migration (ADR-0003 / ADR-0004) + +DSYS-468 tasks are **internal refactors** of components already in the monorepo (e.g. β€œMigrate **BadgeStatus** to ADR-0003/ADR-0004”). They are **not** extension/mobile imports. + +**Primary workflow β€” follow in order:** + +1. `@.cursor/rules/component-enum-union-migration.md` β€” enum β†’ const objects, shared types, platform `.types.ts` + `index.ts` exports, common mistakes (coverage / re-exports). +2. `@.cursor/rules/component-architecture.md` β€” layout of shared vs platform props. +3. `@.cursor/rules/testing.md` β€” tests when touching components. +4. `@.cursor/rules/component-documentation.md` β€” Storybook if stories change. -Follow `CLAUDE.md` and `.cursor/rules/component-migration.md` (and related rules) when implementing work for the chosen ticket. +**Golden reference in repo:** `BadgeStatus` (paths and PR #912 are listed in `component-enum-union-migration.md`). + +**Do not** use `@.cursor/rules/component-migration.md` for this epic β€” that rule is for bringing components **from** extension/mobile **into** the monorepo. + +**After code changes:** `yarn build && yarn test && yarn lint` (from repo root). Open a PR with `.github/pull_request_template.md` / `@.cursor/rules/pr.mdc`; title/body should reference the Jira key (e.g. `DSYS-476`). + +## Cloud automation β€” example prompt (paste into cursor.com/automations) + +Adapt as needed; keep **Private** if the PR must be under your GitHub user. + +```text +Repository/branch: @ . + +1) Jira (Consensys cloud): Run JQL β€” parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC. Take the first issue. If none, exit successfully with a short message. + +2) Assign the issue to the appropriate user if required by your workflow, transition from To Do to In Progress. + +3) Implement the ticket using the repo’s Cursor rules exactly: + - .cursor/rules/component-enum-union-migration.md (primary) + - .cursor/rules/component-architecture.md + - .cursor/rules/testing.md + - .cursor/rules/component-documentation.md when stories change + Use BadgeStatus in the codebase as the reference pattern. Do not use component-migration.md (that is for extension/mobile imports). + +4) Run yarn build, yarn test, yarn lint from the repo root; fix failures. + +5) Open a pull request: include the Jira key in the title/description, follow .github/pull_request_template.md. +``` diff --git a/.cursor/rules/enum-shared-type-migration.mdc b/.cursor/rules/enum-shared-type-migration.mdc index 79caad51f..451f58cc7 100644 --- a/.cursor/rules/enum-shared-type-migration.mdc +++ b/.cursor/rules/enum-shared-type-migration.mdc @@ -6,4 +6,6 @@ alwaysApply: false When invoked (e.g. `@enum-shared-type-migration` or β€œrun enum shared type migration pickup”), follow **every step** in `@.cursor/automations/enum-shared-type-migration.md` using Atlassian Jira for `consensyssoftware.atlassian.net`. -That file is the canonical workflow (JQL, pickup order, Jira updates, PR authorship via `gh`, link to the PR template). +After a ticket is chosen, **implement** it with `@.cursor/rules/component-enum-union-migration.md` (primary), `@.cursor/rules/component-architecture.md`, and `@.cursor/rules/testing.md` β€” not `component-migration.md` (that rule is for extension/mobile β†’ monorepo only). Use **BadgeStatus** file paths in `component-enum-union-migration.md` as the golden reference. + +The automations file is canonical for JQL, pickup mode (interactive vs scheduled), Jira updates, PR identity (`gh` vs Cloud Automations), and the paste-ready cloud prompt. From 9e1c2c31a86ffbae8c31d10b1d957799e3e0ee5b Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:50:38 -0700 Subject: [PATCH 07/13] docs: align automations with ai-agents strategy (reference, checklists, verification) Made-with: Cursor --- .../automations/enum-shared-type-migration.md | 67 +++++++++++++------ .cursor/rules/enum-shared-type-migration.mdc | 6 +- docs/ai-agents.md | 11 +++ 3 files changed, 60 insertions(+), 24 deletions(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 820e00d3d..99b5feef8 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -1,6 +1,10 @@ # enum-shared-type-migration -Daily Jira pickup for epic **DSYS-468** (*Component ADR Migration* / ADR-0003 & ADR-0004). This file is the **source of truth**. In Chat, `@`-mention `.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** so the agent follows these steps. +Daily Jira pickup for epic **DSYS-468** (*Component ADR Migration* / ADR-0003 & ADR-0004). + +**Strategy:** This file matches [docs/ai-agents.md](../../docs/ai-agents.md): *reference over duplication*, *checklists over narratives*, *context efficiency*. It only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` β€” agents must read those files, not improvise from this doc alone. + +**Invoke:** `@.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** (`.cursor/rules/enum-shared-type-migration.mdc`). ## Scope (edit if your epic or identity changes) @@ -92,40 +96,59 @@ gh auth status ## 6. Implement the migration (ADR-0003 / ADR-0004) -DSYS-468 tasks are **internal refactors** of components already in the monorepo (e.g. β€œMigrate **BadgeStatus** to ADR-0003/ADR-0004”). They are **not** extension/mobile imports. +DSYS-468 tasks are **internal refactors** of components already in the monorepo (e.g. β€œMigrate **BadgeStatus** …”). They are **not** extension/mobile imports. + +### Guardrails (agent must not skip) + +- ❌ Do **not** use `@.cursor/rules/component-migration.md` for this epic (extension/mobile β†’ monorepo only). +- βœ… Do use `@CLAUDE.md` for **monorepo commands** (always run from repo root: `yarn workspace …` patterns as documented). +- βœ… Do follow each rule’s **Verification** / checklist sections literally β€” rules are Layer 2 in [docs/ai-agents.md](../../docs/ai-agents.md). + +### Layer 2 rules β€” read in order (do not duplicate their content here) -**Primary workflow β€” follow in order:** +| Order | Rule | Role | +|------|------|------| +| 1 | `@.cursor/rules/component-enum-union-migration.md` | Primary workflow, ❌/βœ… examples, **Golden Path** file paths, PR #912 | +| 2 | `@.cursor/rules/component-architecture.md` | ADR-0003/0004 layering, shared vs platform | +| 3 | `@.cursor/rules/testing.md` | Jest, a11y, assertions | +| 4 | `@.cursor/rules/component-documentation.md` | Storybook/README when stories or docs change | -1. `@.cursor/rules/component-enum-union-migration.md` β€” enum β†’ const objects, shared types, platform `.types.ts` + `index.ts` exports, common mistakes (coverage / re-exports). -2. `@.cursor/rules/component-architecture.md` β€” layout of shared vs platform props. -3. `@.cursor/rules/testing.md` β€” tests when touching components. -4. `@.cursor/rules/component-documentation.md` β€” Storybook if stories change. +**Golden path:** Defined inside `component-enum-union-migration.md` (e.g. **BadgeStatus** paths). -**Golden reference in repo:** `BadgeStatus` (paths and PR #912 are listed in `component-enum-union-migration.md`). +### Verification (after edits) -**Do not** use `@.cursor/rules/component-migration.md` for this epic β€” that rule is for bringing components **from** extension/mobile **into** the monorepo. +From repository root (per `CLAUDE.md`): -**After code changes:** `yarn build && yarn test && yarn lint` (from repo root). Open a PR with `.github/pull_request_template.md` / `@.cursor/rules/pr.mdc`; title/body should reference the Jira key (e.g. `DSYS-476`). +```bash +yarn build && yarn test && yarn lint +``` + +### PR + +`@.cursor/rules/pr.mdc` + `.github/pull_request_template.md`; include Jira key (e.g. `DSYS-476`). ## Cloud automation β€” example prompt (paste into cursor.com/automations) -Adapt as needed; keep **Private** if the PR must be under your GitHub user. +Keep the prompt **short**; implementation detail lives in `@.cursor/rules/` per [docs/ai-agents.md](../../docs/ai-agents.md). Use **Private** if the PR must be under your GitHub user. ```text -Repository/branch: @ . +Repository/branch: @ . -1) Jira (Consensys cloud): Run JQL β€” parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC. Take the first issue. If none, exit successfully with a short message. +You are in the MetaMask design-system monorepo. Follow docs/ai-agents.md: reference rules with @ β€” do not invent ADR patterns from memory. -2) Assign the issue to the appropriate user if required by your workflow, transition from To Do to In Progress. +1) Jira (Consensys): JQL parent = DSYS-468 AND status = "To Do" AND assignee is EMPTY ORDER BY Rank ASC β†’ first issue, or exit with a one-line message if empty. Assign/transition to In Progress per workflow. -3) Implement the ticket using the repo’s Cursor rules exactly: - - .cursor/rules/component-enum-union-migration.md (primary) - - .cursor/rules/component-architecture.md - - .cursor/rules/testing.md - - .cursor/rules/component-documentation.md when stories change - Use BadgeStatus in the codebase as the reference pattern. Do not use component-migration.md (that is for extension/mobile imports). +2) Read and follow in order (full checklists inside each file): + @CLAUDE.md + @.cursor/rules/component-enum-union-migration.md + @.cursor/rules/component-architecture.md + @.cursor/rules/testing.md + @.cursor/rules/component-documentation.md (if stories/docs change) + Do NOT use @.cursor/rules/component-migration.md for this epic. -4) Run yarn build, yarn test, yarn lint from the repo root; fix failures. +3) Verify from repo root: yarn build && yarn test && yarn lint (per CLAUDE.md). -5) Open a pull request: include the Jira key in the title/description, follow .github/pull_request_template.md. +4) Open PR per @.cursor/rules/pr.mdc and .github/pull_request_template.md; put Jira key in title/body. ``` + +Optional: `@`-mention `@.cursor/automations/enum-shared-type-migration.md` in the automation prompt so the agent loads JQL + PR-identity notes from this file. diff --git a/.cursor/rules/enum-shared-type-migration.mdc b/.cursor/rules/enum-shared-type-migration.mdc index 451f58cc7..1e8caaab1 100644 --- a/.cursor/rules/enum-shared-type-migration.mdc +++ b/.cursor/rules/enum-shared-type-migration.mdc @@ -6,6 +6,8 @@ alwaysApply: false When invoked (e.g. `@enum-shared-type-migration` or β€œrun enum shared type migration pickup”), follow **every step** in `@.cursor/automations/enum-shared-type-migration.md` using Atlassian Jira for `consensyssoftware.atlassian.net`. -After a ticket is chosen, **implement** it with `@.cursor/rules/component-enum-union-migration.md` (primary), `@.cursor/rules/component-architecture.md`, and `@.cursor/rules/testing.md` β€” not `component-migration.md` (that rule is for extension/mobile β†’ monorepo only). Use **BadgeStatus** file paths in `component-enum-union-migration.md` as the golden reference. +Follow `@docs/ai-agents.md`: **reference over duplication** β€” pull checklists and golden paths from Layer 2 rules; do not paraphrase long migration steps in chat. -The automations file is canonical for JQL, pickup mode (interactive vs scheduled), Jira updates, PR identity (`gh` vs Cloud Automations), and the paste-ready cloud prompt. +After a ticket is chosen, **implement** with `@.cursor/rules/component-enum-union-migration.md` (primary), `@.cursor/rules/component-architecture.md`, and `@.cursor/rules/testing.md` β€” not `component-migration.md` (extension/mobile β†’ monorepo only). Use **BadgeStatus** paths in `component-enum-union-migration.md` as the golden reference. + +The automations file is canonical for JQL, pickup mode, Jira updates, PR identity, and the paste-ready cloud prompt. diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 5873d5dd1..8b95e4a9b 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -95,6 +95,17 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i ## How AI Agents Use This +### Cursor Cloud Automations + +[Cursor Automations](https://cursor.com/docs/cloud-agent/automations) should follow the **same principles** as interactive agents in this repo (see [Key Principles](#key-principles) below): + +- **Reference over duplication** β€” Automation prompts should `@`-mention `@CLAUDE.md` and specific `@.cursor/rules/*.md` files instead of pasting long paraphrased workflows. Rules stay the single source of truth. +- **Checklists over narratives** β€” Implementation steps live in the rules (Do/Don’t, verification); the prompt only sequences *which* rules apply and *when* (e.g. after Jira pickup). +- **Context efficiency** β€” Keep the scheduled prompt short; agents pull detail from rules and golden-path file paths inside those rules. +- **Verification** β€” Always run commands from repo root as in `CLAUDE.md` (e.g. `yarn build`, `yarn test`, `yarn lint`). + +Repo-specific automation specs (Jira epic, JQL, PR identity notes) live under `.cursor/automations/` alongside opt-in `.cursor/rules/*.mdc` entry points. + ### Cursor **Automatic loading:** From fc75ce9e0d6c13c6edf6064d00bf7599b49fc63c Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:56:30 -0700 Subject: [PATCH 08/13] chore: prettier format automation and ai-agents docs Made-with: Cursor --- .../automations/enum-shared-type-migration.md | 32 +++++++++---------- docs/ai-agents.md | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 99b5feef8..ec7f06e08 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -1,16 +1,16 @@ # enum-shared-type-migration -Daily Jira pickup for epic **DSYS-468** (*Component ADR Migration* / ADR-0003 & ADR-0004). +Daily Jira pickup for epic **DSYS-468** (_Component ADR Migration_ / ADR-0003 & ADR-0004). -**Strategy:** This file matches [docs/ai-agents.md](../../docs/ai-agents.md): *reference over duplication*, *checklists over narratives*, *context efficiency*. It only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` β€” agents must read those files, not improvise from this doc alone. +**Strategy:** This file matches [docs/ai-agents.md](../../docs/ai-agents.md): _reference over duplication_, _checklists over narratives_, _context efficiency_. It only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` β€” agents must read those files, not improvise from this doc alone. **Invoke:** `@.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** (`.cursor/rules/enum-shared-type-migration.mdc`). ## Scope (edit if your epic or identity changes) -| Setting | Value | -|--------|--------| -| Epic | **DSYS-468** β€” *Component ADR Migration: Align with ADR-0003 and ADR-0004* | +| Setting | Value | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Epic | **DSYS-468** β€” _Component ADR Migration: Align with ADR-0003 and ADR-0004_ | | Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?assignee=6152e94cc7bea40069d6b9c3&issueParent=343549) | ## 1. Find candidates @@ -70,12 +70,12 @@ Take the **first** result. If the list is empty, stop (no PR); optionally commen Create and manage automations at [cursor.com/automations](https://cursor.com/automations). Flow: pick a **trigger** (schedule, GitHub event, Slack, webhook, Linear, PagerDuty, etc.), write the **prompt**, enable **tools** (e.g. Open pull request, MCP). -**Who opens the PR** (per Cursor docs β€” *Identity*): +**Who opens the PR** (per Cursor docs β€” _Identity_): -| Automation permission | Pull requests opened as | -|----------------------|-------------------------| -| **Private** or **Team Visible** | **Your** GitHub account | -| **Team Owned** | The **`cursor`** service account (not your user) | +| Automation permission | Pull requests opened as | +| ------------------------------- | ------------------------------------------------ | +| **Private** or **Team Visible** | **Your** GitHub account | +| **Team Owned** | The **`cursor`** service account (not your user) | GitHub **comments**, **review approvals**, and **reviewer requests** run as **`cursor`** regardless. **Slack** sends as the Cursor bot. @@ -106,12 +106,12 @@ DSYS-468 tasks are **internal refactors** of components already in the monorepo ### Layer 2 rules β€” read in order (do not duplicate their content here) -| Order | Rule | Role | -|------|------|------| -| 1 | `@.cursor/rules/component-enum-union-migration.md` | Primary workflow, ❌/βœ… examples, **Golden Path** file paths, PR #912 | -| 2 | `@.cursor/rules/component-architecture.md` | ADR-0003/0004 layering, shared vs platform | -| 3 | `@.cursor/rules/testing.md` | Jest, a11y, assertions | -| 4 | `@.cursor/rules/component-documentation.md` | Storybook/README when stories or docs change | +| Order | Rule | Role | +| ----- | -------------------------------------------------- | --------------------------------------------------------------------- | +| 1 | `@.cursor/rules/component-enum-union-migration.md` | Primary workflow, ❌/βœ… examples, **Golden Path** file paths, PR #912 | +| 2 | `@.cursor/rules/component-architecture.md` | ADR-0003/0004 layering, shared vs platform | +| 3 | `@.cursor/rules/testing.md` | Jest, a11y, assertions | +| 4 | `@.cursor/rules/component-documentation.md` | Storybook/README when stories or docs change | **Golden path:** Defined inside `component-enum-union-migration.md` (e.g. **BadgeStatus** paths). diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 8b95e4a9b..668d8863a 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -100,7 +100,7 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i [Cursor Automations](https://cursor.com/docs/cloud-agent/automations) should follow the **same principles** as interactive agents in this repo (see [Key Principles](#key-principles) below): - **Reference over duplication** β€” Automation prompts should `@`-mention `@CLAUDE.md` and specific `@.cursor/rules/*.md` files instead of pasting long paraphrased workflows. Rules stay the single source of truth. -- **Checklists over narratives** β€” Implementation steps live in the rules (Do/Don’t, verification); the prompt only sequences *which* rules apply and *when* (e.g. after Jira pickup). +- **Checklists over narratives** β€” Implementation steps live in the rules (Do/Don’t, verification); the prompt only sequences _which_ rules apply and _when_ (e.g. after Jira pickup). - **Context efficiency** β€” Keep the scheduled prompt short; agents pull detail from rules and golden-path file paths inside those rules. - **Verification** β€” Always run commands from repo root as in `CLAUDE.md` (e.g. `yarn build`, `yarn test`, `yarn lint`). From 8c2b071bac15586b22ea6c1ea99b70d441e30be8 Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 13:58:23 -0700 Subject: [PATCH 09/13] docs: state in-repo automations as VCS for Cursor Automation prompts Made-with: Cursor --- .cursor/automations/enum-shared-type-migration.md | 11 +++++++++-- docs/ai-agents.md | 2 +- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index ec7f06e08..5dfaf1516 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -2,9 +2,16 @@ Daily Jira pickup for epic **DSYS-468** (_Component ADR Migration_ / ADR-0003 & ADR-0004). -**Strategy:** This file matches [docs/ai-agents.md](../../docs/ai-agents.md): _reference over duplication_, _checklists over narratives_, _context efficiency_. It only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` β€” agents must read those files, not improvise from this doc alone. +## Purpose (version control for Cursor Automations) -**Invoke:** `@.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** (`.cursor/rules/enum-shared-type-migration.mdc`). +[Cursor Automations](https://cursor.com/docs/cloud-agent/automations) prompts in the Cursor product are **not** stored in this git repo. This file **is** the **canonical, reviewable spec**: change it here (PRs, `main`, tags) and treat the UI as a **deployment target**. + +- **Stable link** β€” Use a GitHub URL to this path on `main` (or pin a **commit SHA** when you need a frozen prompt). Prefer having the automation run against a branch that **includes** this file, and tell the agent to read `.cursor/automations/enum-shared-type-migration.md` in the workspace; the URL is for humans, pinning, or tooling that fetches raw markdown. +- **Copy-paste** β€” Paste sections (e.g. the cloud prompt block below) into **Private** or **Team Visible** automations. When the spec changes, merge the PR here, then update the pasted prompt or the link you use. + +**Invoke (IDE):** `@.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** (`.cursor/rules/enum-shared-type-migration.mdc`). + +**Strategy:** Matches [docs/ai-agents.md](../../docs/ai-agents.md): _reference over duplication_, _checklists over narratives_, _context efficiency_. This file only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` β€” agents must read those files, not improvise from this doc alone. ## Scope (edit if your epic or identity changes) diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 668d8863a..88d8498d5 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -104,7 +104,7 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i - **Context efficiency** β€” Keep the scheduled prompt short; agents pull detail from rules and golden-path file paths inside those rules. - **Verification** β€” Always run commands from repo root as in `CLAUDE.md` (e.g. `yarn build`, `yarn test`, `yarn lint`). -Repo-specific automation specs (Jira epic, JQL, PR identity notes) live under `.cursor/automations/` alongside opt-in `.cursor/rules/*.mdc` entry points. +Repo-specific automation specs (Jira epic, JQL, PR identity notes) live under `.cursor/automations/` alongside opt-in `.cursor/rules/*.mdc` entry points. Keep specs **in git** on purpose: the Cursor Automations UI has **no native version control**β€”the repo is where you review, diff, and roll forward or back; the UI prompt is a **mirror** (link or copy-paste) of that spec. ### Cursor From 7ca68264e8ba9d9258be3ad6ec5149f1ab5fbb51 Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 24 Mar 2026 14:00:20 -0700 Subject: [PATCH 10/13] chore: remove unrelated migration tracking docs and cursor rule - Drop component-migration-tracking rule and standalone tracker docs - Remove enum-shared-type-migration.mdc; invoke automation via .cursor/automations only - Fix ai-agents and automation doc references Made-with: Cursor --- .../automations/enum-shared-type-migration.md | 2 +- .cursor/rules/component-migration-tracking.md | 227 ------------ .cursor/rules/enum-shared-type-migration.mdc | 13 - docs/ai-agents.md | 2 +- docs/component-migration-project.md | 173 --------- docs/extension-migration-tracker.md | 154 -------- docs/jira-ticket-creation.md | 350 ------------------ docs/mobile-migration-tracker.md | 200 ---------- 8 files changed, 2 insertions(+), 1119 deletions(-) delete mode 100644 .cursor/rules/component-migration-tracking.md delete mode 100644 .cursor/rules/enum-shared-type-migration.mdc delete mode 100644 docs/component-migration-project.md delete mode 100644 docs/extension-migration-tracker.md delete mode 100644 docs/jira-ticket-creation.md delete mode 100644 docs/mobile-migration-tracker.md diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 5dfaf1516..6b3781ea0 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -9,7 +9,7 @@ Daily Jira pickup for epic **DSYS-468** (_Component ADR Migration_ / ADR-0003 & - **Stable link** β€” Use a GitHub URL to this path on `main` (or pin a **commit SHA** when you need a frozen prompt). Prefer having the automation run against a branch that **includes** this file, and tell the agent to read `.cursor/automations/enum-shared-type-migration.md` in the workspace; the URL is for humans, pinning, or tooling that fetches raw markdown. - **Copy-paste** β€” Paste sections (e.g. the cloud prompt block below) into **Private** or **Team Visible** automations. When the spec changes, merge the PR here, then update the pasted prompt or the link you use. -**Invoke (IDE):** `@.cursor/automations/enum-shared-type-migration.md` or the companion rule **enum-shared-type-migration** (`.cursor/rules/enum-shared-type-migration.mdc`). +**Invoke (IDE):** `@.cursor/automations/enum-shared-type-migration.md`. **Strategy:** Matches [docs/ai-agents.md](../../docs/ai-agents.md): _reference over duplication_, _checklists over narratives_, _context efficiency_. This file only defines **orchestration** (Jira, triggers, PR identity). **Implementation guardrails and golden paths** live in `@.cursor/rules/` β€” agents must read those files, not improvise from this doc alone. diff --git a/.cursor/rules/component-migration-tracking.md b/.cursor/rules/component-migration-tracking.md deleted file mode 100644 index 1b8c18030..000000000 --- a/.cursor/rules/component-migration-tracking.md +++ /dev/null @@ -1,227 +0,0 @@ -# Component Migration Tracking - -Guide for tracking component migrations and updating Jira tickets during the migration process. - -## Purpose - -**This rule** provides guidance for: - -- Tracking migration progress in the migration trackers -- Creating Jira tickets for new migrations -- Updating existing tickets with PR links and status - -**NOT for:** - -- Actually implementing the migration (see @.cursor/rules/component-migration.md) - -## When to Use This - -Use this rule when: - -- Starting a new component migration -- Updating migration progress -- Creating adoption tickets for extension/mobile - -## Migration Trackers - -### Extension Tracker - -`docs/extension-migration-tracker.md` - -### Mobile Tracker - -`docs/mobile-migration-tracker.md` - -### Project Overview - -`docs/component-migration-project.md` - -## Workflow - -### 1. Starting a New Migration - -When starting a new component migration: - -```bash -# 1. Update the tracker to mark component as "In Progress" -# Edit docs/extension-migration-tracker.md or docs/mobile-migration-tracker.md - -# 2. Create Jira ticket -gh issue create \ - --title "Migrate [ComponentName] to MMDS" \ - --body "$(cat <<'EOF' -## Summary -Migrate [ComponentName] from [Extension|Mobile] component-library to MMDS - -## Details -- **Source:** ui/components/component-library/[path]/ -- **Target:** @metamask/design-system-[react|react-native] -- **Epic:** [DSYS-272|DSYS-302] - -## Acceptance Criteria -- [ ] Shared types created in design-system-shared -- [ ] React implementation complete -- [ ] React Native implementation complete (if applicable) -- [ ] Storybook stories added -- [ ] Figma Code Connect files added (if applicable) -- [ ] Tests added -- [ ] Migration guide added to package MIGRATION.md -- [ ] Adoption ticket created for [Extension|Mobile] -EOF -)" \ - --label "component-migration" \ - --label "needs-pr" \ - --project "Design System" -``` - -### 2. Updating Progress - -When the migration is complete: - -```bash -# 1. Update tracker status to "Migrated" -# Edit the appropriate tracker file - -# 2. Update Jira ticket with PR link -gh issue close [ticket-number] -# or -gh issue edit [ticket-number] --add-label "done" -``` - -### 3. Creating Adoption Tickets - -After migration is complete, create tickets for adoption in extension/mobile: - -```bash -# Extension Adoption Ticket -gh issue create \ - --title "[Extension] Adopt [ComponentName] from MMDS" \ - --body "$(cat <<'EOF' -## Summary -Replace [ComponentName] in extension with @metamask/design-system-react - -## Migration Guide -See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#[component] - -## Replacement -- Old: import from '../../component-library/[component]' -- New: import from '@metamask/design-system-react' - -## Components to Update -[List all files that need updating] - -## Verification -- [ ] All imports updated -- [ ] Tests pass -- [ ] No TypeScript errors -- [ ] Storybook renders correctly -EOF -)" \ - --label "adoption" \ - --label "extension" - -# Mobile Adoption Ticket -gh issue create \ - --title "[Mobile] Adopt [ComponentName] from MMDS" \ - --body "$(cat <<'EOF' -## Summary -Replace [ComponentName] in mobile with @metamask/design-system-react-native - -## Migration Guide -See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#[component] - -## Replacement -- Old: import from '../../../component-library/components/[ComponentPath]' -- New: import from '@metamask/design-system-react-native' - -## Platforms -- [ ] iOS -- [ ] Android - -## Verification -- [ ] All imports updated -- [ ] Tests pass -- [ ] No TypeScript errors -- [ ] Renders correctly on both platforms -EOF -)" \ - --label "adoption" \ - --label "mobile" -``` - -## Jira API Alternative - -If using the Jira API directly: - -```bash -# Get auth token from environment or config -JIRA_TOKEN="your-token" -JIRA_BASE_URL="https://consensyssoftware.atlassian.net" - -# Create issue under epic -curl -X POST \ - -H "Authorization: Bearer $JIRA_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "fields": { - "project": {"key": "DSYS"}, - "summary": "Migrate ComponentName to MMDS", - "description": { - "type": "doc", - "version": 1, - "content": [ - { - "type": "paragraph", - "content": [ - {"type": "text", "text": "Migration details..."} - ] - } - ] - }, - "issuetype": {"name": "Task"}, - "parent": {"key": "DSYS-272"}, - "labels": ["component-migration"] - } - }' \ - "$JIRA_BASE_URL/rest/api/3/issue" -``` - -## Tracker Update Checklist - -When marking a component as migrated, update ALL of: - -- [ ] `docs/component-migration-project.md` - Main tracker table -- [ ] `docs/extension-migration-tracker.md` OR `docs/mobile-migration-tracker.md` - Platform-specific tracker -- [ ] `packages/design-system-react/MIGRATION.md` OR `packages/design-system-react-native/MIGRATION.md` - Package migration guide -- [ ] Jira ticket - Update with PR link and close/complete - -## Quick Commands - -```bash -# Check if component is in trackers -grep -i "ComponentName" docs/*-migration-tracker.md docs/component-migration-project.md - -# List all migration tickets -gh issue list --label "component-migration" --state all - -# List adoption tickets -gh issue list --label "adoption" --state all - -# View epic progress -# DSYS-272: https://consensyssoftware.atlassian.net/browse/DSYS-272 -# DSYS-302: https://consensyssoftware.atlassian.net/browse/DSYS-302 -``` - -## Epic Links - -| Platform | Epic | URL | -| --------- | -------- | ------------------------------------------------------- | -| Extension | DSYS-272 | https://consensyssoftware.atlassian.net/browse/DSYS-272 | -| Mobile | DSYS-302 | https://consensyssoftware.atlassian.net/browse/DSYS-302 | - -## Related Documentation - -- @.cursor/rules/component-migration.md - Component migration implementation -- @docs/component-migration-project.md - Project overview -- @docs/extension-migration-tracker.md - Extension component tracker -- @docs/mobile-migration-tracker.md - Mobile component tracker diff --git a/.cursor/rules/enum-shared-type-migration.mdc b/.cursor/rules/enum-shared-type-migration.mdc deleted file mode 100644 index 1e8caaab1..000000000 --- a/.cursor/rules/enum-shared-type-migration.mdc +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: enum-shared-type-migration β€” Jira pickup for DSYS-468, assign, transition, open PR as authenticated GitHub user -globs: ['**/*'] -alwaysApply: false ---- - -When invoked (e.g. `@enum-shared-type-migration` or β€œrun enum shared type migration pickup”), follow **every step** in `@.cursor/automations/enum-shared-type-migration.md` using Atlassian Jira for `consensyssoftware.atlassian.net`. - -Follow `@docs/ai-agents.md`: **reference over duplication** β€” pull checklists and golden paths from Layer 2 rules; do not paraphrase long migration steps in chat. - -After a ticket is chosen, **implement** with `@.cursor/rules/component-enum-union-migration.md` (primary), `@.cursor/rules/component-architecture.md`, and `@.cursor/rules/testing.md` β€” not `component-migration.md` (extension/mobile β†’ monorepo only). Use **BadgeStatus** paths in `component-enum-union-migration.md` as the golden reference. - -The automations file is canonical for JQL, pickup mode, Jira updates, PR identity, and the paste-ready cloud prompt. diff --git a/docs/ai-agents.md b/docs/ai-agents.md index 88d8498d5..7d0473a6e 100644 --- a/docs/ai-agents.md +++ b/docs/ai-agents.md @@ -104,7 +104,7 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i - **Context efficiency** β€” Keep the scheduled prompt short; agents pull detail from rules and golden-path file paths inside those rules. - **Verification** β€” Always run commands from repo root as in `CLAUDE.md` (e.g. `yarn build`, `yarn test`, `yarn lint`). -Repo-specific automation specs (Jira epic, JQL, PR identity notes) live under `.cursor/automations/` alongside opt-in `.cursor/rules/*.mdc` entry points. Keep specs **in git** on purpose: the Cursor Automations UI has **no native version control**β€”the repo is where you review, diff, and roll forward or back; the UI prompt is a **mirror** (link or copy-paste) of that spec. +Repo-specific automation specs (Jira epic, JQL, PR identity notes) live under `.cursor/automations/`. Keep specs **in git** on purpose: the Cursor Automations UI has **no native version control**β€”the repo is where you review, diff, and roll forward or back; the UI prompt is a **mirror** (link or copy-paste) of that spec. ### Cursor diff --git a/docs/component-migration-project.md b/docs/component-migration-project.md deleted file mode 100644 index 960e7cb32..000000000 --- a/docs/component-migration-project.md +++ /dev/null @@ -1,173 +0,0 @@ -# Component Migration Project - -**Status:** Active -**Epic - Extension:** [DSYS-272](https://consensyssoftware.atlassian.net/browse/DSYS-272) -**Epic - Mobile:** [DSYS-302](https://consensyssoftware.atlassian.net/browse/DSYS-302) -**Last Updated:** 2026-03-23 - -## Overview - -This document tracks the comprehensive component migration from MetaMask Extension and Mobile component-libraries into the MetaMask Design System (MMDS) monorepo. - -## Migration Scope - -### Extension Components - -**Source:** [metamask-extension/ui/components/component-library](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) -**Target:** `@metamask/design-system-react` -**Epic:** DSYS-272 - -| Component | Status | Replacement | Jira Ticket | Notes | -| ------------- | -------------- | ----------- | ----------- | -------------------------------------------------------------------------------------- | -| BannerAlert | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#banneralert-component) | -| Box | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#box-component) | -| Button | πŸ”„ In Progress | - | - | - | -| ButtonBase | πŸ”„ In Progress | - | - | - | -| ButtonIcon | βœ… Migrated | - | - | - | -| Checkbox | πŸ”„ In Progress | - | - | - | -| Icon | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#icon-component) | -| Text | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react/MIGRATION.md#text-component) | -| TextButton | πŸ”„ In Progress | - | - | - | -| AvatarAccount | ⬜ Pending | - | - | - | -| AvatarBase | ⬜ Pending | - | - | - | -| AvatarFavicon | ⬜ Pending | - | - | - | -| AvatarGroup | ⬜ Pending | - | - | - | -| AvatarIcon | ⬜ Pending | - | - | - | -| AvatarNetwork | ⬜ Pending | - | - | - | -| AvatarToken | ⬜ Pending | - | - | - | -| BadgeCount | ⬜ Pending | - | - | - | -| BadgeIcon | ⬜ Pending | - | - | - | -| BadgeNetwork | ⬜ Pending | - | - | - | -| BadgeStatus | ⬜ Pending | - | - | - | -| BadgeWrapper | ⬜ Pending | - | - | - | -| BannerBase | ⬜ Pending | - | - | - | -| ButtonFilter | ⬜ Pending | - | - | - | -| ButtonHero | ⬜ Pending | - | - | - | -| Card | ⬜ Pending | - | - | - | -| HeaderBase | ⬜ Pending | - | - | - | -| Input | ⬜ Pending | - | - | - | -| Label | ⬜ Pending | - | - | - | -| ListItem | ⬜ Pending | - | - | - | -| Modal | ⬜ Pending | - | - | - | -| RadioButton | ⬜ Pending | - | - | - | -| SearchToken | ⬜ Pending | - | - | - | -| SensitiveText | ⬜ Pending | - | - | - | -| Skeleton | ⬜ Pending | - | - | - | -| Tag | ⬜ Pending | - | - | - | -| TextField | ⬜ Pending | - | - | - | -| Tooltip | ⬜ Pending | - | - | - | - -### Mobile Components - -**Source:** [metamask-mobile/app/component-library](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) -**Target:** `@metamask/design-system-react-native` -**Epic:** DSYS-302 - -| Component | Status | Replacement | Jira Ticket | Notes | -| ------------------ | -------------- | ----------- | ----------- | --------------------------------------------------------------------------------------------- | -| BannerAlert | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#banneralert-component) | -| Box | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#box-component) | -| Button | πŸ”„ In Progress | - | - | - | -| ButtonBase | πŸ”„ In Progress | - | - | - | -| ButtonIcon | βœ… Migrated | - | - | - | -| Checkbox | πŸ”„ In Progress | - | - | - | -| Icon | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#icon-component) | -| Text | βœ… Migrated | - | - | See [MIGRATION.md](../packages/design-system-react-native/MIGRATION.md#text-component) | -| TextButton | πŸ”„ In Progress | - | - | - | -| AvatarAccount | ⬜ Pending | - | - | - | -| AvatarBase | ⬜ Pending | - | - | - | -| AvatarFavicon | ⬜ Pending | - | - | - | -| AvatarGroup | ⬜ Pending | - | - | - | -| AvatarIcon | ⬜ Pending | - | - | - | -| AvatarNetwork | ⬜ Pending | - | - | - | -| AvatarToken | ⬜ Pending | - | - | - | -| BadgeCount | ⬜ Pending | - | - | - | -| BadgeIcon | ⬜ Pending | - | - | - | -| BadgeNetwork | ⬜ Pending | - | - | - | -| BadgeStatus | ⬜ Pending | - | - | - | -| BadgeWrapper | ⬜ Pending | - | - | - | -| BannerBase | ⬜ Pending | - | - | - | -| BottomSheet | ⬜ Pending | - | - | - | -| BottomSheetDialog | ⬜ Pending | - | - | - | -| BottomSheetFooter | ⬜ Pending | - | - | - | -| BottomSheetHeader | ⬜ Pending | - | - | - | -| BottomSheetOverlay | ⬜ Pending | - | - | - | -| ButtonFilter | ⬜ Pending | - | - | - | -| ButtonHero | ⬜ Pending | - | - | - | -| ButtonSemantic | ⬜ Pending | - | - | - | -| Card | ⬜ Pending | - | - | - | -| HeaderBase | ⬜ Pending | - | - | - | -| Input | ⬜ Pending | - | - | - | -| KeyValueRow | ⬜ Pending | - | - | - | -| Label | ⬜ Pending | - | - | - | -| ListItem | ⬜ Pending | - | - | - | -| MainActionButton | ⬜ Pending | - | - | - | -| RadioButton | ⬜ Pending | - | - | - | -| SensitiveText | ⬜ Pending | - | - | - | -| Skeleton | ⬜ Pending | - | - | - | -| TabEmptyState | ⬜ Pending | - | - | - | -| TextField | ⬜ Pending | - | - | - | -| Toast | ⬜ Pending | - | - | - | - -## Status Legend - -| Symbol | Meaning | -| -------------- | --------------------------------------------------- | -| βœ… Migrated | Component migrated to MMDS, migration guide written | -| πŸ”„ In Progress | Migration currently underway | -| ⬜ Pending | Not yet started | -| ❌ Deprecated | Deprecated in source, replacement available | - -## Migration Checklist - -### Per Component (both platforms) - -- [ ] Create shared types in `packages/design-system-shared/src/types/ComponentName/` -- [ ] Create React implementation in `packages/design-system-react/src/components/ComponentName/` -- [ ] Create React Native implementation in `packages/design-system-react-native/src/components/ComponentName/` -- [ ] Add Storybook stories for both platforms -- [ ] Add Figma Code Connect files for both platforms -- [ ] Add tests for both platforms -- [ ] Update package MIGRATION.md with component-specific guide -- [ ] Create Jira ticket for adoption in Extension/Mobile -- [ ] Update this tracker with ticket number and status - -## Jira Ticket Template - -### Epic Tickets - -- **DSYS-272**: Extension Component Migration to MMDS -- **DSYS-302**: Mobile Component Migration to MMDS - -### Component Sub-task Template - -``` -## Summary -Migrate [ComponentName] from [Extension|Mobile] component-library to MMDS - -## Acceptance Criteria -- [ ] Component implemented in design-system-react (if applicable) -- [ ] Component implemented in design-system-react-native (if applicable) -- [ ] Shared types created in design-system-shared -- [ ] Storybook stories added -- [ ] Figma Code Connect files added -- [ ] Tests added -- [ ] Migration guide added to package MIGRATION.md -- [ ] Adoption ticket created for [Extension|Mobile] -``` - -## Related Documentation - -- [Component Migration Strategy](./component-migration-strategy.md) -- [React Migration Guide](../packages/design-system-react/MIGRATION.md) -- [React Native Migration Guide](../packages/design-system-react-native/MIGRATION.md) -- [Component Migration Cursor Rule](../.cursor/rules/component-migration.md) -- [Migration Tracking Cursor Rule](../.cursor/rules/component-migration-tracking.md) - -## References - -- [ADR-0003: Enum to String Union Migration](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0003-enum-to-string-union-migration.md) -- [ADR-0004: Centralized Types Architecture](https://github.com/MetaMask/decisions/blob/main/decisions/design-system/0004-centralized-types-architecture.md) -- [Extension component-library](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) -- [Mobile component-library](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) -- [MMDS Monorepo](https://github.com/MetaMask/metamask-design-system) diff --git a/docs/extension-migration-tracker.md b/docs/extension-migration-tracker.md deleted file mode 100644 index 97456b668..000000000 --- a/docs/extension-migration-tracker.md +++ /dev/null @@ -1,154 +0,0 @@ -# Extension Component Migration Tracker - -**Source:** [metamask-extension/ui/components/component-library](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) -**Target:** `@metamask/design-system-react` -**Epic:** [DSYS-272](https://consensyssoftware.atlassian.net/browse/DSYS-272) -**Last Updated:** 2026-03-23 - -## Summary - -| Status | Count | -| -------------- | ------ | -| βœ… Migrated | 5 | -| πŸ”„ In Progress | 4 | -| ⬜ Pending | 26 | -| **Total** | **35** | - -## βœ… Migrated Components - -These components have been migrated to MMDS and have migration guides. - -| Component | MMDS Location | Migration Guide | Notes | -| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------- | -| BannerAlert | `packages/design-system-react/src/components/BannerAlert/` | [Guide](../packages/design-system-react/MIGRATION.md#banneralert-component) | Severity values standardized | -| Box | `packages/design-system-react/src/components/Box/` | [Guide](../packages/design-system-react/MIGRATION.md#box-component) | Responsive spacing changed | -| ButtonIcon | `packages/design-system-react/src/components/ButtonIcon/` | [Guide](../packages/design-system-react/MIGRATION.md#from-version-0100-to-0110) | Variant prop replacement | -| Icon | `packages/design-system-react/src/components/Icon/` | [Guide](../packages/design-system-react/MIGRATION.md#icon-component) | Color enum changes | -| Text | `packages/design-system-react/src/components/Text/` | [Guide](../packages/design-system-react/MIGRATION.md#text-component) | Font weight separation | - -## πŸ”„ In Progress - -These components are currently being migrated. - -| Component | Owner | Ticket | PR | Notes | -| ---------- | ----- | ------ | --- | ----- | -| Button | - | - | - | - | -| ButtonBase | - | - | - | - | -| Checkbox | - | - | - | - | -| TextButton | - | - | - | - | - -## ⬜ Pending Components - -### Avatar Components - -| Component | Extension Path | Priority | Ticket | Notes | -| ------------- | ------------------------- | -------- | ------ | ----- | -| AvatarAccount | `avatars/avatar-account/` | Medium | - | - | -| AvatarBase | `avatars/avatar-base/` | Medium | - | - | -| AvatarFavicon | `avatars/avatar-favicon/` | Medium | - | - | -| AvatarGroup | `avatars/avatar-group/` | Medium | - | - | -| AvatarIcon | `avatars/avatar-icon/` | Medium | - | - | -| AvatarNetwork | `avatars/avatar-network/` | Medium | - | - | -| AvatarToken | `avatars/avatar-token/` | Medium | - | - | - -### Badge Components - -| Component | Extension Path | Priority | Ticket | Notes | -| ------------ | ---------------- | -------- | ------ | ----- | -| BadgeCount | `badge-count/` | Low | - | - | -| BadgeIcon | `badge-icon/` | Low | - | - | -| BadgeNetwork | `badge-network/` | Low | - | - | -| BadgeStatus | `badge-status/` | Low | - | - | -| BadgeWrapper | `badge-wrapper/` | Low | - | - | - -### Banner Components - -| Component | Extension Path | Priority | Ticket | Notes | -| ---------- | ---------------------- | -------- | ------ | ----- | -| BannerBase | `banners/banner/base/` | Medium | - | - | - -### Button Components - -| Component | Extension Path | Priority | Ticket | Notes | -| ------------ | ---------------- | -------- | ------ | ----- | -| ButtonFilter | `button-filter/` | Medium | - | - | -| ButtonHero | `button-hero/` | Medium | - | - | - -### Form Components - -| Component | Extension Path | Priority | Ticket | Notes | -| --------- | -------------------- | -------- | ------ | ----- | -| Input | `inputs/input/` | High | - | - | -| TextField | `inputs/text-field/` | High | - | - | - -### Layout Components - -| Component | Extension Path | Priority | Ticket | Notes | -| ---------- | -------------- | -------- | ------ | ----- | -| Card | `card/` | Medium | - | - | -| HeaderBase | `header/base/` | Medium | - | - | - -### Other Components - -| Component | Extension Path | Priority | Ticket | Notes | -| ------------- | -------------------- | -------- | ------ | ----- | -| Label | `label/` | Medium | - | - | -| ListItem | `list-items/` | High | - | - | -| Modal | `modal/` | High | - | - | -| RadioButton | `radio/RadioButton/` | Medium | - | - | -| SearchToken | `search-token/` | Low | - | - | -| SensitiveText | `sensitive-text/` | Low | - | - | -| Skeleton | `skeleton/` | Low | - | - | -| Tag | `tag/` | Low | - | - | -| Tooltip | `tooltip/` | Medium | - | - | - -## Migration Workflow - -### Step 1: Audit Component - -1. Locate component in extension: `ui/components/component-library/[component-path]/` -2. Document current API (props, types, variants) -3. Check if shared types already exist in `packages/design-system-shared/src/types/` - -### Step 2: Create Migration Plan - -1. Identify shared props vs platform-specific props -2. Decide on Conservative vs Unified approach -3. Create comparison table (Extension API vs MMDS patterns) - -### Step 3: Implement - -```bash -# Create component scaffolding -yarn create-component:react --name ComponentName --description "Brief description" - -# Follow component-migration.md workflow -``` - -### Step 4: Document - -1. Add migration section to `packages/design-system-react/MIGRATION.md` -2. Create adoption ticket for extension - -### Step 5: Track - -1. Update this tracker with: - - Jira ticket number - - PR link - - Migration completion date - -## Quick Reference - -| Task | Command | -| ---------------------- | ------------------------------------------------------------------- | -| Check component status | Search this file for component name | -| Update status | Edit this file and commit | -| Create ticket | Use Jira API or web UI with template | -| View epic | [DSYS-272](https://consensyssoftware.atlassian.net/browse/DSYS-272) | - -## Related Documentation - -- [Project Overview](./component-migration-project.md) -- [Migration Strategy](./component-migration-strategy.md) -- [Component Migration Cursor Rule](../.cursor/rules/component-migration.md) -- [Extension Source](https://github.com/MetaMask/metamask-extension/tree/main/ui/components/component-library) diff --git a/docs/jira-ticket-creation.md b/docs/jira-ticket-creation.md deleted file mode 100644 index d3a8b237d..000000000 --- a/docs/jira-ticket-creation.md +++ /dev/null @@ -1,350 +0,0 @@ -# Jira Ticket Creation Guide - -Guide for creating and managing Jira tickets for component migrations. - -## Epic Structure - -| Platform | Epic | Key | URL | -| --------- | ----------------------------- | -------- | ------------------------------------------------------- | -| Extension | Extension Component Migration | DSYS-272 | https://consensyssoftware.atlassian.net/browse/DSYS-272 | -| Mobile | Mobile Component Migration | DSYS-302 | https://consensyssoftware.atlassian.net/browse/DSYS-302 | - -## Ticket Types - -### 1. Migration Ticket (Sub-task) - -Created under the epic when starting a component migration. - -**Template:** - -``` -Summary: Migrate [ComponentName] to MMDS -Type: Sub-task -Parent: DSYS-272 (Extension) or DSYS-302 (Mobile) -Labels: component-migration -``` - -**Acceptance Criteria:** - -``` -- [ ] Shared types created in design-system-shared -- [ ] React implementation complete (if applicable) -- [ ] React Native implementation complete (if applicable) -- [ ] Storybook stories added -- [ ] Figma Code Connect files added (if applicable) -- [ ] Tests added -- [ ] Migration guide added to package MIGRATION.md -- [ ] Adoption ticket created for [Extension|Mobile] -``` - -### 2. Adoption Ticket - -Created after migration is complete, to track adoption in the platform. - -**Template:** - -``` -Summary: [Extension|Mobile] - Adopt [ComponentName] from MMDS -Type: Task -Labels: adoption, extension OR mobile -Epic: DSYS-272 (Extension) or DSYS-302 (Mobile) -``` - -## Creating Tickets - -### Using GitHub CLI (Recommended) - -```bash -# Migration Ticket -gh issue create \ - --title "Migrate [ComponentName] to MMDS" \ - --body "$(cat <<'EOF' -## Summary -Migrate [ComponentName] from [Extension|Mobile] component-library to MMDS - -## Details -- **Source:** ui/components/component-library/[path]/ -- **Target:** @metamask/design-system-[react|react-native] -- **Epic:** DSYS-272 (Extension) or DSYS-302 (Mobile) - -## Migration Guide -See package MIGRATION.md for component-specific guidance. - -## Acceptance Criteria -- [ ] Shared types created in design-system-shared -- [ ] React implementation complete -- [ ] React Native implementation complete (if applicable) -- [ ] Storybook stories added -- [ ] Figma Code Connect files added (if applicable) -- [ ] Tests added -- [ ] Migration guide added to package MIGRATION.md -- [ ] Adoption ticket created for [Extension|Mobile] -EOF -)" \ - --label "component-migration" \ - --label "needs-pr" - -# Extension Adoption Ticket -gh issue create \ - --title "[Extension] Adopt [ComponentName] from MMDS" \ - --body "$(cat <<'EOF' -## Summary -Replace [ComponentName] in extension with @metamask/design-system-react - -## Migration Guide -See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#[component] - -## Replacement -- Old: import from '../../component-library/[component]' -- New: import from '@metamask/design-system-react' - -## Components to Update -[List all files that need updating] - -## Verification -- [ ] All imports updated -- [ ] Tests pass -- [ ] No TypeScript errors -- [ ] Storybook renders correctly -EOF -)" \ - --label "adoption" \ - --label "extension" - -# Mobile Adoption Ticket -gh issue create \ - --title "[Mobile] Adopt [ComponentName] from MMDS" \ - --body "$(cat <<'EOF' -## Summary -Replace [ComponentName] in mobile with @metamask/design-system-react-native - -## Migration Guide -See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#[component] - -## Replacement -- Old: import from '../../../component-library/components/[ComponentPath]' -- New: import from '@metamask/design-system-react-native' - -## Platforms -- [ ] iOS -- [ ] Android - -## Verification -- [ ] All imports updated -- [ ] Tests pass -- [ ] No TypeScript errors -- [ ] Renders correctly on both platforms -EOF -)" \ - --label "adoption" \ - --label "mobile" -``` - -### Using Jira REST API - -#### Authentication - -Set up your Jira API token: - -```bash -# Option 1: Environment variable -export JIRA_TOKEN="your-api-token" -export JIRA_EMAIL="your-email@consensys.net" -export JIRA_BASE_URL="https://consensyssoftware.atlassian.net" - -# Option 2: .env file (gitignored) -echo "JIRA_TOKEN=your-token" >> .env -echo "JIRA_EMAIL=your-email@consensys.net" >> .env -``` - -#### Create Migration Ticket - -```bash -curl -X POST \ - -H "Authorization: Basic $(echo -n $JIRA_EMAIL:$JIRA_TOKEN | base64)" \ - -H "Content-Type: application/json" \ - -d '{ - "fields": { - "project": {"key": "DSYS"}, - "summary": "Migrate ComponentName to MMDS", - "description": { - "type": "doc", - "version": 1, - "content": [ - { - "type": "heading", - "attrs": {"level": 2}, - "content": [{"type": "text", "text": "Summary"}] - }, - { - "type": "paragraph", - "content": [{"type": "text", "text": "Migrate ComponentName from [Extension|Mobile] component-library to MMDS."}] - }, - { - "type": "heading", - "attrs": {"level": 2}, - "content": [{"type": "text", "text": "Details"}] - }, - { - "type": "bulletList", - "content": [ - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Source: ui/components/component-library/[path]/"}]}]}, - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Target: @metamask/design-system-[react|react-native]"}]}]} - ] - }, - { - "type": "heading", - "attrs": {"level": 2}, - "content": [{"type": "text", "text": "Acceptance Criteria"}] - }, - { - "type": "orderedList", - "content": [ - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Shared types created in design-system-shared"}]}]}, - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "React implementation complete"}]}]}, - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "React Native implementation complete"}]}]}, - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Storybook stories added"}]}]}, - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Tests added"}]}]}, - {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Migration guide added"}]}]} - ] - } - ] - }, - "issuetype": {"name": "Sub-task"}, - "parent": {"key": "DSYS-272"}, - "labels": ["component-migration"] - } - }' \ - "$JIRA_BASE_URL/rest/api/3/issue" -``` - -#### Create Adoption Ticket - -```bash -curl -X POST \ - -H "Authorization: Basic $(echo -n $JIRA_EMAIL:$JIRA_TOKEN | base64)" \ - -H "Content-Type: application/json" \ - -d '{ - "fields": { - "project": {"key": "DSYS"}, - "summary": "[Extension] Adopt ComponentName from MMDS", - "description": { - "type": "doc", - "version": 1, - "content": [ - { - "type": "paragraph", - "content": [{"type": "text", "text": "Replace ComponentName in extension with @metamask/design-system-react."}] - }, - { - "type": "heading", - "attrs": {"level": 2}, - "content": [{"type": "text", "text": "Migration Guide"}] - }, - { - "type": "paragraph", - "content": [{"type": "text", "text": "See: https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#component"}] - }, - { - "type": "heading", - "attrs": {"level": 2}, - "content": [{"type": "text", "text": "Replacement"}] - }, - { - "type": "codeBlock", - "attrs": {"language": "typescript"}, - "content": [ - {"type": "text", "text": "// Old\nimport { ComponentName } from '../../component-library/component';\n\n// New\nimport { ComponentName } from '@metamask/design-system-react';"} - ] - } - ] - }, - "issuetype": {"name": "Task"}, - "labels": ["adoption", "extension"], - "priority": {"name": "Medium"} - } - }' \ - "$JIRA_BASE_URL/rest/api/3/issue" -``` - -## Bulk Ticket Creation - -To create tickets for all pending components: - -```bash -#!/bin/bash -# create-migration-tickets.sh - -COMPONENTS=( - "AvatarAccount" - "AvatarBase" - "AvatarFavicon" - "AvatarGroup" - "AvatarIcon" - "AvatarNetwork" - "AvatarToken" -) - -for component in "${COMPONENTS[@]}"; do - gh issue create \ - --title "Migrate $component to MMDS" \ - --body "## Summary -Migrate $component from extension component-library to MMDS - -## Details -- **Source:** ui/components/component-library/[component-path]/ -- **Target:** @metamask/design-system-react -- **Epic:** DSYS-272 - -## Acceptance Criteria -- [ ] Shared types created -- [ ] React implementation complete -- [ ] Storybook stories added -- [ ] Tests added -- [ ] Migration guide added -- [ ] Adoption ticket created" \ - --label "component-migration" \ - --label "needs-pr" - - echo "Created ticket for: $component" -done -``` - -## Ticket Labels - -| Label | Description | -| ------------------- | ---------------------------------------------- | -| component-migration | Ticket for migrating a component to MMDS | -| adoption | Ticket for adopting MMDS component in platform | -| extension | Extension-specific ticket | -| mobile | Mobile-specific ticket | -| needs-pr | Waiting for PR | -| blocked | Blocked on dependency | - -## Viewing Epic Progress - -### Web UI - -- Extension Epic: https://consensyssoftware.atlassian.net/browse/DSYS-272 -- Mobile Epic: https://consensyssoftware.atlassian.net/browse/DSYS-302 - -### CLI - -```bash -# List all component migration tickets -gh issue list --label "component-migration" --state all - -# List by platform -gh issue list --label "component-migration" --label "extension" --state open -gh issue list --label "component-migration" --label "mobile" --state open - -# List adoption tickets -gh issue list --label "adoption" --state open -``` - -## Related Documentation - -- @.cursor/rules/component-migration-tracking.md - Tracking workflow -- @docs/component-migration-project.md - Project overview -- @docs/extension-migration-tracker.md - Extension tracker -- @docs/mobile-migration-tracker.md - Mobile tracker diff --git a/docs/mobile-migration-tracker.md b/docs/mobile-migration-tracker.md deleted file mode 100644 index 8a85451a3..000000000 --- a/docs/mobile-migration-tracker.md +++ /dev/null @@ -1,200 +0,0 @@ -# Mobile Component Migration Tracker - -**Source:** [metamask-mobile/app/component-library](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) -**Target:** `@metamask/design-system-react-native` -**Epic:** [DSYS-302](https://consensyssoftware.atlassian.net/browse/DSYS-302) -**Last Updated:** 2026-03-23 - -## Summary - -| Status | Count | -| -------------- | ------ | -| βœ… Migrated | 5 | -| πŸ”„ In Progress | 4 | -| ⬜ Pending | 38 | -| **Total** | **47** | - -## βœ… Migrated Components - -These components have been migrated to MMDS and have migration guides. - -| Component | MMDS Location | Migration Guide | Notes | -| ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------ | -| BannerAlert | `packages/design-system-react-native/src/components/BannerAlert/` | [Guide](../packages/design-system-react-native/MIGRATION.md#banneralert-component) | Errorβ†’Danger rename | -| Box | `packages/design-system-react-native/src/components/Box/` | [Guide](../packages/design-system-react-native/MIGRATION.md#box-component) | Custom spacing via twClassName | -| ButtonIcon | `packages/design-system-react-native/src/components/ButtonIcon/` | [Guide](../packages/design-system-react-native/MIGRATION.md#from-version-0100-to-0110) | Variant prop replacement | -| Icon | `packages/design-system-react-native/src/components/Icon/` | [Guide](../packages/design-system-react-native/MIGRATION.md#icon-component) | Size/color enum changes | -| Text | `packages/design-system-react-native/src/components/Text/` | [Guide](../packages/design-system-react-native/MIGRATION.md#text-component) | Font weight separation | - -## πŸ”„ In Progress - -These components are currently being migrated. - -| Component | Owner | Ticket | PR | Notes | -| ---------- | ----- | ------ | --- | ----- | -| Button | - | - | - | - | -| ButtonBase | - | - | - | - | -| Checkbox | - | - | - | - | -| TextButton | - | - | - | - | - -## ⬜ Pending Components - -### Avatar Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ------------- | ----------------------------------- | -------- | ------ | ----- | -| AvatarAccount | `components/Avatars/AvatarAccount/` | Medium | - | - | -| AvatarBase | `components/Avatars/AvatarBase/` | Medium | - | - | -| AvatarFavicon | `components/Avatars/AvatarFavicon/` | Medium | - | - | -| AvatarGroup | `components/Avatars/AvatarGroup/` | Medium | - | - | -| AvatarIcon | `components/Avatars/AvatarIcon/` | Medium | - | - | -| AvatarNetwork | `components/Avatars/AvatarNetwork/` | Medium | - | - | -| AvatarToken | `components/Avatars/AvatarToken/` | Medium | - | - | - -### Badge Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ------------ | -------------------------------- | -------- | ------ | ----- | -| BadgeCount | `components/Badge/BadgeCount/` | Low | - | - | -| BadgeIcon | `components/Badge/BadgeIcon/` | Low | - | - | -| BadgeNetwork | `components/Badge/BadgeNetwork/` | Low | - | - | -| BadgeStatus | `components/Badge/BadgeStatus/` | Low | - | - | -| BadgeWrapper | `components/Badge/BadgeWrapper/` | Low | - | - | - -### Banner Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ---------- | --------------------------------- | -------- | ------ | ----- | -| BannerBase | `components/Banners/Banner/base/` | Medium | - | - | - -### Bottom Sheet Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ------------------ | -------------------------------------------- | -------- | ------ | ----- | -| BottomSheet | `components/BottomSheet/BottomSheet/` | High | - | - | -| BottomSheetDialog | `components/BottomSheet/BottomSheetDialog/` | High | - | - | -| BottomSheetFooter | `components/BottomSheet/BottomSheetFooter/` | High | - | - | -| BottomSheetHeader | `components/BottomSheet/BottomSheetHeader/` | High | - | - | -| BottomSheetOverlay | `components/BottomSheet/BottomSheetOverlay/` | High | - | - | - -### Button Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| -------------- | ----------------------------------- | -------- | ------ | ----- | -| ButtonFilter | `components/Button/ButtonFilter/` | Medium | - | - | -| ButtonHero | `components/Button/ButtonHero/` | Medium | - | - | -| ButtonSemantic | `components/Button/ButtonSemantic/` | Medium | - | - | - -### Card Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| --------- | ----------------------- | -------- | ------ | ----- | -| Card | `components/Card/Card/` | Medium | - | - | - -### Form Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| --------- | --------------------------------- | -------- | ------ | ----- | -| Input | `components/Input/Input/` | High | - | - | -| TextField | `components/TextField/TextField/` | High | - | - | - -### Header Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ---------- | ------------------------------- | -------- | ------ | ----- | -| HeaderBase | `components/Header/HeaderBase/` | Medium | - | - | - -### KeyValue Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ----------- | ------------------------- | -------- | ------ | ----- | -| KeyValueRow | `components/KeyValueRow/` | Medium | - | - | - -### Layout Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| --------- | --------------------------- | -------- | ------ | ----- | -| Label | `components/Label/` | Medium | - | - | -| ListItem | `components/List/ListItem/` | High | - | - | - -### Other Components - -| Component | Mobile Path | Priority | Ticket | Notes | -| ---------------- | ----------------------------------------- | -------- | ------ | ----- | -| MainActionButton | `components/Buttons/MainActionButton/` | Medium | - | - | -| RadioButton | `components/RadioButton/RadioButton/` | Medium | - | - | -| SensitiveText | `components/SensitiveText/SensitiveText/` | Low | - | - | -| Skeleton | `components/Skeleton/Skeleton/` | Low | - | - | -| TabEmptyState | `components/TabEmptyState/TabEmptyState/` | Low | - | - | -| Toast | `components/Toast/Toast/` | Medium | - | - | - -## Migration Workflow - -### Step 1: Audit Component - -1. Locate component in mobile: `app/component-library/components/[ComponentPath]/` -2. Document current API (props, types, variants) -3. Check if shared types already exist in `packages/design-system-shared/src/types/` - -### Step 2: Create Migration Plan - -1. Identify shared props vs platform-specific props -2. Decide on Conservative vs Unified approach -3. Create comparison table (Mobile API vs MMDS patterns) - -### Step 3: Implement - -```bash -# Create component scaffolding -yarn create-component:react-native --name ComponentName --description "Brief description" - -# Follow component-migration.md workflow -``` - -### Step 4: Document - -1. Add migration section to `packages/design-system-react-native/MIGRATION.md` -2. Create adoption ticket for mobile - -### Step 5: Track - -1. Update this tracker with: - - Jira ticket number - - PR link - - Migration completion date - -## Quick Reference - -| Task | Command | -| ---------------------- | ------------------------------------------------------------------- | -| Check component status | Search this file for component name | -| Update status | Edit this file and commit | -| Create ticket | Use Jira API or web UI with template | -| View epic | [DSYS-302](https://consensyssoftware.atlassian.net/browse/DSYS-302) | - -## Mobile-Specific Considerations - -### React Native Patterns - -- Use `twClassName` instead of `className` -- Use `Pressable` instead of `onClick` (use `onPress`) -- Use `twrnc` preset for Tailwind utilities -- Test on both iOS and Android - -### Native-Specific Components - -The following components are React Native specific (not in web package): - -- BottomSheet family -- Toast -- KeyValueRow -- MainActionButton -- TabEmptyState -- Skeleton - -## Related Documentation - -- [Project Overview](./component-migration-project.md) -- [Migration Strategy](./component-migration-strategy.md) -- [Component Migration Cursor Rule](../.cursor/rules/component-migration.md) -- [Mobile Source](https://github.com/MetaMask/metamask-mobile/tree/main/app/component-library) From b7ee51b32cdfead60af7d6a08e29e71260cffb00 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 24 Mar 2026 21:05:21 +0000 Subject: [PATCH 11/13] cursor: remove hardcoded assignee from DSYS board reference link to show full epic scope --- .cursor/automations/enum-shared-type-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 6b3781ea0..6a1967749 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -18,7 +18,7 @@ Daily Jira pickup for epic **DSYS-468** (_Component ADR Migration_ / ADR-0003 & | Setting | Value | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Epic | **DSYS-468** β€” _Component ADR Migration: Align with ADR-0003 and ADR-0004_ | -| Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?assignee=6152e94cc7bea40069d6b9c3&issueParent=343549) | +| Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?issueParent=343549) | ## 1. Find candidates From 4a032652935132d441e3ad7373b0da6fdbfdd581 Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Fri, 27 Mar 2026 12:39:10 -0700 Subject: [PATCH 12/13] Add post-merge GitHub trigger flow for Jira closure --- .../automations/enum-shared-type-migration.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 6b3781ea0..969f75ced 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -159,3 +159,44 @@ You are in the MetaMask design-system monorepo. Follow docs/ai-agents.md: refere ``` Optional: `@`-mention `@.cursor/automations/enum-shared-type-migration.md` in the automation prompt so the agent loads JQL + PR-identity notes from this file. + +## 7. Post-merge automation: close Jira ticket + +Use a second automation for completion/closure. + +### Trigger + +- **GitHub trigger:** **Pull request merged** +- This runs only when a PR is merged. + +### Required tools + +- **MCP server** enabled in the automation. +- **GitHub MCP** connected (to inspect the triggering PR). +- **Atlassian/Jira MCP** connected (to transition the linked Jira issue). + +### Decision rules + +1. Read the triggering PR metadata (title/body/branch/labels). +2. Continue only if it is an enum-to-union/shared-type migration PR for this stream. +3. Extract Jira key (e.g. `DSYS-476`) from title/body. +4. Fetch transitions and move the issue to the workflow’s done state (`Done` / equivalent). +5. Add a Jira comment with the merged PR link and merge commit SHA. +6. If no Jira key or no matching transition is available, leave a comment and exit without changing status. + +### Cloud automation β€” example prompt (PR merged -> Jira Done) + +```text +Triggered by a GitHub "Pull request merged" event. + +Use MCP tools only: +- GitHub MCP to read the triggering PR +- Atlassian/Jira MCP to update Jira + +Workflow: +1) Inspect triggering PR title/body/labels/branch. Only continue if this is an enum-union/shared-type migration PR in this repo flow. +2) Extract Jira key from PR title/body (format DSYS-). If none, stop and log why. +3) In Jira, get available transitions for that issue and transition to Done (or closest done-category status in this workflow). +4) Add Jira comment: include PR URL, PR number, merge commit SHA, and date. +5) Output one concise summary line with issue key + final status. +``` From 2594fa93c83858eb81710997cea891e0a394adbe Mon Sep 17 00:00:00 2001 From: georgewrmarshall Date: Tue, 31 Mar 2026 18:24:24 -0700 Subject: [PATCH 13/13] chore: lint fix --- .cursor/automations/enum-shared-type-migration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.cursor/automations/enum-shared-type-migration.md b/.cursor/automations/enum-shared-type-migration.md index 4221b8211..2385a42e2 100644 --- a/.cursor/automations/enum-shared-type-migration.md +++ b/.cursor/automations/enum-shared-type-migration.md @@ -15,9 +15,9 @@ Daily Jira pickup for epic **DSYS-468** (_Component ADR Migration_ / ADR-0003 & ## Scope (edit if your epic or identity changes) -| Setting | Value | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Epic | **DSYS-468** β€” _Component ADR Migration: Align with ADR-0003 and ADR-0004_ | +| Setting | Value | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Epic | **DSYS-468** β€” _Component ADR Migration: Align with ADR-0003 and ADR-0004_ | | Board (reference) | [DSYS board β€” epic filter](https://consensyssoftware.atlassian.net/jira/software/c/projects/DSYS/boards/1888?issueParent=343549) | ## 1. Find candidates