Sprint: Migrate Chakra UI from v2 to v3

[celticr]

Overview

Chakra UI v3 introduces significant architectural changes that require a dedicated migration effort. This cannot be handled as a simple dependency bump (see closed PR #6).

Why Migrate?

• v2 will eventually stop receiving security updates
• v3 offers improved performance and new components
• Modern React patterns (compound components, slot recipes)

Breaking Changes Summary

Based on Chakra UI Migration Guide:

Dependencies

• Remove @emotion/styled (no longer required)
• Remove framer-motion (no longer required)
• Requires Node 20.x (already using ✅)

Provider Changes

• Update ChakraProvider configuration
• Review theme provider setup

Theme System

• Rewrite client/src/theme.ts for v3 theme structure
• Update color mode configuration
• Migrate custom component styles to new slot recipe system

Component API Changes

• Audit all component imports
• Update deprecated props
• Migrate to new compound component patterns where applicable

Files to Update

Based on codebase analysis:

File	Impact
client/src/theme.ts	Full rewrite
client/src/App.tsx	Provider changes
client/src/components/**/*	Component API updates
client/src/pages/**/*	Component API updates
client/package.json	Dependency changes

Migration Checklist

Phase 1: Preparation

• Read full migration guide: https://www.chakra-ui.com/docs/get-started/migration
• Create feature branch feature/chakra-v3-migration
• Inventory all Chakra components currently used
• Document custom theme tokens and overrides

Phase 2: Core Migration

• Update @chakra-ui/react to v3
• Remove deprecated dependencies
• Update ChakraProvider setup
• Migrate theme configuration

Phase 3: Component Updates

• Update component imports
• Fix deprecated prop usage
• Update any custom Chakra components
• Fix TypeScript errors

Phase 4: Testing

• Visual regression testing
• Test all user flows manually
• Run existing tests
• Fix any styling issues

Phase 5: Cleanup

• Remove any v2 compatibility shims
• Update component documentation if any
• Code review

Resources

• Chakra UI v3 Migration Guide
• Chakra UI v3 Documentation
• Migration Livestream Recordings (referenced in docs)

Estimate

This is a medium-to-large effort affecting the entire frontend. Recommend dedicating a focused sprint or pairing session.

---

Related: Closes Dependabot PR #6