> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server.

# Migrate from Radix UI to Material UI with Seamless Design System in DOCAI

## Epic Overview

**Epic ID**: WEB-EPIC-001

**Title**: Migrate Web Application from Radix UI to Material UI

**Priority**: High

**Estimated Duration**: 8-12 sprints

**Status**: Planning

## Executive Summary

This epic encompasses the complete migration of the Web Documents AI application from Radix UI component library to Material UI (MUI), integrated with the Seamless design system (MUI theme engine). The migration will be executed incrementally by functional view to minimize disruption, maintain continuous delivery, and allow for iterative testing and validation.

## Business Objectives

* **Standardization**: Align with enterprise-wide Seamless design system for consistent UX

* **Enhanced Capabilities**: Leverage MUI's comprehensive component ecosystem and accessibility features

* **Maintainability**: Reduce dependency on multiple UI libraries and improve long-term maintenance

* **Design System Integration**: Enable theming consistency across all enterprise applications

## Technical Scope

### Current State

* **UI Framework**: Radix UI primitives with custom Tailwind styling

* **Components**: 40+ custom UI components built on Radix primitives

* **Radix Dependencies**:

\- @radix-ui/react-alert-dialog

\- @radix-ui/react-avatar

\- @radix-ui/react-checkbox

\- @radix-ui/react-dialog

\- @radix-ui/react-dropdown-menu

\- @radix-ui/react-icons

\- @radix-ui/react-label

\- @radix-ui/react-popover

\- @radix-ui/react-progress

\- @radix-ui/react-select

\- @radix-ui/react-separator

\- @radix-ui/react-slot

\- @radix-ui/react-switch

\- @radix-ui/react-tabs

\- @radix-ui/react-toast

\- @radix-ui/react-tooltip

\- @radix-ui/react-visually-hidden

### Target State

* **UI Framework**: Material UI v6.4.0+ with Seamless design system

* **Components**: MUI components customized via Seamless theme engine

* **Styling**: MUI sx prop and styled components, maintaining Tailwind for utility classes

* **Icons**: Migration from @radix-ui/react-icons to @mui/icons-material

## Migration Strategy

### Phased Approach

The migration will follow a **vertical slice** strategy, completing one functional view at a time rather than migrating components horizontally. This ensures:

* Each view is fully functional after migration

* Incremental testing and validation

* Reduced risk of breaking changes

* Ability to rollback individual views if needed

### Parallel Component Support

During migration, both Radix UI and MUI components will coexist:

* Prefix migrated components with `Mui` (e.g., `MuiButton`)

* Keep original Radix components until all views are migrated

* Clean up Radix dependencies in final phase

---

## Feature Breakdown

### Feature 1: Foundation & Infrastructure Setup

**Goal**: Establish MUI and Seamless design system infrastructure

**Requirements**:

* Install and configure Material UI v6.4.0+

* Install and configure Seamless design system theme engine

* Create MUI theme provider wrapper

* Configure Seamless theme customizations

* Set up MUI typography, spacing, and breakpoint system

* Create component migration documentation

* Establish testing strategy for migrated components

**Acceptance Criteria**:

* MUI and Seamless packages installed and configured

* Theme provider wraps application root

* Design tokens from Seamless are applied

* Documentation template created

* Migration testing guidelines established

---

### Feature 2: Core Component Library Migration

**Goal**: Migrate foundational UI components used across all views

**Requirements**:

* Migrate base components to MUI equivalents:

\- Button → MUI Button

\- Input → MUI TextField

\- Label → MUI FormLabel

\- Checkbox → MUI Checkbox

\- Badge → MUI Badge

\- Avatar → MUI Avatar

\- Card → MUI Card

\- Alert → MUI Alert

* Apply Seamless theme styling to components

* Maintain API compatibility where possible

* Create Storybook stories for migrated components

* Update unit tests for migrated components

**Acceptance Criteria**:

* All core components migrated with full feature parity

* Storybook stories pass visual regression tests

* Unit tests pass with >80% coverage

* Components follow MUI and Seamless design patterns

* Accessibility standards maintained (WCAG 2.1 AA)

---

### Feature 3: Navigation & Layout Migration

**Goal**: Migrate application shell, navigation, and layout components

**Components Affected**:

* Navigation.tsx

* BreadcrumbTrail.tsx

* App layout structure

**Requirements**:

* Migrate Navigation to MUI AppBar, Drawer, and List components

* Migrate Breadcrumbs to MUI Breadcrumbs

* Update layout containers to use MUI Grid/Box

* Apply Seamless navigation theme

* Migrate dropdown menus to MUI Menu

* Update tooltips to MUI Tooltip

* Ensure responsive behavior maintained

**Acceptance Criteria**:

* Navigation fully functional with MUI components

* Breadcrumbs display correctly across all routes

* Responsive behavior matches current implementation

* Theme consistency with Seamless design system

* No visual regressions in layout

---

### Feature 4: Authentication & Login View Migration

**Goal**: Migrate login and authentication-related UI

**Components Affected**:

* routes/Login.tsx

* components/AuthProvider.tsx

* Related form components

**Requirements**:

* Migrate login form to MUI TextField, Button

* Update form validation with MUI FormControl

* Migrate any dialogs to MUI Dialog

* Apply Seamless form theme

* Update error states and messaging

* Maintain MSAL authentication integration

**Acceptance Criteria**:

* Login flow fully functional

* Form validation working correctly

* Error states display properly

* MSAL integration unaffected

* Visual consistency with Seamless design

---

### Feature 5: Dashboard View Migration

**Goal**: Migrate main dashboard and data visualization components

**Components Affected**:

* routes/Dashboard.tsx

* Related chart and stats components

**Requirements**:

* Migrate dashboard cards to MUI Card

* Update data tables to use MUI DataGrid (or maintain @tanstack/react-table with MUI Table)

* Migrate progress indicators to MUI LinearProgress/CircularProgress

* Update tabs to MUI Tabs

* Apply Seamless data visualization theme

* Ensure recharts integration remains functional

**Acceptance Criteria**:

* Dashboard fully functional with MUI components

* Data visualization maintains performance

* All interactive elements work correctly

* Responsive design preserved

* Theme applied consistently

---

### Feature 6: Invoice Management View Migration (Phase 1)

**Goal**: Migrate invoice list and filtering UI

**Components Affected**:

* routes/invoice/Invoices.tsx

* components/ui/data-table.tsx

* components/ui/data-table-faceted-filter.tsx

* Related filter and search components

**Requirements**:

* Migrate invoice data table to MUI Table with @tanstack/react-table

* Migrate filters to MUI Select, Autocomplete

* Update search to MUI TextField with search variant

* Migrate pagination to MUI Pagination

* Update action buttons (Export, Restart) to MUI IconButton/Button

* Apply Seamless table theme

* Migrate icons from Radix to MUI icons

**Acceptance Criteria**:

* Invoice table displays correctly with all data

* Filtering and search functionality preserved

* Pagination works correctly

* Export and bulk actions functional

* Performance maintained (virtualization if needed)

---

### Feature 7: Invoice Management View Migration (Phase 2)

**Goal**: Migrate individual invoice processing views

**Components Affected**:

* routes/invoice/Invoice.tsx

* routes/invoice/Intake.tsx

* routes/invoice/Matching.tsx

* routes/invoice/Coding.tsx

* routes/invoice/Approval.tsx

* routes/invoice/Filing.tsx

* routes/invoice/Closed.tsx

* components/InvoiceViewer.tsx

**Requirements**:

* Migrate invoice detail view layout to MUI Grid/Stack

* Update stage-specific forms to MUI FormControl

* Migrate dialogs and modals to MUI Dialog

* Update steppers to MUI Stepper

* Migrate status badges to MUI Chip

* Update dropdown menus to MUI Menu

* Apply Seamless form and data display themes

* Maintain invoice PDF viewer functionality

**Acceptance Criteria**:

* All invoice stages functional

* Form submissions work correctly

* Stage transitions maintained

* File upload/viewer preserved

* Validation and error handling functional

---

### Feature 8: Administration & Settings Views Migration

**Goal**: Migrate all administrative and configuration views

**Components Affected**:

* routes/Administration.tsx

* routes/Configuration.tsx

* routes/settings/\* (all management views)

**Requirements**:

* Migrate all management forms to MUI FormControl

* Update data tables to MUI Table

* Migrate switches and toggles to MUI Switch

* Update dialog-based workflows to MUI Dialog

* Migrate date pickers to MUI DatePicker

* Apply Seamless form theme

* Update user management tables and forms

* Migrate workflow editor components

**Acceptance Criteria**:

* All admin views fully functional

* User/client/department management works

* Configuration changes persist correctly

* Workflow editor maintains functionality

* Forms validate correctly

---

### Feature 9: Monitoring & Reporting Views Migration

**Goal**: Migrate monitoring, logs, and reporting interfaces

**Components Affected**:

* routes/Monitoring.tsx

* routes/AppLogs.tsx

* routes/monitoring/\* (subdirectory)

* routes/Starred.tsx

* routes/InvoiceHistory.tsx

**Requirements**:

* Migrate log viewers to MUI Table with virtualization

* Update monitoring dashboards to MUI Grid/Card

* Migrate date range selectors to MUI DateRangePicker

* Update export dialogs to MUI Dialog

* Apply Seamless data display theme

* Maintain real-time update capabilities

**Acceptance Criteria**:

* Log viewing functional with filtering

* Monitoring dashboards display correctly

* Date range selection works

* Export functionality preserved

* Real-time updates functional

---

### Feature 10: Supporting Views & Utilities Migration

**Goal**: Migrate remaining views and utility components

**Components Affected**:

* routes/About.tsx

* routes/Documentation.tsx

* components/Loading.tsx

* components/Error.tsx

* components/ErrorBoundary.tsx

**Requirements**:

* Migrate loading indicators to MUI CircularProgress/Skeleton

* Update error displays to MUI Alert

* Migrate info pages to MUI Typography/Paper

* Update any remaining dialogs to MUI Dialog

* Apply Seamless utility component theme

**Acceptance Criteria**:

* All views migrated and functional

* Loading states display correctly

* Error handling works properly

* Documentation accessible

---

### Feature 11: Testing & Quality Assurance

**Goal**: Comprehensive testing of all migrated components and views

**Requirements**:

* Execute full regression testing suite

* Perform accessibility audit (WCAG 2.1 AA)

* Conduct visual regression testing

* Performance benchmarking

* Cross-browser testing (Chrome, Firefox, Safari, Edge)

* Mobile responsive testing

* Theme switching validation

* User acceptance testing

**Acceptance Criteria**:

* All automated tests pass (>90% coverage)

* No accessibility violations

* Visual regressions identified and resolved

* Performance metrics within acceptable range

* UAT sign-off completed

---

### Feature 12: Cleanup & Optimization

**Goal**: Remove Radix UI dependencies and optimize final implementation

**Requirements**:

* Remove all Radix UI packages from package.json

* Delete unused Radix component files

* Update all imports to use MUI components

* Optimize bundle size

* Remove duplicate styling

* Update documentation

* Create migration guide for future reference

* Performance optimization post-migration

**Acceptance Criteria**:

* Zero Radix UI dependencies remain

* Bundle size reduced or maintained

* All dead code removed

* Documentation complete

* Performance benchmarks met or exceeded

---

## Story List

### Epic WEB-EPIC-001: Stories Breakdown

#### Theme 1: Foundation (Sprint 1-2)

* **WEB-001**: Install and configure Material UI v6 and dependencies

* **WEB-002**: Install and configure Seamless design system theme engine

* **WEB-003**: Create MUI ThemeProvider with Seamless configuration

* **WEB-004**: Configure design tokens (colors, typography, spacing, breakpoints)

* **WEB-005**: Set up dual component system (Radix + MUI coexistence)

* **WEB-006**: Create component migration documentation template

* **WEB-007**: Establish testing strategy and update test utilities

* **WEB-008**: Configure Storybook for MUI components

#### Theme 2: Core Components (Sprint 2-3)

* **WEB-009**: Migrate Button component to MUI Button

* **WEB-010**: Migrate Input component to MUI TextField

* **WEB-011**: Migrate Label component to MUI FormLabel

* **WEB-012**: Migrate Checkbox component to MUI Checkbox

* **WEB-013**: Migrate Badge component to MUI Badge

* **WEB-014**: Migrate Avatar component to MUI Avatar

* **WEB-015**: Migrate Card component to MUI Card

* **WEB-016**: Migrate Alert component to MUI Alert

* **WEB-017**: Migrate Form component to MUI FormControl

* **WEB-018**: Create Storybook stories for all core components

* **WEB-019**: Update unit tests for all core components

#### Theme 3: Navigation & Layout (Sprint 3-4)

* **WEB-020**: Migrate Navigation component to MUI AppBar and Drawer

* **WEB-021**: Migrate BreadcrumbTrail to MUI Breadcrumbs

* **WEB-022**: Migrate DropdownMenu to MUI Menu

* **WEB-023**: Migrate Tooltip to MUI Tooltip

* **WEB-024**: Update App layout structure with MUI Grid/Box

* **WEB-025**: Test responsive navigation behavior

* **WEB-026**: Update navigation-related unit tests

#### Theme 4: Authentication (Sprint 4)

* **WEB-027**: Migrate Login form to MUI components

* **WEB-028**: Update AuthProvider with MUI styling

* **WEB-029**: Migrate authentication dialogs to MUI Dialog

* **WEB-030**: Test authentication flow end-to-end

* **WEB-031**: Update authentication-related tests

#### Theme 5: Dashboard (Sprint 5-6)

* **WEB-032**: Migrate Dashboard cards to MUI Card

* **WEB-033**: Migrate Dashboard tabs to MUI Tabs

* **WEB-034**: Migrate progress indicators to MUI Progress components

* **WEB-035**: Update data tables with MUI Table styling

* **WEB-036**: Migrate dashboard filters to MUI components

* **WEB-037**: Test dashboard data visualization

* **WEB-038**: Test dashboard responsiveness

* **WEB-039**: Update dashboard unit and integration tests

#### Theme 6: Invoice List View (Sprint 6-7)

* **WEB-040**: Migrate invoice data table to MUI Table

* **WEB-041**: Migrate data-table-faceted-filter to MUI Autocomplete/Select

* **WEB-042**: Migrate invoice search to MUI TextField

* **WEB-043**: Migrate pagination to MUI Pagination

* **WEB-044**: Migrate bulk action buttons to MUI IconButton/Button

* **WEB-045**: Migrate Radix icons to MUI icons in invoice list

* **WEB-046**: Test invoice filtering and search

* **WEB-047**: Test pagination and data loading

* **WEB-048**: Update invoice list tests

#### Theme 7: Invoice Processing - Intake & Matching (Sprint 7-8)

* **WEB-049**: Migrate Invoice detail layout to MUI Grid/Stack

* **WEB-050**: Migrate Intake view to MUI components

* **WEB-051**: Migrate Matching view to MUI components

* **WEB-052**: Migrate invoice status badges to MUI Chip

* **WEB-053**: Migrate invoice dialogs to MUI Dialog

* **WEB-054**: Test intake workflow end-to-end

* **WEB-055**: Test matching workflow end-to-end

* **WEB-056**: Update intake and matching tests

#### Theme 8: Invoice Processing - Coding & Approval (Sprint 8-9)

* **WEB-057**: Migrate Coding view to MUI components

* **WEB-058**: Migrate Approval view to MUI components

* **WEB-059**: Migrate ApprovalStatus component to MUI

* **WEB-060**: Migrate invoice stepper to MUI Stepper

* **WEB-061**: Migrate form controls in coding/approval to MUI

* **WEB-062**: Test coding workflow end-to-end

* **WEB-063**: Test approval workflow end-to-end

* **WEB-064**: Update coding and approval tests

#### Theme 9: Invoice Processing - Filing & Closed (Sprint 9)

* **WEB-065**: Migrate Filing view to MUI components

* **WEB-066**: Migrate Closed view to MUI components

* **WEB-067**: Migrate Processing view to MUI components

* **WEB-068**: Migrate Export/ExportBulk views to MUI components

* **WEB-069**: Test filing and export workflows

* **WEB-070**: Update filing and export tests

#### Theme 10: Administration Views (Sprint 10)

* **WEB-071**: Migrate Administration dashboard to MUI components

* **WEB-072**: Migrate Configuration view to MUI components

* **WEB-073**: Migrate UserManagement to MUI components

* **WEB-074**: Migrate ClientManagement to MUI components

* **WEB-075**: Migrate DepartmentManagement to MUI components

* **WEB-076**: Migrate ClientDepartmentManagement to MUI components

* **WEB-077**: Test admin CRUD operations

* **WEB-078**: Update administration tests

#### Theme 11: Settings & Management Tools (Sprint 10-11)

* **WEB-079**: Migrate WorkflowEditor to MUI components

* **WEB-080**: Migrate KnowledgeBaseManager to MUI components

* **WEB-081**: Migrate InboxMonitoringManager to MUI components

* **WEB-082**: Migrate WebhookManager to MUI components

* **WEB-083**: Migrate ErpConnections to MUI components

* **WEB-084**: Migrate ClientInvoiceStats to MUI components

* **WEB-085**: Test all management workflows

* **WEB-086**: Update management tool tests

#### Theme 12: Monitoring & Reporting (Sprint 11)

* **WEB-087**: Migrate Monitoring dashboard to MUI components

* **WEB-088**: Migrate AppLogs view to MUI components with virtualization

* **WEB-089**: Migrate Starred view to MUI components

* **WEB-090**: Migrate InvoiceHistory to MUI components

* **WEB-091**: Migrate date range pickers to MUI DateRangePicker

* **WEB-092**: Test log filtering and export

* **WEB-093**: Update monitoring tests

#### Theme 13: Supporting Views (Sprint 11-12)

* **WEB-094**: Migrate About view to MUI Typography/Paper

* **WEB-095**: Migrate Documentation view to MUI components

* **WEB-096**: Migrate Loading component to MUI CircularProgress/Skeleton

* **WEB-097**: Migrate Error component to MUI Alert

* **WEB-098**: Update ErrorBoundary with MUI styling

* **WEB-099**: Migrate remaining utility components

* **WEB-100**: Update utility component tests

#### Theme 14: Advanced Components (Sprint 12)

* **WEB-101**: Migrate Select component to MUI Select/Autocomplete

* **WEB-102**: Migrate MultiSelect to MUI Autocomplete

* **WEB-103**: Migrate DatePicker to MUI DatePicker

* **WEB-104**: Migrate Calendar to MUI DateCalendar

* **WEB-105**: Migrate Combobox to MUI Autocomplete

* **WEB-106**: Migrate Command palette to MUI Dialog + Autocomplete

* **WEB-107**: Migrate Switch to MUI Switch

* **WEB-108**: Migrate Tabs to MUI Tabs

* **WEB-109**: Migrate Separator to MUI Divider

* **WEB-110**: Migrate Progress to MUI LinearProgress

* **WEB-111**: Migrate Popover to MUI Popover

* **WEB-112**: Migrate Sheet to MUI Drawer

* **WEB-113**: Migrate Toast/Toaster to MUI Snackbar

* **WEB-114**: Update advanced component tests

#### Theme 15: Testing & QA (Sprint 12-13)

* **WEB-115**: Execute full regression test suite

* **WEB-116**: Perform accessibility audit (WCAG 2.1 AA)

* **WEB-117**: Conduct visual regression testing

* **WEB-118**: Performance benchmarking and optimization

* **WEB-119**: Cross-browser compatibility testing

* **WEB-120**: Mobile responsive testing

* **WEB-121**: Theme switching validation

* **WEB-122**: User acceptance testing

* **WEB-123**: Address regression findings

* **WEB-124**: Document test results

#### Theme 16: Cleanup & Documentation (Sprint 13)

* **WEB-125**: Remove Radix UI packages from package.json

* **WEB-126**: Delete unused Radix component files

* **WEB-127**: Update all remaining imports to MUI

* **WEB-128**: Bundle size analysis and optimization

* **WEB-129**: Remove duplicate styling and CSS cleanup

* **WEB-130**: Update component documentation

* **WEB-131**: Create migration guide and lessons learned

* **WEB-132**: Final performance optimization

* **WEB-133**: Update README and developer documentation

* **WEB-134**: Epic closure and retrospective

---

## Dependencies & Risks

### Dependencies

1. **Seamless Design System**: Requires access to and documentation for the Seamless theme engine

2. **MUI Version**: Compatibility with MUI v6.4.0+ and React 18.3.1

3. **Testing Infrastructure**: Storybook and testing library setup

4. **Design Review**: Design team approval of Seamless theme configuration

### Technical Risks

\| Risk | Impact | Mitigation |

\|------|--------|------------|

\| Component API incompatibility | High | Create abstraction layer, maintain adapter components |

\| Performance regression | Medium | Performance benchmarking at each phase, virtualization where needed |

\| Breaking changes in user workflows | High | Thorough UAT, feature flags for gradual rollout |

\| Bundle size increase | Medium | Tree-shaking, lazy loading, code splitting |

\| Theme conflicts with existing styles | Medium | Namespace MUI components, gradual CSS migration |

\| Accessibility regressions | High | Automated a11y testing at each phase |

### Resource Risks

* **Parallel development**: Requires coordination to avoid merge conflicts

* **Knowledge transfer**: Team training on MUI and Seamless required

* **Testing capacity**: QA resources needed for each phase

## Success Criteria

1. **Functional Parity**: All existing features work identically after migration

2. **Visual Consistency**: UI matches Seamless design system specifications

3. **Performance**: No performance degradation (load time, interaction latency)

4. **Accessibility**: WCAG 2.1 AA compliance maintained or improved

5. **Code Quality**: Test coverage maintained at >80%

6. **Bundle Size**: Overall bundle size increase \<15%

7. **Zero Radix Dependencies**: Complete removal of all Radix UI packages

## Timeline Estimate

* **Foundation**: 2 sprints

* **Core Components & Navigation**: 2 sprints

* **Authentication & Dashboard**: 2 sprints

* **Invoice Management**: 3 sprints

* **Administration & Settings**: 2 sprints

* **Monitoring & Supporting Views**: 1 sprint

* **Advanced Components**: 1 sprint

* **Testing & Cleanup**: 2 sprints

**Total Estimated Duration**: 15 sprints (\~7-8 months with 2-week sprints)

## Rollout Strategy

1. **Feature Flags**: Use feature flags to enable MUI views progressively

2. **Canary Release**: Deploy to select users first

3. **Phased Rollout**: Enable views incrementally in production

4. **Monitoring**: Track user feedback and error rates

5. **Rollback Plan**: Ability to revert individual views if critical issues arise

## Communication Plan

* **Weekly Status Updates**: Progress reports to stakeholders

* **Demo Sessions**: Sprint demos of migrated views

* **Documentation**: Keep migration guide updated

* **Training**: Team workshops on MUI and Seamless patterns

* **User Communication**: Release notes for each phase deployment

---

## Appendix

### Component Mapping Reference

\| Radix UI Component | MUI Equivalent | Notes |

\|-------------------|----------------|-------|

\| AlertDialog | Dialog | Use Dialog with Alert severity |

\| Avatar | Avatar | Direct mapping |

\| Checkbox | Checkbox | Direct mapping |

\| Dialog | Dialog | Direct mapping |

\| DropdownMenu | Menu | Direct mapping |

\| Label | FormLabel | Use within FormControl |

\| Popover | Popover | Direct mapping |

\| Progress | LinearProgress / CircularProgress | Choose based on context |

\| Select | Select / Autocomplete | Autocomplete for searchable |

\| Separator | Divider | Direct mapping |

\| Slot | N/A | Use MUI composition patterns |

\| Switch | Switch | Direct mapping |

\| Tabs | Tabs | Direct mapping |

\| Toast | Snackbar | Different API, requires adapter |

\| Tooltip | Tooltip | Direct mapping |

\| VisuallyHidden | visuallyHidden utility | Use MUI utility |

### Icon Migration

* Replace `@radix-ui/react-icons` with `@mui/icons-material`

* Create icon mapping document for consistent replacements

### Useful Resources

* [Material UI Documentation](https://mui.com/material-ui/)

* [Seamless Design System Documentation](#) (add link)

* [Migration Best Practices Guide](#) (to be created)

* [Component Storybook](http://localhost:6006) (local)

---

**Document Version**: 1.0

**Last Updated**: February 16, 2026

**Epic Owner**: \[To be assigned]

**Stakeholders**: Engineering, Design, Product, QA