---
name: mui-v7-mastery
description: Guia completo de MUI V7 para React + TypeScript. Ensina migração V6→V7, design responsivo avançado, theming profissional, padrões de componentes e detecção automática de sintaxe antiga. Use quando criar dashboards, interfaces modernas, ou trabalhar com Material-UI/MUI.
---
# MUI V7 Mastery
Skill especializada em Material-UI V7 para criar interfaces profissionais e responsivas com React + TypeScript. Fornece conhecimento sobre migração, melhores práticas, e padrões avançados.
## Quando Usar Esta Skill
Use esta skill quando:
- Criar dashboards ou interfaces administrativas
- Desenvolver aplicações React com Material Design
- Migrar de MUI V6 para V7
- Precisar de padrões responsivos mobile-first
- Configurar temas profissionais com dark mode
- Implementar componentes complexos (tabelas, formulários, etc)
- Quiser garantir uso correto da API do MUI V7
## Filosofia de Uso do MUI V7
**🎨 O MUI não é apenas para botões e barras!**
O verdadeiro poder do MUI V7 está em:
1. **Sistema de Grid responsivo** - Layouts profissionais que se adaptam
2. **Theming avançado** - Personalização completa da marca
3. **Componentes compostos** - Criar experiências ricas
4. **CSS Variables** - Temas dinâmicos performáticos
5. **Design System** - Consistência em toda aplicação
6. **Mobile-First by Default** - Interfaces que funcionam perfeitamente em qualquer dispositivo
## 📱 Mobile-First Essentials
**SEMPRE projete para mobile primeiro, depois expanda para desktop!**
### Princípios Fundamentais
1. **Comece em xs (0px)** - Base styles funcionam em mobile
2. **Use `up()` para expandir** - `theme.breakpoints.up('md')` para desktop
3. **Grid para layouts 2D** - Cards, galerias, dashboards
4. **Stack para layouts 1D** - Listas verticais/horizontais
5. **Touch targets ≥44px** - Botões e ícones clicáveis (WCAG 2.2 AAA)
### Breakpoints MUI V7
| Nome | Pixels | Dispositivo |
|------|--------|-------------|
| xs | 0px | Mobile portrait |
| sm | 600px | Mobile landscape / Tablet portrait |
| md | 900px | Tablet landscape / Desktop small |
| lg | 1200px | Desktop |
| xl | 1536px | Desktop large |
### Quando Usar Grid vs Stack
```
Precisa de layout?
│
├─ Itens em LINHAS E COLUNAS? → Grid
│ └─ Exemplo: Cards de produtos, dashboard tiles
│
└─ Itens em UMA DIREÇÃO? → Stack
├─ Vertical? → Stack (default)
└─ Horizontal? → Stack direction="row"
```
### Quando Usar sx vs useMediaQuery
```
Precisa de responsividade?
│
├─ Apenas ESTILOS mudam? → sx prop
│ └─ fontSize, padding, display, width, etc
│
└─ LÓGICA/COMPORTAMENTO muda? → useMediaQuery
└─ Componentes diferentes, render condicional
```
## Quick Start
### 1. Para Criar Nova Interface (Mobile-First)
```typescript
// PASSO 1: Comece lendo as referências relevantes
// - Read references/responsive-design.md
// - Read references/advanced-theming.md
// - Read references/advanced-components.md
import { Container, Grid, Card, Stack, IconButton, useTheme, useMediaQuery } from '@mui/material';
function Dashboard() {
const theme = useTheme();
// PASSO 2: Defina breakpoint APENAS se lógica/comportamento mudar
const isMobile = useMediaQuery(theme.breakpoints.down('md'));
return (
{/* PASSO 3: Mobile-first Grid (xs → md → lg) */}
{/* Mobile: 100% largura, Tablet: 50%, Desktop: 33% */}
{/* PASSO 4: Touch targets ≥44px em mobile */}
{/* PASSO 5: Componentes diferentes se necessário */}
{isMobile ? : }
);
}
```
### 2. Para Migrar de V6 para V7
```bash
# ANTES de qualquer código, leia:
# references/migration-v6-to-v7.md
# Depois execute os codemods:
npx @mui/codemod v7.0.0/grid-props src
npx @mui/codemod v7.0.0/lab-removed-components src
npx @mui/codemod v7.0.0/input-label-size-normal-medium src
# Configure ESLint para detectar código antigo:
node scripts/setup-mui-eslint.js
```
### 3. Para Configurar Tema Profissional
```typescript
// Leia references/advanced-theming.md primeiro
import { createTheme, ThemeProvider } from '@mui/material/styles';
const theme = createTheme({
cssVariables: true, // ✅ Ativa CSS variables (recomendado V7)
colorSchemes: {
light: {
palette: {
primary: { main: '#1976d2' },
background: { default: '#fafafa' },
},
},
dark: {
palette: {
primary: { main: '#90caf9' },
background: { default: '#121212' },
},
},
},
typography: {
fontFamily: 'Inter, system-ui, sans-serif',
},
components: {
MuiButton: {
styleOverrides: {
root: {
textTransform: 'none',
borderRadius: 8,
},
},
},
},
});
```
## Fluxo de Trabalho Recomendado
### Para Qualquer Tarefa MUI
1. **Identifique o tipo de trabalho:**
- Nova interface? → Leia responsive-design.md + advanced-components.md
- Migração? → Leia migration-v6-to-v7.md primeiro
- Tema? → Leia advanced-theming.md
- Tudo junto? → Leia todos os references
2. **Leia as referências relevantes:**
```typescript
// SEMPRE faça isso ANTES de escrever código
view references/[arquivo-relevante].md
```
3. **Implemente seguindo os padrões:**
- Use os exemplos das referências como base
- Adapte ao caso específico
- Siga as melhores práticas indicadas
4. **Valide com ESLint (opcional mas recomendado):**
```bash
node scripts/setup-mui-eslint.js
npm run lint:mui
```
## Recursos Disponíveis
### 📚 References (Leia conforme necessidade)
#### [migration-v6-to-v7.md](references/migration-v6-to-v7.md)
**Quando ler:** Ao migrar código existente ou corrigir erros de breaking changes.
Contém:
- ❌ Sintaxe antiga vs ✅ Nova sintaxe V7
- Mudanças de breaking changes (Grid, imports, props)
- Codemods automáticos
- Guia passo-a-passo de migração
- Novos recursos do V7 (ESM, CSS Layers)
**Situações de uso:**
- Erros de import após atualizar para V7
- Componentes Grid não funcionando
- Props depreciadas sendo usadas
- Problemas com Hidden, Dialog.onBackdropClick, etc
#### [responsive-design.md](references/responsive-design.md)
**Quando ler:** Ao criar qualquer interface que precisa funcionar em mobile.
Contém:
- Sistema Grid completo com exemplos
- Breakpoints e useMediaQuery
- Padrões de navegação responsiva
- Cards, formulários e dialogs responsivos
- Mobile-first best practices
**Situações de uso:**
- Criar dashboards responsivos
- Layouts que se adaptam a diferentes telas
- Navegação mobile vs desktop
- Formulários otimizados para mobile
#### [advanced-theming.md](references/advanced-theming.md)
**Quando ler:** Ao configurar tema personalizado ou dark mode.
Contém:
- Criação de tema com TypeScript
- CSS Variables (nova abordagem V7)
- Dark/Light mode toggle
- Customização avançada de componentes
- Variantes customizadas
- Module augmentation
**Situações de uso:**
- Aplicar identidade visual da marca
- Implementar dark mode
- Criar variantes customizadas de componentes
- Estilização global consistente
#### [advanced-components.md](references/advanced-components.md)
**Quando ler:** Ao implementar componentes complexos.
Contém:
- Dashboard layout completo
- Cards com skeleton loading
- Data tables avançadas (sort, search, pagination)
- Formulários com validação
- Sistema de toasts/snackbar
- Autocomplete assíncrono
- Performance (lazy loading, memoização, virtualização)
**Situações de uso:**
- Criar layouts profissionais
- Implementar tabelas de dados
- Formulários complexos com validação
- Loading states
- Listas grandes (virtualização)
### 🔧 Scripts
#### [setup-mui-eslint.js](scripts/setup-mui-eslint.js)
**Propósito:** Configurar ESLint para detectar sintaxe antiga do MUI V6 automaticamente.
**Como usar:**
```bash
node scripts/setup-mui-eslint.js
```
**O que faz:**
- Adiciona regras ESLint customizadas
- Detecta imports depreciados
- Avisa sobre props removidas
- Mensagens amigáveis e educativas (emoji + explicação)
- Cria scripts npm para migração automática
**Mensagens exemplo:**
- ❌ Deep imports não são mais suportados no MUI V7
- ✨ Este componente foi movido para @mui/material
- ⚠️ Grid foi renomeado. Considere migrar para novo Grid
- 🔄 Use onClose em vez de onBackdropClick
## Mudanças Críticas V7 (Resumo Rápido)
### ❌ NÃO FUNCIONA MAIS:
```typescript
// Deep imports
import createTheme from '@mui/material/styles/createTheme'; // ❌
// Grid antigo
import Grid from '@mui/material/Grid'; // ❌ (agora é GridLegacy)
// Grid2
import Grid2 from '@mui/material/Grid2'; // ❌ (agora é Grid)
// Componentes do lab
import Alert from '@mui/lab/Alert'; // ❌
// Props depreciadas
// ❌
// ❌
... // ❌
```
### ✅ USE AGORA:
```typescript
// Imports corretos
import { createTheme } from '@mui/material/styles'; // ✅
// Novo Grid (era Grid2)
import Grid from '@mui/material/Grid'; // ✅
// Componentes movidos
import Alert from '@mui/material/Alert'; // ✅
// Props atualizadas