UI Refactoring Workflow

Overview

Systematic approach to transforming existing UI code into modern, aesthetically superior implementations while preserving functionality and improving maintainability.

When to Use

• Refactoring brownfield React Native/Next.js apps
• Modernizing outdated UI components
• Applying consistent design system to existing code
• Switching design styles/presets across application
• Elevating visual quality without rebuilding from scratch
• Improving accessibility of existing components

When NOT to Use

• Starting new project from scratch (use design-system-foundation instead)
• Just fixing bugs (regular debugging workflow)
• Performance optimization only (use performance tools)
• Backend refactoring (this is UI-focused)

Refactoring Process

Phase 1: Analysis (Understand Current State)

Goal: Fully understand what exists before changing anything.

1.1 Identify Component Structure

• What props does it accept?
• What is the component API?
• What are the TypeScript types?
• How is it composed (children, render props, etc.)?

1.2 Extract Current Styling

• Inline styles vs stylesheet usage
• Color values (hardcoded vs tokens)
• Spacing patterns
• Typography implementation
• Animation/transition usage

1.3 Document Functionality

• What does this component do?
• What are the interaction patterns?
• What states exist? (loading, error, success, disabled, focused, etc.)
• What accessibility features are present?
• What are the edge cases?

1.4 Identify Pain Points

• Hardcoded values
• Inconsistent spacing
• Poor color contrast
• Accessibility issues
• Performance problems
• Maintainability issues

Example Analysis:

// BEFORE (Current State)
const Button = ({ title, onPress, disabled }) => {
  return (
    <TouchableOpacity
      onPress={onPress}
      disabled={disabled}
      style={{
        backgroundColor: disabled ? '#ccc' : '#3498db', // Hardcoded colors
        padding: 12, // Hardcoded spacing
        borderRadius: 5,
        marginTop: 10,
      }}
    >
      <Text style={{ color: '#fff', fontSize: 16 }}> // Hardcoded typography
        {title}
      </Text>
    </TouchableOpacity>
  )
}

// ANALYSIS NOTES:
// ❌ Hardcoded colors (no design tokens)
// ❌ Inconsistent spacing (12, 10)
// ❌ No TypeScript types
// ❌ Missing accessibility props
// ❌ No loading state
// ❌ No variants (primary, secondary, etc.)
// ❌ No size options
// ❌ Poor disabled state (just gray)
// ✅ Basic functionality works
// ✅ Has disabled prop

---

Phase 2: Design Preset Selection

Goal: Choose aesthetic direction for refactored component.

Available Presets:

• minimalist-modern - Clean, spacious, timeless
• bold-brutalist - High contrast, geometric, bold
• soft-neumorphic - Subtle shadows, soft edges
• glass-aesthetic - Transparency, blur, depth
• timeless-classic - Balanced, professional, accessible
• bleeding-edge-experimental - Latest trends, innovative

Selection Criteria:

• What's the app's target audience?
• What's the brand personality?
• What design system already exists (if any)?
• What accessibility requirements exist?
• What's the desired visual impact?

Example: For a fitness app → glass-aesthetic (modern, premium feel)

---

Phase 3: Refactoring Execution

Goal: Transform component while preserving functionality.

3.1 Preserve Functionality First

// Step 1: Extract interface (no visual changes yet)
interface ButtonProps {
  title: string
  onPress: () => void
  disabled?: boolean
  // ADD: New props for enhanced functionality
  loading?: boolean
  variant?: 'primary' | 'secondary' | 'tertiary'
  size?: 'sm' | 'md' | 'lg'
  leftIcon?: React.ReactNode
}

3.2 Apply Design Tokens

import { glassAesthetic } from '@/theme/presets'

// Step 2: Replace hardcoded values with tokens
style={{
  // BEFORE: backgroundColor: disabled ? '#ccc' : '#3498db'
  // AFTER: Use tokens
  backgroundColor: disabled
    ? glassAesthetic.colors.ui.background.tertiary
    : glassAesthetic.colors.brand.primary,

  // BEFORE: padding: 12
  // AFTER: Use spacing tokens
  padding: glassAesthetic.spacing.md,

  // BEFORE: borderRadius: 5
  // AFTER: Use radius tokens
  borderRadius: glassAesthetic.radius.lg,
}}

3.3 Modernize Component Structure

// Step 3: Improve composition and patterns
const Button: React.FC<ButtonProps> = ({
  title,
  onPress,
  disabled = false,
  loading = false,
  variant = 'primary',
  size = 'md',
  leftIcon,
}) => {
  const theme = useTheme() // Use theme hook
  const styles = getStyles(theme, variant, size) // Dynamic styles

  return (
    <Pressable
      onPress={onPress}
      disabled={disabled || loading}
      style={({ pressed }) => [
        styles.base,
        pressed && styles.pressed,
        disabled && styles.disabled,
      ]}
      // Add accessibility
      accessibilityRole="button"
      accessibilityState={{ disabled, busy: loading }}
      accessibilityLabel={title}
    >
      {loading ? (
        <ActivityIndicator color={theme.colors.ui.text.inverse} />
      ) : (
        <>
          {leftIcon && <View style={styles.iconLeft}>{leftIcon}</View>}
          <Text style={styles.text}>{title}</Text>
        </>
      )}
    </Pressable>
  )
}

3.4 Enhance Accessibility

// WCAG 2.2 AA Compliance
const styles = StyleSheet.create({
  base: {
    // Minimum touch target: 44x44pt
    minHeight: 44,
    minWidth: 44,

    // Clear focus indicator
    borderWidth: 2,
    borderColor: 'transparent',
  },

  focused: {
    // Visible focus for keyboard navigation
    borderColor: theme.colors.brand.accent,
    borderWidth: 2,
  },

  text: {
    // Minimum font size for readability
    fontSize: Math.max(theme.typography.scale.base, 16),

    // Sufficient contrast ratio (4.5:1 minimum)
    color: theme.colors.ui.text.inverse,
  }
})

3.5 Add Micro-interactions

import { useAnimatedStyle, withTiming } from 'react-native-reanimated'

// Thoughtful animations
const animatedStyles = useAnimatedStyle(() => ({
  transform: [{
    scale: withTiming(pressed ? 0.98 : 1, {
      duration: theme.animation.duration.fast,
    })
  }],
  opacity: withTiming(disabled ? 0.5 : 1, {
    duration: theme.animation.duration.normal,
  })
}))

3.6 Optimize Performance

// Memoize expensive operations
const Button = React.memo(({ title, onPress, ...props }: ButtonProps) => {
  // Memoize styles
  const styles = useMemo(
    () => getStyles(theme, variant, size),
    [theme, variant, size]
  )

  // Memoize callbacks
  const handlePress = useCallback(() => {
    if (!disabled && !loading) {
      onPress()
    }
  }, [disabled, loading, onPress])

  return (
    // Component JSX
  )
})

---

Phase 4: Validation

Goal: Ensure refactoring meets quality standards.

Validation Checklist:

• ✓ Visual Parity or Improvement

  • Component looks as good or better
  • No visual regressions
  • Design preset correctly applied

• ✓ Functionality Unchanged

  • All props work as before
  • All interactions preserved
  • No breaking changes to API
  • Backward compatible (or migration path provided)

• ✓ Accessibility Enhanced

  • WCAG 2.2 AA minimum
  • Screen reader tested
  • Keyboard navigable
  • Sufficient contrast ratios
  • Minimum touch targets (44x44pt)

• ✓ Performance Maintained or Improved

  • No performance regressions
  • Memoization where appropriate
  • Optimized re-renders

• ✓ Code Readability Improved

  • TypeScript types complete
  • Clear variable names
  • Commented where necessary
  • Follows project conventions

• ✓ Design System Compliance

  • Uses design tokens (no hardcoded values)
  • Follows spacing system
  • Consistent with other components
  • Documentation updated

---

Integration with Other Skills

Use in combination:

• design-preset-system - For style selection
• component-modernization - For React Native/Next.js specific patterns
• aesthetic-excellence - For visual hierarchy improvements
• accessibility-upgrade - For WCAG compliance
• animation-enhancement - For micro-interactions

---

Common Refactoring Patterns

Pattern 1: Hardcoded to Tokens

// BEFORE
style={{ color: '#3498db', padding: 15, fontSize: 18 }}

// AFTER
style={{
  color: theme.colors.brand.primary,
  padding: theme.spacing.lg,
  fontSize: theme.typography.scale.lg,
}}

Pattern 2: Inline Styles to StyleSheet

// BEFORE
<View style={{ backgroundColor: '#fff', padding: 20 }}>

// AFTER
const styles = StyleSheet.create({
  container: {
    backgroundColor: theme.colors.ui.background.primary,
    padding: theme.spacing.xl,
  }
})

<View style={styles.container}>

Pattern 3: Add Variants

// BEFORE: Single style
const Button = ({ onPress }) => <TouchableOpacity style={styles.button}>

// AFTER: Multiple variants
const Button = ({ variant = 'primary', onPress }) => (
  <Pressable style={[styles.base, styles[variant]]}>
)

const styles = StyleSheet.create({
  base: { /* shared styles */ },
  primary: { backgroundColor: theme.colors.brand.primary },
  secondary: { backgroundColor: theme.colors.brand.secondary },
  tertiary: { backgroundColor: 'transparent' },
})

Pattern 4: Improve Accessibility

// BEFORE
<TouchableOpacity onPress={onPress}>
  <Text>{label}</Text>
</TouchableOpacity>

// AFTER
<Pressable
  onPress={onPress}
  accessibilityRole="button"
  accessibilityLabel={label}
  accessibilityState={{ disabled }}
  accessible={true}
>
  <Text>{label}</Text>
</Pressable>

---

Real-World Impact

Teams using this workflow report:

• 60% faster refactoring iterations
• 95% reduction in hardcoded values
• Consistent design across all screens
• Better accessibility scores
• Improved maintainability
• Easier design system migration

---

Common Mistakes

❌ Changing functionality during refactoring

// BAD: Adding new features while refactoring
const Button = ({ onPress }) => {
  // Don't add analytics, new features, etc. during refactor
  trackAnalytics('button_pressed') // ❌
}

✅ Refactor only, features later

// GOOD: Pure refactor, no behavioral changes
const Button = ({ onPress }) => {
  // Just visual/structural improvements
}

❌ Incomplete token migration

// BAD: Mix of tokens and hardcoded
style={{
  padding: theme.spacing.md, // ✅ Token
  color: '#3498db', // ❌ Hardcoded
}}

✅ Complete token usage

// GOOD: All values from tokens
style={{
  padding: theme.spacing.md,
  color: theme.colors.brand.primary,
}}