material-ui

Material-UI (MUI) Best Practices

This guide outlines the definitive best practices for developing React applications with Material-UI (MUI). Adhere to these standards to ensure consistent, performant, and maintainable code across our projects.

1. Code Organization & Structure

Organize code by feature, not by type. Components should be small, focused, and self-contained.

1.1 Directory Structure

Adopt a feature-oriented layout.

src/
  components/           # Reusable, generic UI components (e.g., Button, Modal)
    Button/
      Button.jsx
      Button.styled.js  # Styled components for Button
      Button.test.jsx
      index.js          # Exports Button
  features/             # Feature-specific components and logic (e.g., UserProfile, ProductList)
    Auth/
      LoginPage.jsx
      AuthForm.jsx
      AuthService.js
      AuthContext.js
  theme/                # Centralized MUI theme configuration
    index.js
    palette.js
    typography.js
  utils/                # General utility functions
    api.js
    helpers.js
  App.jsx               # Main application component
  index.jsx             # Entry point

1.2 Naming Conventions

• Components: PascalCase (e.g., MyComponent.jsx).
• Styled Components: PascalCase for the component, .styled.js suffix (e.g., MyComponent.styled.js).
• CSS Modules: kebab-case or camelCase (e.g., my-component.module.css).
• Tests: .test.jsx suffix (e.g., MyComponent.test.jsx).
• Indexes: index.js should export the main entity of its parent folder.

2. Theming

Centralize all design tokens and theme customizations. Always use createTheme and ThemeProvider.

2.1 Centralized Theme Configuration

Define your theme in src/theme/index.js and wrap your application with ThemeProvider. This is where Material Design 3 tokens should be configured.

// src/theme/index.js
import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    mode: 'light', // or 'dark'
    primary: {
      main: '#006B5F', // Material Design 3 primary color example
      light: '#4DA89F',
      dark: '#003730',
    },
    secondary: {
      main: '#6A5F00', // Material Design 3 secondary color example
    },
    // ... other palette colors
  },
  typography: {
    fontFamily: 'Roboto, sans-serif',
    h1: { fontSize: '2.5rem', fontWeight: 700 },
    body1: { fontSize: '1rem', lineHeight: 1.5 },
  },
  components: {
    MuiButton: {
      defaultProps: {
        disableElevation: true, // Consistent button style
      },
      styleOverrides: {
        root: {
          borderRadius: 8,
          textTransform: 'none', // Prefer sentence case for buttons
        },
      },
    },
    MuiCard: {
      styleOverrides: {
        root: {
          borderRadius: 12,
          boxShadow: '0 2px 8px rgba(0,0,0,0.08)',
        },
      },
    },
  },
});

export default theme;

// src/App.jsx
import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline'; // Resets browser styles
import theme from './theme';
import MyPage from './features/MyPage';

function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline /> {/* Always include CssBaseline */}
      <MyPage />
    </ThemeProvider>
  );
}
export default App;