Mui

Padrões MUI v7

Propósito

Padrões do Material-UI v7 (lançado em março de 2025) para uso de componentes, estilização com sx prop, integração de tema e design responsivo.

Nota: Mudanças de quebra do MUI v7 em relação ao v6:

• Deep imports não funcionam mais - use o campo exports do pacote
• onBackdropClick removido do Modal - use onClose em seu lugar
• Todos os componentes agora usam o padrão padronizado slots e slotProps
• Suporte a CSS layers via configuração enableCssLayer (funciona com Tailwind v4)

Quando Usar Esta Habilidade

• Estilização de componentes com MUI sx prop
• Uso de componentes MUI (Box, Grid, Paper, Typography, etc.)
• Personalização e uso de tema
• Design responsivo com breakpoints MUI
• Utilitários e hooks específicos do MUI

Início Rápido

Componente MUI Básico

import { Box, Typography, Button, Paper } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

const styles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    display: 'flex',
    flexDirection: 'column',
    gap: 2,
  },
  header: {
    mb: 3,
    fontSize: '1.5rem',
    fontWeight: 600,
  },
};

function MyComponent() {
  return (
    <Paper sx={styles.container}>
      <Typography sx={styles.header}>
        Título
      </Typography>
      <Button variant="contained">
        Ação
      </Button>
    </Paper>
  );
}

Padrões de Estilização

Estilos Inline (< 100 linhas)

Para componentes com estilização simples, defina os estilos no topo:

import type { SxProps, Theme } from '@mui/material';

const componentStyles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    display: 'flex',
    flexDirection: 'column',
  },
  header: {
    mb: 2,
    color: 'primary.main',
  },
  button: {
    mt: 'auto',
    alignSelf: 'flex-end',
  },
};

function Component() {
  return (
    <Box sx={componentStyles.container}>
      <Typography sx={componentStyles.header}>Cabeçalho</Typography>
      <Button sx={componentStyles.button}>Ação</Button>
    </Box>
  );
}

Arquivo de Estilos Separado (>= 100 linhas)

Para componentes complexos, crie um arquivo de estilos separado:

// UserProfile.styles.ts
import type { SxProps, Theme } from '@mui/material';

export const userProfileStyles: Record<string, SxProps<Theme>> = {
  container: {
    p: 3,
    maxWidth: 800,
    mx: 'auto',
  },
  header: {
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'center',
    mb: 3,
  },
  // ... muitos mais estilos
};

// UserProfile.tsx
import { userProfileStyles as styles } from './UserProfile.styles';

function UserProfile() {
  return <Box sx={styles.container}>...</Box>;
}

Componentes Comuns

Componentes de Layout

// Box - Contêiner genérico
<Box sx={{ p: 2, bgcolor: 'background.paper' }}>
  Conteúdo
</Box>

// Paper - Superfície elevada
<Paper elevation={2} sx={{ p: 3 }}>
  Conteúdo
</Paper>

// Container - Conteúdo centralizado com largura máxima
<Container maxWidth="lg">
  Conteúdo
</Container>

// Stack - Contêiner flex com espaçamento
<Stack spacing={2} direction="row">
  <Item />
  <Item />
</Stack>

Sistema de Grid

import { Grid } from '@mui/material';

// Grid de 12 colunas
<Grid container spacing={2}>
  <Grid item xs={12} md={6}>
    Metade esquerda
  </Grid>
  <Grid item xs={12} md={6}>
    Metade direita
  </Grid>
</Grid>

// Grid responsivo
<Grid container spacing={3}>
  <Grid item xs={12} sm={6} md={4} lg={3}>
    Cartão
  </Grid>
  {/* Repita para mais cartões */}
</Grid>

Tipografia

<Typography variant="h1">Título 1</Typography>
<Typography variant="h2">Título 2</Typography>
<Typography variant="body1">Texto do corpo</Typography>
<Typography variant="caption">Texto pequeno</Typography>

// Com estilização customizada
<Typography
  variant="h4"
  sx={{
    color: 'primary.main',
    fontWeight: 600,
    mb: 2,
  }}
>
  Título Customizado
</Typography>

Botões

// Variantes
<Button variant="contained">Contido</Button>
<Button variant="outlined">Delineado</Button>
<Button variant="text">Texto</Button>

// Cores
<Button variant="contained" color="primary">Primária</Button>
<Button variant="contained" color="secondary">Secundária</Button>
<Button variant="contained" color="error">Erro</Button>

// Com ícones
import { Add as AddIcon } from '@mui/icons-material';

<Button startIcon={<AddIcon />}>Adicionar Item</Button>

Integração de Tema

Usando Valores de Tema

import { useTheme } from '@mui/material';

function Component() {
  const theme = useTheme();

  return (
    <Box
      sx={{
        p: 2,
        bgcolor: theme.palette.primary.main,
        color: theme.palette.primary.contrastText,
        borderRadius: theme.shape.borderRadius,
      }}
    >
      Caixa tematizada
    </Box>
  );
}

Tema na Prop sx

<Box
  sx={{
    // Acessar tema em sx
    color: 'primary.main',          // theme.palette.primary.main
    bgcolor: 'background.paper',     // theme.palette.background.paper
    p: 2,                            // theme.spacing(2)
    borderRadius: 1,                 // theme.shape.borderRadius
  }}
>
  Conteúdo
</Box>

// Callback para uso avançado
<Box
  sx={(theme) => ({
    color: theme.palette.primary.main,
    '&:hover': {
      color: theme.palette.primary.dark,
    },
  })}
>
  Passe o mouse sobre mim
</Box>

Design Responsivo

Breakpoints

// Valores responsivos mobile-first
<Box
  sx={{
    width: {
      xs: '100%',    // 0-600px
      sm: '80%',     // 600-900px
      md: '60%',     // 900-1200px
      lg: '40%',     // 1200-1536px
      xl: '30%',     // 1536px+
    },
  }}
>
  Largura responsiva
</Box>

// Display responsivo
<Box
  sx={{
    display: {
      xs: 'none',    // Oculto em mobile
      md: 'block',   // Visível em desktop
    },
  }}
>
  Apenas desktop
</Box>

Tipografia Responsiva

<Typography
  sx={{
    fontSize: {
      xs: '1rem',
      md: '1.5rem',
      lg: '2rem',
    },
    lineHeight: {
      xs: 1.5,
      md: 1.75,
    },
  }}
>
  Texto responsivo
</Typography>

Formulários

import { TextField, Stack, Button } from '@mui/material';

<Box component="form"
  <Stack spacing={2}>
    <TextField
      label="Email"
      type="email"
      value={email}
      => setEmail(e.target.value)}
      fullWidth
      required
      error={!!errors.email}
      helperText={errors.email}
    />
    <Button type="submit" variant="contained">Enviar</Button>
  </Stack>
</Box>

Padrões Comuns

Componente Card

import { Card, CardContent, CardActions, Typography, Button } from '@mui/material';

<Card>
  <CardContent>
    <Typography variant="h5" component="div">
      Título
    </Typography>
    <Typography variant="body2" color="text.secondary">
      Descrição
    </Typography>
  </CardContent>
  <CardActions>
    <Button size="small">Saiba Mais</Button>
  </CardActions>
</Card>

Dialog/Modal

import { Dialog, DialogTitle, DialogContent, DialogActions, Button } from '@mui/material';

<Dialog open={open}
  <DialogTitle>Confirmar Ação</DialogTitle>
  <DialogContent>
    Tem certeza de que deseja prosseguir?
  </DialogContent>
  <DialogActions>
    <Button
    <Button variant="contained">
      Confirmar
    </Button>
  </DialogActions>
</Dialog>

Estados de Carregamento

import { CircularProgress, Skeleton } from '@mui/material';

// Spinner
<Box sx={{ display: 'flex', justifyContent: 'center', p: 3 }}>
  <CircularProgress />
</Box>

// Skeleton
<Stack spacing={1}>
  <Skeleton variant="text" width="60%" />
  <Skeleton variant="rectangular" height={200} />
  <Skeleton variant="text" width="40%" />
</Stack>

Hooks Específicos do MUI

useMuiSnackbar

import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

function Component() {
  const { showSuccess, showError, showInfo } = useMuiSnackbar();

  const handleSave = async () => {
    try {
      await saveData();
      showSuccess('Salvo com sucesso');
    } catch (error) {
      showError('Falha ao salvar');
    }
  };

  return <Button
}

Ícones

import { Add as AddIcon, Delete as DeleteIcon } from '@mui/icons-material';
import { Button, IconButton } from '@mui/material';

<Button startIcon={<AddIcon />}>Adicionar</Button>
<IconButton /></IconButton>

Melhores Práticas

1. Digite Suas Props sx

import type { SxProps, Theme } from '@mui/material';

// ✅ Bom
const styles: Record<string, SxProps<Theme>> = {
  container: { p: 2 },
};

// ❌ Evitar
const styles = {
  container: { p: 2 }, // Sem segurança de tipo
};

2. Use Tokens de Tema

// ✅ Bom: Use tokens de tema
<Box sx={{ color: 'primary.main', p: 2 }} />

// ❌ Evitar: Valores codificados
<Box sx={{ color: '#1976d2', padding: '16px' }} />

3. Espaçamento Consistente

// ✅ Bom: Use escala de espaçamento
<Box sx={{ p: 2, mb: 3, mt: 1 }} />

// ❌ Evitar: Valores de pixel aleatórios
<Box sx={{ padding: '17px', marginBottom: '25px' }} />

Recursos Adicionais

Para padrões mais detalhados, veja:

• styling-guide.md - Padrões de estilização avançada
• component-library.md - Exemplos de componentes
• theme-customization.md - Configuração de tema