mui-v7-mastery

MUI V7 Mastery

React + TypeScript でプロフェッショナルかつレスポンシブなインターフェースを作成するための、Material-UI V7 に特化したスキルです。移行、ベストプラクティス、高度なパターンに関する知識を提供します。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• ダッシュボードや管理インターフェースを作成するとき
• Material Design を使用した React アプリケーションを開発するとき
• MUI V6 から V7 に移行するとき
• モバイルファーストのレスポンシブパターンが必要なとき
• ダークモードを備えたプロフェッショナルなテーマを設定するとき
• 複雑なコンポーネント（テーブル、フォームなど）を実装するとき
• MUI V7 の API を正しく使用したいとき

MUI V7 の使用方針

🎨 MUI はボタンやバーだけのものではありません！

MUI V7 の真の力は、次の点にあります：

1. レスポンシブな Grid システム - 画面に合わせて調整されるプロフェッショナルなレイアウト
2. 高度なテーマ設定 - ブランドを完全にカスタマイズ
3. 複合コンポーネント - 豊かなユーザー体験を作成
4. CSS Variables - パフォーマンスに優れた動的なテーマ
5. デザインシステム - アプリケーション全体で一貫性を確保
6. デフォルトでモバイルファースト - どのデバイスでも快適に動作するインターフェース

📱 モバイルファーストの基本

必ずモバイル向けに設計してから、デスクトップ向けに拡張してください！

基本原則

1. xs（0px）から始める - 基本スタイルはモバイルで機能します
2. up() を使って拡張する - デスクトップ向けには theme.breakpoints.up('md') を使用します
3. 2D レイアウトには Grid を使う - カード、ギャラリー、ダッシュボード
4. 1D レイアウトには Stack を使う - 縦方向／横方向のリスト
5. タッチターゲットは 44px 以上 - クリック可能なボタンやアイコン（WCAG 2.2 AAA）

MUI V7 のブレークポイント

名前	ピクセル	デバイス
xs	0px	モバイル縦向き
sm	600px	モバイル横向き／タブレット縦向き
md	900px	タブレット横向き／小型デスクトップ
lg	1200px	デスクトップ
xl	1536px	大型デスクトップ

Grid と 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"

sx と useMediaQuery の使い分け

Precisa de responsividade?
│
├─ Apenas ESTILOS mudam? → sx prop
│   └─ fontSize, padding, display, width, etc
│
└─ LÓGICA/COMPORTAMENTO muda? → useMediaQuery
    └─ Componentes diferentes, render condicional

クイックスタート

1. 新しいインターフェースを作成する場合（モバイルファースト）

// 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 (
    <Container maxWidth="lg">
      {/* PASSO 3: Mobile-first Grid (xs → md → lg) */}
      <Grid container spacing={{ xs: 2, md: 3 }}>
        {/* Mobile: 100% largura, Tablet: 50%, Desktop: 33% */}
        <Grid size={{ xs: 12, md: 6, lg: 4 }}>
          <Card sx={{
            p: { xs: 2, md: 3 },  // Padding responsivo
            minHeight: 200
          }}>
            {/* PASSO 4: Touch targets ≥44px em mobile */}
            <Stack direction="row" spacing={1}>
              <IconButton sx={{ minHeight: 44, minWidth: 44 }}>
                <EditIcon />
              </IconButton>
            </Stack>

            {/* PASSO 5: Componentes diferentes se necessário */}
            {isMobile ? <MobileView /> : <DesktopView />}
          </Card>
        </Grid>
      </Grid>
    </Container>
  );
}

2. V6 から V7 に移行する場合

# 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. プロフェッショナルなテーマを設定する場合

// 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,
        },
      },
    },
  },
});

推奨ワークフロー

MUI に関するすべての作業

1. 作業の種類を特定します：

   • 新しいインターフェースですか？ → responsive-design.md と advanced-components.md を読みます
   • 移行ですか？ → まず migration-v6-to-v7.md を読みます
   • テーマですか？ → advanced-theming.md を読みます
   • すべてに該当しますか？ → すべてのリファレンスを読みます

2. 関連するリファレンスを読みます：

   // SEMPRE faça isso ANTES de escrever código
   view references/[arquivo-relevante].md
   

3. パターンに従って実装します：

   • リファレンスの例をベースとして使用します
   • 具体的なケースに合わせて調整します
   • 記載されているベストプラクティスに従います

4. ESLint で検証します（任意ですが推奨）：

   node scripts/setup-mui-eslint.js
   npm run lint:mui
   

利用可能なリソース

📚 リファレンス（必要に応じて参照してください）

migration-v6-to-v7.md

読むタイミング： 既存のコードを移行するとき、または破壊的変更によるエラーを修正するとき。

内容：

• ❌ 旧構文と ✅ V7 の新構文
• 破壊的変更（Grid、インポート、props）
• 自動 Codemod
• ステップごとの移行ガイド
• V7 の新機能（ESM、CSS Layers）

使用する状況：

• V7 に更新した後のインポートエラー
• Grid コンポーネントが動作しない
• 非推奨の props が使用されている
• Hidden、Dialog.onBackdropClick などに関する問題

responsive-design.md

読むタイミング： モバイルで動作する必要があるインターフェースを作成するとき。

内容：

• 例を含む Grid システムの全容
• ブレークポイントと useMediaQuery
• レスポンシブなナビゲーションパターン
• レスポンシブなカード、フォーム、ダイアログ
• モバイルファーストのベストプラクティス

使用する状況：

• レスポンシブなダッシュボードの作成
• さまざまな画面に合わせて調整されるレイアウト
• モバイルとデスクトップでのナビゲーション
• モバイル向けに最適化されたフォーム

advanced-theming.md

読むタイミング： カスタムテーマやダークモードを設定するとき。

以下を含みます：

• TypeScript でのテーマ作成
• CSS Variables（新しい V7 のアプローチ）
• ダーク／ライトモードの切り替え
• コンポーネントの高度なカスタマイズ
• カスタムバリアント
• Module augmentation

使用例：

• ブランドのビジュアルアイデンティティを適用する
• ダークモードを実装する
• コンポーネントのカスタムバリアントを作成する
• 一貫性のあるグローバルスタイル設定

advanced-components.md

読むタイミング： 複雑なコンポーネントを実装するとき。

以下を含みます：

• 完全なダッシュボードレイアウト
• スケルトンローディング付きカード
• 高度なデータテーブル（ソート、検索、ページネーション）
• バリデーション付きフォーム
• トースト／スナックバーシステム
• 非同期オートコンプリート
• パフォーマンス（遅延読み込み、メモ化、仮想化）

使用例：

• プロフェッショナルなレイアウトを作成する
• データテーブルを実装する
• バリデーション付きの複雑なフォーム
• ローディング状態
• 大規模なリスト（仮想化）

🔧 スクリプト

setup-mui-eslint.js

目的： ESLint を設定して、古い MUI V6 の構文を自動的に検出します。

使用方法：

node scripts/setup-mui-eslint.js

機能：

• カスタム ESLint ルールを追加します
• 非推奨のインポートを検出します
• 削除された props について警告します
• 親しみやすく学びにつながるメッセージを表示します（絵文字＋説明）
• 自動移行用の npm スクリプトを作成します

メッセージの例：

• ❌ MUI V7 では Deep imports はサポートされなくなりました
• ✨ このコンポーネントは @mui/material に移動されました
• ⚠️ Grid の名前が変更されました。新しい Grid への移行をご検討ください
• 🔄 onBackdropClick ではなく onClose を使用してください

V7 の重大な変更（クイックサマリー）

❌ もう動作しません：

// 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
<Dialog onBackdropClick={...} /> // ❌
<InputLabel size="normal" /> // ❌
<Hidden xlUp>...</Hidden> // ❌

✅ 今すぐ使用：

// 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
<Dialog onClose={(e, reason) => {...}} /> // ✅
<InputLabel size="medium" /> // ✅
<Box sx={{ display: { xl: 'none' } }} /> // ✅

ダッシュボードの応答パターン

「見栄えの良いダッシュボードを作成して」と依頼された場合は、次のパターンに従ってください：

1. リファレンスを読む：

   view references/responsive-design.md
   view references/advanced-components.md
   view references/advanced-theming.md
   

2. モバイルファーストのアプローチで実装する：

   • xs（モバイル）から始める — 縦方向のレイアウト、タッチターゲットは 44px
   • md（タブレット）に拡張する — 2 列、広めの間隔
   • lg（デスクトップ）で仕上げる — 3〜4 列、コンパクトな密度
   • 新しい Grid V7 を使用したレスポンシブレイアウト
   • ダークモード対応のカスタムテーマ
   • プロフェッショナルなコンポーネント（基本的な Button だけにしない）
   • ローディング状態（Skeleton）
   • any を使わない TypeScript

3. 必ず含める（モバイルファースト）：

   • 中央揃え用の Container
   • size={{ xs: 12, md: 6, lg: 4 }} を指定した Grid
   • レスポンシブなパディング p={{ xs: 2, md: 3 }} を指定したカード
   • IconButton／Button のタッチターゲットは 44px 以上
   • 縦方向のレイアウトには Stack を使用する（Grid direction="column" は使わない）
   • ローディングには Skeleton を使用する
   • ロジックが変わる場合に限り useMediaQuery を使用する
   • cssVariables を使用したテーマ
   • 375px、768px、1200px でテストする

とっておきのヒント 💡

モバイルファースト（最優先！）

• 常に xs から始める — まずモバイル向けの基本スタイルを設定します
• 拡張には up() を使用する — theme.breakpoints.up('md') を使い、down() は使いません
• タッチターゲットは 44px 以上 — ボタン、アイコン、クリック可能なリンク

  <IconButton sx={{ minHeight: 44, minWidth: 44 }}>
  

• ターゲット間の間隔は 10px 以上 — 誤タップを防ぎます
• 2D には Grid、1D には Stack — Grid direction="column" は使わないでください
• スタイルには sx、ロジックには useMediaQuery
• 375px、768px、1200px でテストする — 重要な境界値です

タッチターゲット（WCAG 2.2）

コンテキスト	表示サイズ	タッチターゲット	WCAG レベル
モバイルの主要操作	40-48px	48px	AAA
デスクトップのコンパクト表示	32-36px	44px	AAA
法的な最小値	24px	24px	AA

推奨パターン：

// Visual: 36px (compacto), Touch: 48px (seguro)
<Button sx={{
  height: { xs: 40, md: 36 },  // Visual height
  minHeight: { xs: 48, md: 44 } // Touch target
}}>
  Action
</Button>

パフォーマンス

• 動的なテーマには cssVariables: true を使用します
• ローディング状態には Skeleton を実装します
• 重いコンポーネントには遅延読み込みを使用します
• 大規模なリストは仮想化します（react-window）
• useMediaQuery を共有する — 子コンポーネントでの重複を避けます

レスポンシブ対応

• 常にモバイルファースト - xs → sm → md → lg → xl
• Grid では size={{ xs: 12, md: 6 }} を使用します
• レスポンシブスタイルには sx prop を使用します：

  sx={{
    fontSize: { xs: '14px', md: '16px' },
    p: { xs: 2, md: 3 }
  }}
  

• useMediaQuery は条件分岐のロジックにのみ使用します
• エミュレーターだけでなく、実機でもテストします

テーマ設定

• 最初からダークモードを設定します
• CSS 変数には theme.vars.* を使用します
• インラインではなく、テーマ内にバリアントを作成します
• TypeScript では module augmentation を使用します

コンポーネント

• パターンについては advanced-components.md を参照してください
• prop drilling ではなく、コンポジションを使用します
• 負荷の高いコンポーネントをメモ化します
• スケルトン > 読み込みスピナー

便利なコマンド

# Migração automática
npx @mui/codemod v7.0.0/lab-removed-components src
npx @mui/codemod v7.0.0/grid-props src
npx @mui/codemod v7.0.0/input-label-size-normal-medium src

# Setup ESLint (detecção de código antigo)
node scripts/setup-mui-eslint.js

# Lint MUI
npm run lint:mui

# Migração completa (após configurar ESLint)
npm run mui-migrate

モバイルファーストの品質チェックリスト

MUI V7 のインターフェースを完成とする前に、以下を確認してください。

モバイルファースト設計

• xs（0px）のベーススタイル - まずモバイルで動作する
• up() による段階的な拡張 - theme.breakpoints.up('md') と up('lg')
• タッチターゲット ≥44px - ボタン、アイコン、リンク（WCAG 2.2 AAA）
• 視覚上の高さは32～36pxでも可。ただし、タッチターゲットは≥44px
• インタラクティブ要素間の間隔 ≥10px
• 2D レイアウトには Grid - カード、ダッシュボード、ギャラリー
• 1D レイアウトには Stack - 縦方向／横方向のリスト
• Grid direction="column" は使用しない - Stack を使用します

レスポンシブ対応

• **375px（小型モバイル）**でレイアウトをテスト済み
• **599px（sm ブレークポイントの境界）**でレイアウトをテスト済み
• **768px（タブレット）**でレイアウトをテスト済み
• **899px（md ブレークポイントの境界）**でレイアウトをテスト済み
• **1199px（lg ブレークポイントの境界）**でレイアウトをテスト済み
• **1920px（大型デスクトップ）**でレイアウトをテスト済み
• スタイルに sx prop を使用 - fontSize、padding、display
• useMediaQuery はロジックにのみ使用 - 異なるコンポーネント、条件付きレンダリング
• useMediaQuery を共有 - 子コンポーネントで重複させない
• ブレークポイントにピクセル値をハードコードしていない

テーマとスタイル

• ダークモードを含むテーマを設定済み
• cssVariables: true を有効化済み
• 非推奨のインポートによるエラーがない

パフォーマンス

• 読み込み状態を実装済み（スケルトン）
• 負荷の高いコンポーネントに遅延読み込みを適用済み
• 大規模なリストを仮想化済み（react-window）
• 必要に応じてコンポーネントをメモ化済み

コード品質

• TypeScript のエラーがない
• any を使用していない
• コンポーネントが Atomic Design に従っている（該当する場合）

アクセシビリティ

• 適切な色のコントラスト（最低でも WCAG AA）
• インタラクティブ要素に ARIA ラベルを設定済み
• タッチターゲットが WCAG 2.2 に準拠
• スクリーンリーダーでテスト済み（重要な場合）

外部リソース

• MUI V7 公式ドキュメント
• 移行ガイド
• テーマクリエーター
• Material Design ガイドライン

---

忘れないでください： MUI V7 は、その機能を十分に活用すると強力です。ボタンだけにとどまらず、Grid、テーマ設定、コンポジション、高度なパターンも活用しましょう！ 🚀