enhance-component

Enhance Component Workflow

Help improve or extend an existing gluestack-ui component. This skill guides you through safely modifying existing components while maintaining backward compatibility and following established patterns.

When to Use This Skill

• Adding new variants to an existing component
• Adding new features or sub-components
• Fixing bugs in existing components
• Improving accessibility
• Enhancing performance
• Updating to new dependencies

Critical Requirements When Enhancing

1. ALWAYS use correct import paths - @gluestack-ui/core/[component]/creator not @gluestack-ui/[component]
2. ALWAYS use semantic color tokens from src/components/ui/gluestack-ui-provider/config.ts
3. ALWAYS respect existing animation library - don't switch libraries without user approval
4. NEVER edit apps/ directory - only edit src/components/ui/
5. ALWAYS maintain proper exports in core package barrel files

Workflow

PHASE 1: Component Selection & Analysis

Step 1.1: Identify Component

Ask the user:

questions:
  - question: "Which component would you like to enhance?"
    header: "Component"
    multiSelect: false
    options:
      - label: "List component name"
        description: "E.g., button, accordion, alert-dialog"

Step 1.2: Read Existing Implementation

Use Read tool to understand current implementation:

1. Read src/components/ui/[component]/index.tsx
2. Read src/components/ui/[component]/styles.tsx
3. Read packages/gluestack-core/src/[component]/creator/index.tsx (if exists)
4. Read src/components/ui/[component]/docs/index.mdx
5. Check examples in src/components/ui/[component]/examples/

Step 1.3: Understand What Needs Enhancement

Ask the user:

• What needs to be changed or added?
• Is this a bug fix or new feature?
• Are there breaking changes?
• What's the expected behavior?

PHASE 2: Impact Analysis

Step 2.1: Check Usage

Use Grep to find where the component is used:

# Search for component usage in examples
Grep: "import.*from.*[component-name]" in src/components/ui/

# Check documentation
Grep: "[ComponentName]" in src/components/ui/**/docs/

Step 2.2: Identify Breaking Changes

Analyze if the enhancement:

• Changes existing prop names or types
• Removes functionality
• Changes default behavior
• Requires migration

If breaking changes exist:

• Document migration path
• Consider deprecation warnings
• Provide backward compatibility if possible

Step 2.3: Present Impact Analysis

Show the user:

## Impact Analysis

### Files to Modify:
- [ ] src/components/ui/[component]/index.tsx
- [ ] src/components/ui/[component]/styles.tsx
- [ ] packages/gluestack-core/src/[component]/creator/index.tsx
- [ ] src/components/ui/[component]/docs/index.mdx
- [ ] examples

### Breaking Changes:
[List any breaking changes]

### Migration Required:
[If yes, explain migration path]

### Affected Examples:
[List examples that need updates]

CHECKPOINT 1: Get user confirmation on impact and approach

PHASE 3: Enhancement Design

Step 3.1: Design the Enhancement

Based on the type of enhancement:

For New Variants:

// Before
variants: {
  size: {
    sm: '...',
    md: '...',
    lg: '...',
  }
}

// After (adding xl)
variants: {
  size: {
    sm: '...',
    md: '...',
    lg: '...',
    xl: '...',  // NEW
  }
}

For New Props:

// Before
interface ButtonProps {
  size?: 'sm' | 'md' | 'lg';
  variant?: 'default' | 'outline';
}

// After (adding isLoading)
interface ButtonProps {
  size?: 'sm' | 'md' | 'lg';
  variant?: 'default' | 'outline';
  isLoading?: boolean;  // NEW
}

For New Sub-components:

// Add new sub-component to compound component
export {
  Accordion,
  AccordionItem,
  AccordionHeader,
  AccordionNewSubComponent,  // NEW
}

Step 3.2: Show Before/After

Present the changes clearly:

## Proposed Changes

### Before:
[Show current code]

### After:
[Show enhanced code]

### New Features:
- Feature 1 description
- Feature 2 description

### API Changes:
- New prop: `propName` (type) - description
- Modified prop: `existingProp` - what changed

CHECKPOINT 2: Get user approval on enhancement design

PHASE 4: Implementation

Step 4.1: Setup Development Environment

yarn link:create
yarn link:apps
yarn dev

Step 4.2: Implement Changes

CRITICAL REMINDERS:

• ✅ Keep existing import paths (use deep imports: @gluestack-ui/core/[component]/creator)
• ✅ Use semantic color tokens only: bg-background, text-foreground, border-border
• ✅ Maintain the existing animation library (don't switch without user approval)
• ✅ Only edit src/components/ui/ - NEVER manually edit apps/ directories
• ✅ Ensure barrel exports remain correct in core package

Make changes in order:

1. Update Core Package (if needed)

   • Modify creator function in packages/gluestack-core/src/[component]/creator/index.tsx
   • Add new functionality
   • Update TypeScript types
   • Verify barrel export in packages/gluestack-core/src/[component]/index.tsx is still correct

2. Update UI Component

   • Modify src/components/ui/[component]/index.tsx
   • Keep deep import path: @gluestack-ui/core/[component]/creator
   • Add new props/sub-components
   • Update forwardRef types
   • Use existing animation library

3. Update Styles

   • Add new variants to src/components/ui/[component]/styles.tsx
   • Update tva() configuration
   • Use semantic color tokens (bg-background, not bg-white)
   • Add responsive/dark mode styles using token system

4. Update TypeScript Types

   • Export new interfaces
   • Update existing interfaces
   • Add generics if needed

5. Update Examples

   • Modify existing examples if needed
   • Add new examples for new features
   • Test all examples still work

6. Update Documentation

   • Add new props to API table
   • Document new features
   • Add examples
   • Update best practices section
   • Add migration guide if breaking changes

Step 4.3: Verify Backward Compatibility

Test that existing usage still works:

• Run all existing examples
• Check no console warnings
• Verify default behavior unchanged

PHASE 5: Testing

Step 5.1: Test Enhanced Component

# Test in kitchen-sink
cd apps/kitchen-sink && yarn dev

# Test in website
cd apps/website && yarn dev

Test:

• ✅ New features work correctly
• ✅ Existing features still work
• ✅ All variants render properly
• ✅ No console errors/warnings
• ✅ TypeScript types correct
• ✅ Examples work
• ✅ Documentation accurate

Step 5.2: Regression Testing

Ensure no regressions:

• Test all existing examples
• Test all variants (size, color, etc.)
• Test edge cases
• Test accessibility features
• Test animations

Step 5.3: Present Results

Show the user:

## Testing Results

### New Features Tested:
- ✅ Feature 1 works on iOS, Android, Web
- ✅ Feature 2 works with all variants
- ✅ New examples render correctly

### Regression Testing:
- ✅ All existing examples work
- ✅ No console errors
- ✅ Backward compatible
- ✅ TypeScript compiles

### Documentation:
- ✅ Updated API reference
- ✅ Added examples
- ✅ Migration guide (if needed)

CHECKPOINT 3: Get user approval on implementation

PHASE 6: Finalization

Step 6.1: Final Checklist

## Enhancement Completion Checklist

### Code Changes
- [ ] Core package updated (if needed)
- [ ] UI component updated
- [ ] Styles updated
- [ ] TypeScript types updated
- [ ] All exports updated

### Documentation
- [ ] API reference updated
- [ ] New examples added
- [ ] Migration guide (if breaking changes)
- [ ] Changelog entry (if applicable)

### Testing
- [ ] New features tested
- [ ] Regression tests passed
- [ ] Accessibility verified
- [ ] Cross-platform tested

### Backward Compatibility
- [ ] Existing examples work
- [ ] No breaking changes (or documented)
- [ ] Default behavior preserved

Step 6.2: Cleanup

yarn unlink:apps

Step 6.3: Summary

## ✅ Component Enhancement Complete!

### What Changed:
[Summary of changes]

### Files Modified:
- src/components/ui/[component]/index.tsx
- src/components/ui/[component]/styles.tsx
- [other files]

### Testing:
- ✅ Tested on iOS, Android, Web
- ✅ All existing features work
- ✅ New features work correctly

### Next Steps:
1. Review all changes
2. Run final tests
3. Commit with message: `feat([component]): [description]` or `fix([component]): [description]`
4. Create PR

Ready to commit?

CHECKPOINT 4: Final confirmation before commit

Best Practices

1. Always maintain backward compatibility unless it's a major version bump
2. Test all existing examples to ensure no regressions
3. Document breaking changes clearly with migration guides
4. Add deprecation warnings before removing features
5. Update all examples affected by changes
6. Keep changes focused - one enhancement at a time
7. Follow existing patterns in the component
8. Test accessibility after changes
9. Update TypeScript types to match implementation
10. Verify cross-platform behavior

Common Enhancements

Adding a New Variant

• Update styles.tsx with new variant
• Update TypeScript types
• Add example
• Document in API reference

Adding a New Prop

• Add to props interface
• Implement functionality
• Update documentation
• Add example

Adding Sub-component

• Implement in core (if needed)
• Add to UI component
• Create styles
• Export from index
• Document
• Add example

Bug Fix

• Identify root cause
• Implement fix
• Add regression test
• Update documentation if behavior changes

Error Recovery

If issues arise:

• Revert changes and start over
• Check existing component patterns
• Read CONTRIBUTING.md for guidance
• Ask user for clarification
• Test incrementally

---

Ready to enhance a component! 🔧