Description

Adds comprehensive cursor rule for component creation incorporating ADR-0003 (enum to string union migration), ADR-0004 (centralized types architecture), and platform-specific props patterns. Includes proof-of-concept BadgeStatus migration demonstrating the complete architectural approach.

Key insight: The rule focuses on what to do after running create-component scripts, since the generated templates don't yet implement these patterns. This ensures the rule stays relevant even as templates evolve.

What Changed

1. Component Creation Cursor Rule: .cursor/rules/component-creation.md (600+ lines)

   • Platform-Specific Props Pattern: Added comprehensive guidance on handling cross-platform differences
   • Layered Architecture: Decision tree table showing what goes in shared vs platform layers
   • Reference-Based Approach: Points to templates instead of duplicating content
   • BadgeStatus Examples: Replaced Button examples with migrated BadgeStatus to show real implementation
   • Enhanced Verification: Updated checklist with platform-specific checks

2. BadgeStatus Migration (Proof-of-Concept):

   • Shared Package: Created types/BadgeStatus/ with ADR-0003 pattern (const objects)
   • React Package: Re-exports shared types, extends with className and React-specific props
   • React Native Package: Re-exports shared types, extends with twClassName and React Native props
   • Type Cleanup: Removed old enum definitions from both platform packages

3. Updated CLAUDE.md:

   • Added reference to component-creation.md rule
   • Added create-component:react-native command

Platform-Specific Props (Layered Architecture)

New guidance for handling cross-platform differences while maximizing consistency:

Philosophy: Use idiomatic platform APIs (onClick vs onPress) rather than unified abstractions. This maintains platform conventions and developer familiarity.

Key Architectural Patterns

ADR-0003 Pattern (Const Objects with String Unions):

// Before (generated template):
export enum BadgeStatusStatus {
  Active = 'active',
  Inactive = 'inactive',
}

// After (ADR-0003):
export const BadgeStatusStatus = {
  Active: 'active',
  Inactive: 'inactive',
} as const;
export type BadgeStatusStatus = 
  (typeof BadgeStatusStatus)[keyof typeof BadgeStatusStatus];

ADR-0004 Pattern (Centralized Types):

// Shared package - Design system concerns only
export type BadgeStatusPropsShared = {
  status: BadgeStatusStatus;
  hasBorder?: boolean;
  size?: BadgeStatusSize;
};

// React package - Platform-specific extension
export type BadgeStatusProps = 
  ComponentProps<'div'> &
  BadgeStatusPropsShared & {
    className?: string;
    style?: React.CSSProperties;
  };

// React Native package - Platform-specific extension
export type BadgeStatusProps = 
  BadgeStatusPropsShared &
  Omit<ViewProps, 'children'> & {
    twClassName?: string;
  };

Before/After Comparison (BadgeStatus)

Before (Duplicated Enums in Each Platform):

• packages/design-system-react/src/types/index.ts:

  export enum BadgeStatusStatus { Active = 'active', ... }
  export enum BadgeStatusSize { Md = 'md', Lg = 'lg' }

• packages/design-system-react-native/src/types/index.ts:

  export enum BadgeStatusStatus { Active = 'active', ... }
  export enum BadgeStatusSize { Md = 'md', Lg = 'lg' }

• Total: ~40 lines duplicated

After (Shared Source + Platform Extensions):

• packages/design-system-shared/src/types/BadgeStatus/:

  export const BadgeStatusStatus = { Active: 'active', ... } as const;
  export const BadgeStatusSize = { Md: 'md', Lg: 'lg' } as const;
  export type BadgeStatusPropsShared = { status, hasBorder, size };

• Platform packages: Re-export shared, extend with className/twClassName
• Result: Single source of truth, zero duplication

Why Reference-Based Instead of Duplicating Templates?

The rule is intentionally reference-based rather than duplicating template content:

✅ Stays maintainable - Template updates don't require rule updates
✅ Focuses on gaps - Guides patterns NOT in templates (ADR-0003/0004)
✅ Post-generation workflow - What to do after scripts run
✅ Explicit about template limitations - "Templates DO NOT include this pattern yet"

Testing Results

• ✅ Build passes (yarn build)
• ✅ Tests pass (yarn test)
• ✅ Linting passes (yarn lint)
• ✅ TypeScript compilation successful
• ✅ No breaking changes to BadgeStatus component API
• ✅ Import paths unchanged (consumers don't need updates)

Related issues

Relates to:

• ADR-0003: Enum to String Union Migration
• ADR-0004: Centralized Types Architecture

Manual testing steps

1. Test Component Creation Workflow:

   • Start a new Claude Code or Cursor session
   • Ask: "Create a new Button component with variants"
   • Verify the AI agent:
     • Uses yarn create-component:react and yarn create-component:react-native
     • Moves types to @metamask/design-system-shared
     • Converts types to const objects + string unions (not enums)
     • Understands platform-specific props (className vs twClassName)
     • Creates identical shared APIs for React and React Native

2. Verify BadgeStatus Migration:

   • Build passes: yarn build
   • Tests pass: yarn test
   • Lint passes: yarn lint
   • Import BadgeStatusStatus from both React and React Native packages
   • Verify types resolve correctly
   • Check component behavior unchanged

3. Check Cross-Platform Consistency:

   • Compare BadgeStatusPropsShared exports
   • Verify platform packages have identical shared props
   • Confirm platform-specific differences only in extension layer

Screenshots/Recordings

Before

Component creation rule existed but was missing:

• Platform-specific props guidance (onClick/onPress, className/twClassName)
• Decision tree for shared vs platform concerns
• Real migration example
• BadgeStatus used old enum pattern with duplication

After

Component creation rule provides:

• Platform-Specific Props Section: Layered architecture pattern
• Decision Tree Table: Clear guidance on shared vs platform
• BadgeStatus Examples: Real migrated component showing patterns
• Verification Checklist: Platform-specific validation steps
• Proof-of-Concept: BadgeStatus migrated using patterns

Pre-merge author checklist

• I've followed MetaMask Contributor Docs
• I've completed the PR template to the best of my ability
• I've included tests if applicable (existing tests pass)
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

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

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com