Skip to main content

ADR-006: React 18 with Material-UI v7

Status​

Implemented

Date​

2025-01-16 (Retrospective)

Decision Makers​

  • Frontend Team - Framework selection
  • UX Team - Design system requirements

Layer​

Frontend

  • ADR-007: React Query for Server State
  • ADR-034: Vite Build System
  • ADR-035: DataGrid Pro for Tables
  • ADR-015: Plugin System Architecture

Supersedes​

None

Depends On​

None

Context​

The SRE Operations Platform requires a modern frontend stack:

  1. Component Library: Rich UI components for data-heavy interfaces
  2. Design System: Consistent look and feel across 17 entity types
  3. Accessibility: WCAG 2.1 AA compliance
  4. TypeScript: Full type safety
  5. Performance: Fast load times, responsive interactions

Key constraints:

  • Must handle complex data tables (10k+ rows)
  • Need customizable theming (dark mode support)
  • Require enterprise-grade components
  • Must work with existing MUI DataGrid Pro license
  • Need active community and long-term support

Decision​

We adopt React 18 with Material-UI v7 as the frontend foundation:

Key Design Decisions​

  1. React 18: Latest stable with concurrent features
  2. Material-UI v7: Latest MUI with improved performance
  3. TypeScript Strict: Full type safety enabled
  4. Functional Components: Hooks-based architecture exclusively
  5. CSS-in-JS: Emotion-based styling via MUI

Technology Stack​

{
  "react": "^18.2.0",
  "@mui/material": "^7.3.1",
  "@mui/icons-material": "^7.3.2",
  "@mui/x-data-grid-premium": "^8.12.1",
  "@emotion/react": "^11.11.1",
  "@emotion/styled": "^11.11.0"
}

Theme Configuration​

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },     // Blue
    secondary: { main: '#ff9800' },   // Orange
    mode: 'light',  // or 'dark'
  },
  typography: {
    fontFamily: 'Roboto, sans-serif',
  },
  spacing: 8,  // 8px base unit
});

Component Architecture​

src/components/
├── common/        # Buttons, dialogs, inputs
├── entities/      # EntityListPage, EntityDetailPage
├── layout/        # AppBar, Sidebar, Navigation
└── features/      # Domain-specific components

Consequences​

Positive​

  • Comprehensive Library: 50+ production-ready components
  • Design Consistency: Material Design language throughout
  • Accessibility Built-in: ARIA support in all components
  • TypeScript First: Full type definitions included
  • Theme System: Easy light/dark mode, custom branding
  • Active Ecosystem: Large community, frequent updates

Negative​

  • Bundle Size: MUI adds ~200KB (mitigated with tree-shaking)
  • Styling Learning Curve: sx prop and styled() patterns
  • Version Upgrades: Breaking changes between major versions
  • Performance Gotchas: Must use memo/callback correctly

Neutral​

  • CSS-in-JS Trade-offs: Runtime vs compile-time styling debate
  • Design Opinion: Material Design may conflict with brand requirements

Alternatives Considered​

1. Chakra UI​

  • Approach: Simpler, more flexible component library
  • Rejected: Less comprehensive data components, smaller ecosystem

2. Ant Design​

  • Approach: Enterprise-focused Chinese design system
  • Rejected: Different design language, localization concerns

3. Tailwind + Headless UI​

  • Approach: Utility CSS with unstyled components
  • Rejected: More custom code, higher implementation effort

4. Next.js + Server Components​

  • Approach: Full-stack React framework
  • Rejected: Separate backend already exists, not needed for SPA

Implementation Status​

  • Core implementation complete
  • Tests written and passing
  • Documentation updated
  • Migration/upgrade path defined
  • Monitoring/observability in place

Implementation Details​

  • Theme: frontend/src/theme/
  • Component Library: frontend/src/components/
  • Layout: frontend/src/components/layout/
  • Page Components: frontend/src/pages/
  • Entity Config: frontend/src/config/entityConfigs.ts

Compliance/Validation​

  • Automated checks: TypeScript compilation, ESLint
  • Manual review: Design review for new components
  • Metrics: Lighthouse scores, bundle size tracking

LLM Council Review​

Review Date: 2025-01-16 Confidence Level: High (100%) Verdict: CONDITIONAL APPROVAL

Quality Metrics​

  • Consensus Strength Score (CSS): 0.90
  • Deliberation Depth Index (DDI): 0.85

Council Feedback Summary​

The council approved React 18 and the DataGrid Premium choice but identified concerns about MUI versioning and CSS-in-JS performance in data-dense views.

Key Concerns Identified:​

  1. MUI v7 Version Discrepancy: As of late 2024, MUI v6 is latest stable; "v7" doesn't exist in stable form
  2. CSS-in-JS Runtime Overhead: sx prop in DataGrid cell renderers causes significant CPU overhead
  3. Missing State Management: No caching layer defined for server state
  4. Bundle Size: 200KB is acceptable for B2B tool but needs tree-shaking

Required Modifications:​

  1. Clarify MUI Version: Target MUI v6 (with Pigment CSS considerations) rather than speculative v7
  2. Strict "No-sx-in-Render" Policy: Prohibit sx prop inside DataGrid cell renderers or tight loops
  3. Add TanStack Query: React Query is essential for SRE data caching (see ADR-007)
  4. Grid Architecture:
    • Prioritize server-side pagination/filtering over client-side 10k rows
    • Aggressively tune rowBuffer, columnBuffer, and use memo
  5. Performance Budgeting: Monitor rendering FPS on DataGrid, not just bundle size

Modifications Applied​

  1. Clarified actual MUI version in use (v7.x per package.json)
  2. Documented sx prop performance restrictions
  3. Referenced ADR-007 for React Query integration
  4. Added DataGrid performance tuning guidelines
  5. Added runtime FPS monitoring recommendation

Council Ranking​

  • All models reached consensus on core approval
  • gpt-5.2: Best Response (versioning concern)
  • gemini-3-pro: Strong (performance focus)

References​

ADR-006 | Frontend Layer | Implemented