Material-UI Best Practices

Comprehensive guide for building performant, accessible, and maintainable applications with Material-UI (MUI). Contains best practices across multiple categories, including theming, performance optimization, accessibility, and component usage.

When to Apply

Reference these guidelines when:

• Writing new components with Material-UI
• Implementing custom themes or design systems
• Optimizing MUI application performance
• Reviewing code for accessibility compliance
• Refactoring existing MUI code
• Choosing between different MUI styling approaches

Rule Categories

Category	Focus Area	Prefix
1	Theme & Styling	theme-
2	Performance Optimization	perf-
3	Component Usage	component-
4	Accessibility	a11y-
5	Bundle Size	bundle-
6	TypeScript & Type Safety	types-

Quick Reference

1. Theme & Styling

• theme-provider-root - Always wrap app with ThemeProvider at root level
• theme-custom-colors - Extend theme palette for custom colors instead of inline styles
• theme-responsive-values - Use theme breakpoints for responsive design
• theme-spacing-function - Use theme.spacing() for consistent spacing
• theme-typography - Leverage theme typography variants
• theme-dark-mode - Implement dark mode using theme mode toggle
• theme-css-baseline - Include CssBaseline for consistent resets

2. Performance Optimization

• perf-sx-prop-static - Extract static sx prop values to constants
• perf-avoid-inline-styles - Avoid inline style objects in render
• perf-styled-outside-render - Define styled components outside render functions
• perf-use-memo-expensive-computations - Memoize expensive theme/style computations
• perf-emotion-cache - Configure Emotion cache for SSR
• perf-tree-shaking - Import components individually for tree-shaking

3. Component Usage

• component-prop-forwarding - Use component prop for semantic HTML
• component-icon-sizing - Use fontSize prop for Icon sizing
• component-button-variants - Choose appropriate Button variant
• component-grid-vs-stack - Use Stack for simple layouts, Grid for complex
• component-dialog-composition - Compose Dialog with semantic sub-components
• component-form-control - Group related form inputs with FormControl
• component-controlled-inputs - Use controlled components for form inputs

4. Accessibility

• a11y-aria-labels - Provide aria-label for icon-only buttons
• a11y-focus-visible - Preserve focus indicators
• a11y-color-contrast - Ensure sufficient color contrast
• a11y-keyboard-navigation - Support keyboard navigation
• a11y-screen-reader - Use proper semantic HTML and ARIA attributes
• a11y-form-labels - Associate labels with form controls

5. Bundle Size

• bundle-direct-imports - Import directly from @mui/material/Component
• bundle-icons-separate - Load icons from @mui/icons-material separately
• bundle-lab-components - Import lab components individually
• bundle-date-pickers - Use date picker adapters judiciously

6. TypeScript & Type Safety

• types-theme-augmentation - Augment theme types for custom properties
• types-component-props - Use MUI's component prop types
• types-sx-prop - Leverage SxProps type for sx prop
• types-override-types - Extend component variant types properly

Directory Structure

skills/material-ui-best-practices/
├── SKILL.md           # This file - skill overview
├── AGENTS.md          # Complete compiled guide for agents
├── metadata.json      # Skill metadata
├── README.md          # User-facing documentation
└── rules/             # Individual rule files
    ├── theme-provider-root.md
    ├── perf-sx-prop-static.md
    └── ...

How to Use

Read individual rule files for detailed explanations and code examples:

rules/theme-provider-root.md
rules/perf-sx-prop-static.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

References

• Material-UI Documentation
• MUI System
• Emotion Documentation
• MUI Performance Guide