## **Description**

Adds `component-enum-union-migration.md` cursor rule providing workflow
for refactoring existing monorepo components to ADR-0003 (const objects)
and ADR-0004 (centralized types) patterns. This rule is specifically for
internal cleanup of components with duplicate const object definitions
across React and React Native packages.

**When to use this workflow:**
- Component already exists in both React and React Native packages
- Const objects are duplicated across platform packages
- Types are defined separately in each platform (no shared source)
- Component API needs to be unified/modernized

**Key workflow documented:**
1. Identify components with duplicate const objects across platforms
2. Create shared types in `@metamask/design-system-shared` package
3. Update React package to import (not re-export) shared types
4. Update React Native package to import (not re-export) shared types
5. Remove old duplicates from platform type indices
6. Update component index.ts to export directly from shared
7. Verify build/test/lint

**Critical mistakes documented:**
- Re-exporting const objects from `.types.ts` files (causes test
coverage loss)
- Using `interface` instead of `type` for shared props (ESLint error)
- Separate type exports causing "Duplicate identifier" TypeScript errors
- Wrong import ordering (platform imports before shared imports)
- Including platform-specific props in shared types (violates ADR-0004)

**Why this matters:**
The BadgeCount migration (PR #942) revealed that duplicate const object
exports in `.types.ts` files create uncovered code paths, failing Jest
coverage thresholds at 81.81% instead of 100%. This rule documents the
exact two-file pattern needed to prevent this issue.

**Relationship to other rules:**
- Depends on: `component-architecture.md` (foundational ADR patterns)
- Different from: `component-creation.md` (new components) and
`component-migration.md` (extension/mobile migration)
- Use case: Internal monorepo cleanup only

**References:**
- Golden path: BadgeStatus component (SOURCE OF TRUTH for shared types)
- Complete example: PR #912 (full migration with all file changes)
- Validation: BadgeCount PR #942 (demonstrated coverage issue and fix)

## **Related issues**

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

## **Manual testing steps**

1. Review the cursor rule file:
`.cursor/rules/component-enum-union-migration.md`
2. Verify it references BadgeCount PR #942 and PR #912
3. Check workflow steps match the BadgeCount migration pattern
4. Confirm anti-patterns section shows duplicate export mistake
5. Verify it clarifies this is NOT for new components
6. Check golden path examples reference BadgeStatus implementation
7. Confirm verification checklist covers both platforms
8. Verify CLAUDE.md includes reference to this new rule

## **Screenshots/Recordings**

N/A - Documentation only

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs)
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable (N/A - documentation)
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable (N/A - markdown)
- [ ] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation-only changes: adds an internal workflow guide and links
it from `CLAUDE.md`, with no runtime or build impact.
> 
> **Overview**
> Adds a new Cursor rule,
`.cursor/rules/component-enum-union-migration.md`, documenting a
step-by-step workflow to migrate existing cross-platform components from
duplicated enums/consts to **shared const-object + string-union types**
per ADR-0003/ADR-0004, including common pitfalls (notably avoiding const
re-exports from `.types.ts` to prevent coverage drops).
> 
> Updates `CLAUDE.md` to reference this new rule in the AI-agent
documentation list.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
690c364. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->