@fprad0/skill-master-mcp 0.0.12 → 1.0.0

package/docs/skill-candidates/v0.0.11/frontend-dev-guidelines/resources/loading-and-error-states.md

@@ -1,501 +1,501 @@
-# Loading & Error States
-
-**CRITICAL**: Proper loading and error state handling prevents layout shift and provides better user experience.
-
----
-
-## ⚠️ CRITICAL RULE: Never Use Early Returns
-
-### The Problem
-
-```typescript
-// ❌ NEVER DO THIS - Early return with loading spinner
-const Component = () => {
-    const { data, isLoading } = useQuery();
-
-    // WRONG: This causes layout shift and poor UX
-    if (isLoading) {
-        return <LoadingSpinner />;
-    }
-
-    return <Content data={data} />;
-};
-```
-
-**Why this is bad:**
-1. **Layout Shift**: Content position jumps when loading completes
-2. **CLS (Cumulative Layout Shift)**: Poor Core Web Vital score
-3. **Jarring UX**: Page structure changes suddenly
-4. **Lost Scroll Position**: User loses place on page
-
-### The Solutions
-
-**Option 1: SuspenseLoader (PREFERRED for new components)**
-
-```typescript
-import { SuspenseLoader } from '~components/SuspenseLoader';
-
-const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
-
-export const MyComponent: React.FC = () => {
-    return (
-        <SuspenseLoader>
-            <HeavyComponent />
-        </SuspenseLoader>
-    );
-};
-```
-
-**Option 2: LoadingOverlay (for legacy useQuery patterns)**
-
-```typescript
-import { LoadingOverlay } from '~components/LoadingOverlay';
-
-export const MyComponent: React.FC = () => {
-    const { data, isLoading } = useQuery({ ... });
-
-    return (
-        <LoadingOverlay loading={isLoading}>
-            <Content data={data} />
-        </LoadingOverlay>
-    );
-};
-```
-
----
-
-## SuspenseLoader Component
-
-### What It Does
-
-- Shows loading indicator while lazy components load
-- Smooth fade-in animation
-- Prevents layout shift
-- Consistent loading experience across app
-
-### Import
-
-```typescript
-import { SuspenseLoader } from '~components/SuspenseLoader';
-// Or
-import { SuspenseLoader } from '@/components/SuspenseLoader';
-```
-
-### Basic Usage
-
-```typescript
-<SuspenseLoader>
-    <LazyLoadedComponent />
-</SuspenseLoader>
-```
-
-### With useSuspenseQuery
-
-```typescript
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { SuspenseLoader } from '~components/SuspenseLoader';
-
-const Inner: React.FC = () => {
-    // No isLoading needed!
-    const { data } = useSuspenseQuery({
-        queryKey: ['data'],
-        queryFn: () => api.getData(),
-    });
-
-    return <Display data={data} />;
-};
-
-// Outer component wraps in Suspense
-export const Outer: React.FC = () => {
-    return (
-        <SuspenseLoader>
-            <Inner />
-        </SuspenseLoader>
-    );
-};
-```
-
-### Multiple Suspense Boundaries
-
-**Pattern**: Separate loading for independent sections
-
-```typescript
-export const Dashboard: React.FC = () => {
-    return (
-        <Box>
-            <SuspenseLoader>
-                <Header />
-            </SuspenseLoader>
-
-            <SuspenseLoader>
-                <MainContent />
-            </SuspenseLoader>
-
-            <SuspenseLoader>
-                <Sidebar />
-            </SuspenseLoader>
-        </Box>
-    );
-};
-```
-
-**Benefits:**
-- Each section loads independently
-- User sees partial content sooner
-- Better perceived performance
-
-### Nested Suspense
-
-```typescript
-export const ParentComponent: React.FC = () => {
-    return (
-        <SuspenseLoader>
-            {/* Parent suspends while loading */}
-            <ParentContent>
-                <SuspenseLoader>
-                    {/* Nested suspense for child */}
-                    <ChildComponent />
-                </SuspenseLoader>
-            </ParentContent>
-        </SuspenseLoader>
-    );
-};
-```
-
----
-
-## LoadingOverlay Component
-
-### When to Use
-
-- Legacy components with `useQuery` (not refactored to Suspense yet)
-- Overlay loading state needed
-- Can't use Suspense boundaries
-
-### Usage
-
-```typescript
-import { LoadingOverlay } from '~components/LoadingOverlay';
-
-export const MyComponent: React.FC = () => {
-    const { data, isLoading } = useQuery({
-        queryKey: ['data'],
-        queryFn: () => api.getData(),
-    });
-
-    return (
-        <LoadingOverlay loading={isLoading}>
-            <Box sx={{ p: 2 }}>
-                {data && <Content data={data} />}
-            </Box>
-        </LoadingOverlay>
-    );
-};
-```
-
-**What it does:**
-- Shows semi-transparent overlay with spinner
-- Content area reserved (no layout shift)
-- Prevents interaction while loading
-
----
-
-## Error Handling
-
-### useMuiSnackbar Hook (REQUIRED)
-
-**NEVER use react-toastify** - Project standard is MUI Snackbar
-
-```typescript
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-
-export const MyComponent: React.FC = () => {
-    const { showSuccess, showError, showInfo, showWarning } = useMuiSnackbar();
-
-    const handleAction = async () => {
-        try {
-            await api.doSomething();
-            showSuccess('Operation completed successfully');
-        } catch (error) {
-            showError('Operation failed');
-        }
-    };
-
-    return <Button onClick={handleAction}>Do Action</Button>;
-};
-```
-
-**Available Methods:**
-- `showSuccess(message)` - Green success message
-- `showError(message)` - Red error message
-- `showWarning(message)` - Orange warning message
-- `showInfo(message)` - Blue info message
-
-### TanStack Query Error Callbacks
-
-```typescript
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-
-export const MyComponent: React.FC = () => {
-    const { showError } = useMuiSnackbar();
-
-    const { data } = useSuspenseQuery({
-        queryKey: ['data'],
-        queryFn: () => api.getData(),
-
-        // Handle errors
-        onError: (error) => {
-            showError('Failed to load data');
-            console.error('Query error:', error);
-        },
-    });
-
-    return <Content data={data} />;
-};
-```
-
-### Error Boundaries
-
-```typescript
-import { ErrorBoundary } from 'react-error-boundary';
-
-function ErrorFallback({ error, resetErrorBoundary }) {
-    return (
-        <Box sx={{ p: 4, textAlign: 'center' }}>
-            <Typography variant='h5' color='error'>
-                Something went wrong
-            </Typography>
-            <Typography>{error.message}</Typography>
-            <Button onClick={resetErrorBoundary}>Try Again</Button>
-        </Box>
-    );
-}
-
-export const MyPage: React.FC = () => {
-    return (
-        <ErrorBoundary
-            FallbackComponent={ErrorFallback}
-            onError={(error) => console.error('Boundary caught:', error)}
-        >
-            <SuspenseLoader>
-                <ComponentThatMightError />
-            </SuspenseLoader>
-        </ErrorBoundary>
-    );
-};
-```
-
----
-
-## Complete Examples
-
-### Example 1: Modern Component with Suspense
-
-```typescript
-import React from 'react';
-import { Box, Paper } from '@mui/material';
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { SuspenseLoader } from '~components/SuspenseLoader';
-import { myFeatureApi } from '../api/myFeatureApi';
-
-// Inner component uses useSuspenseQuery
-const InnerComponent: React.FC<{ id: number }> = ({ id }) => {
-    const { data } = useSuspenseQuery({
-        queryKey: ['entity', id],
-        queryFn: () => myFeatureApi.getEntity(id),
-    });
-
-    // data is always defined - no isLoading needed!
-    return (
-        <Paper sx={{ p: 2 }}>
-            <h2>{data.title}</h2>
-            <p>{data.description}</p>
-        </Paper>
-    );
-};
-
-// Outer component provides Suspense boundary
-export const OuterComponent: React.FC<{ id: number }> = ({ id }) => {
-    return (
-        <Box>
-            <SuspenseLoader>
-                <InnerComponent id={id} />
-            </SuspenseLoader>
-        </Box>
-    );
-};
-
-export default OuterComponent;
-```
-
-### Example 2: Legacy Pattern with LoadingOverlay
-
-```typescript
-import React from 'react';
-import { Box } from '@mui/material';
-import { useQuery } from '@tanstack/react-query';
-import { LoadingOverlay } from '~components/LoadingOverlay';
-import { myFeatureApi } from '../api/myFeatureApi';
-
-export const LegacyComponent: React.FC<{ id: number }> = ({ id }) => {
-    const { data, isLoading, error } = useQuery({
-        queryKey: ['entity', id],
-        queryFn: () => myFeatureApi.getEntity(id),
-    });
-
-    return (
-        <LoadingOverlay loading={isLoading}>
-            <Box sx={{ p: 2 }}>
-                {error && <ErrorDisplay error={error} />}
-                {data && <Content data={data} />}
-            </Box>
-        </LoadingOverlay>
-    );
-};
-```
-
-### Example 3: Error Handling with Snackbar
-
-```typescript
-import React from 'react';
-import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { Button } from '@mui/material';
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-import { myFeatureApi } from '../api/myFeatureApi';
-
-export const EntityEditor: React.FC<{ id: number }> = ({ id }) => {
-    const queryClient = useQueryClient();
-    const { showSuccess, showError } = useMuiSnackbar();
-
-    const { data } = useSuspenseQuery({
-        queryKey: ['entity', id],
-        queryFn: () => myFeatureApi.getEntity(id),
-        onError: () => {
-            showError('Failed to load entity');
-        },
-    });
-
-    const updateMutation = useMutation({
-        mutationFn: (updates) => myFeatureApi.update(id, updates),
-
-        onSuccess: () => {
-            queryClient.invalidateQueries({ queryKey: ['entity', id] });
-            showSuccess('Entity updated successfully');
-        },
-
-        onError: () => {
-            showError('Failed to update entity');
-        },
-    });
-
-    return (
-        <Button onClick={() => updateMutation.mutate({ name: 'New' })}>
-            Update
-        </Button>
-    );
-};
-```
-
----
-
-## Loading State Anti-Patterns
-
-### ❌ What NOT to Do
-
-```typescript
-// ❌ NEVER - Early return
-if (isLoading) {
-    return <CircularProgress />;
-}
-
-// ❌ NEVER - Conditional rendering
-{isLoading ? <Spinner /> : <Content />}
-
-// ❌ NEVER - Layout changes
-if (isLoading) {
-    return (
-        <Box sx={{ height: 100 }}>
-            <Spinner />
-        </Box>
-    );
-}
-return (
-    <Box sx={{ height: 500 }}>  // Different height!
-        <Content />
-    </Box>
-);
-```
-
-### ✅ What TO Do
-
-```typescript
-// ✅ BEST - useSuspenseQuery + SuspenseLoader
-<SuspenseLoader>
-    <ComponentWithSuspenseQuery />
-</SuspenseLoader>
-
-// ✅ ACCEPTABLE - LoadingOverlay
-<LoadingOverlay loading={isLoading}>
-    <Content />
-</LoadingOverlay>
-
-// ✅ OK - Inline skeleton with same layout
-<Box sx={{ height: 500 }}>
-    {isLoading ? <Skeleton variant='rectangular' height='100%' /> : <Content />}
-</Box>
-```
-
----
-
-## Skeleton Loading (Alternative)
-
-### MUI Skeleton Component
-
-```typescript
-import { Skeleton, Box } from '@mui/material';
-
-export const MyComponent: React.FC = () => {
-    const { data, isLoading } = useQuery({ ... });
-
-    return (
-        <Box sx={{ p: 2 }}>
-            {isLoading ? (
-                <>
-                    <Skeleton variant='text' width={200} height={40} />
-                    <Skeleton variant='rectangular' width='100%' height={200} />
-                    <Skeleton variant='text' width='100%' />
-                </>
-            ) : (
-                <>
-                    <Typography variant='h5'>{data.title}</Typography>
-                    <img src={data.image} />
-                    <Typography>{data.description}</Typography>
-                </>
-            )}
-        </Box>
-    );
-};
-```
-
-**Key**: Skeleton must have **same layout** as actual content (no shift)
-
----
-
-## Summary
-
-**Loading States:**
-- ✅ **PREFERRED**: SuspenseLoader + useSuspenseQuery (modern pattern)
-- ✅ **ACCEPTABLE**: LoadingOverlay (legacy pattern)
-- ✅ **OK**: Skeleton with same layout
-- ❌ **NEVER**: Early returns or conditional layout
-
-**Error Handling:**
-- ✅ **ALWAYS**: useMuiSnackbar for user feedback
-- ❌ **NEVER**: react-toastify
-- ✅ Use onError callbacks in queries/mutations
-- ✅ Error boundaries for component-level errors
-
-**See Also:**
-- [component-patterns.md](component-patterns.md) - Suspense integration
+# Loading & Error States
+
+**CRITICAL**: Proper loading and error state handling prevents layout shift and provides better user experience.
+
+---
+
+## ⚠️ CRITICAL RULE: Never Use Early Returns
+
+### The Problem
+
+```typescript
+// ❌ NEVER DO THIS - Early return with loading spinner
+const Component = () => {
+    const { data, isLoading } = useQuery();
+
+    // WRONG: This causes layout shift and poor UX
+    if (isLoading) {
+        return <LoadingSpinner />;
+    }
+
+    return <Content data={data} />;
+};
+```
+
+**Why this is bad:**
+1. **Layout Shift**: Content position jumps when loading completes
+2. **CLS (Cumulative Layout Shift)**: Poor Core Web Vital score
+3. **Jarring UX**: Page structure changes suddenly
+4. **Lost Scroll Position**: User loses place on page
+
+### The Solutions
+
+**Option 1: SuspenseLoader (PREFERRED for new components)**
+
+```typescript
+import { SuspenseLoader } from '~components/SuspenseLoader';
+
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+
+export const MyComponent: React.FC = () => {
+    return (
+        <SuspenseLoader>
+            <HeavyComponent />
+        </SuspenseLoader>
+    );
+};
+```
+
+**Option 2: LoadingOverlay (for legacy useQuery patterns)**
+
+```typescript
+import { LoadingOverlay } from '~components/LoadingOverlay';
+
+export const MyComponent: React.FC = () => {
+    const { data, isLoading } = useQuery({ ... });
+
+    return (
+        <LoadingOverlay loading={isLoading}>
+            <Content data={data} />
+        </LoadingOverlay>
+    );
+};
+```
+
+---
+
+## SuspenseLoader Component
+
+### What It Does
+
+- Shows loading indicator while lazy components load
+- Smooth fade-in animation
+- Prevents layout shift
+- Consistent loading experience across app
+
+### Import
+
+```typescript
+import { SuspenseLoader } from '~components/SuspenseLoader';
+// Or
+import { SuspenseLoader } from '@/components/SuspenseLoader';
+```
+
+### Basic Usage
+
+```typescript
+<SuspenseLoader>
+    <LazyLoadedComponent />
+</SuspenseLoader>
+```
+
+### With useSuspenseQuery
+
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { SuspenseLoader } from '~components/SuspenseLoader';
+
+const Inner: React.FC = () => {
+    // No isLoading needed!
+    const { data } = useSuspenseQuery({
+        queryKey: ['data'],
+        queryFn: () => api.getData(),
+    });
+
+    return <Display data={data} />;
+};
+
+// Outer component wraps in Suspense
+export const Outer: React.FC = () => {
+    return (
+        <SuspenseLoader>
+            <Inner />
+        </SuspenseLoader>
+    );
+};
+```
+
+### Multiple Suspense Boundaries
+
+**Pattern**: Separate loading for independent sections
+
+```typescript
+export const Dashboard: React.FC = () => {
+    return (
+        <Box>
+            <SuspenseLoader>
+                <Header />
+            </SuspenseLoader>
+
+            <SuspenseLoader>
+                <MainContent />
+            </SuspenseLoader>
+
+            <SuspenseLoader>
+                <Sidebar />
+            </SuspenseLoader>
+        </Box>
+    );
+};
+```
+
+**Benefits:**
+- Each section loads independently
+- User sees partial content sooner
+- Better perceived performance
+
+### Nested Suspense
+
+```typescript
+export const ParentComponent: React.FC = () => {
+    return (
+        <SuspenseLoader>
+            {/* Parent suspends while loading */}
+            <ParentContent>
+                <SuspenseLoader>
+                    {/* Nested suspense for child */}
+                    <ChildComponent />
+                </SuspenseLoader>
+            </ParentContent>
+        </SuspenseLoader>
+    );
+};
+```
+
+---
+
+## LoadingOverlay Component
+
+### When to Use
+
+- Legacy components with `useQuery` (not refactored to Suspense yet)
+- Overlay loading state needed
+- Can't use Suspense boundaries
+
+### Usage
+
+```typescript
+import { LoadingOverlay } from '~components/LoadingOverlay';
+
+export const MyComponent: React.FC = () => {
+    const { data, isLoading } = useQuery({
+        queryKey: ['data'],
+        queryFn: () => api.getData(),
+    });
+
+    return (
+        <LoadingOverlay loading={isLoading}>
+            <Box sx={{ p: 2 }}>
+                {data && <Content data={data} />}
+            </Box>
+        </LoadingOverlay>
+    );
+};
+```
+
+**What it does:**
+- Shows semi-transparent overlay with spinner
+- Content area reserved (no layout shift)
+- Prevents interaction while loading
+
+---
+
+## Error Handling
+
+### useMuiSnackbar Hook (REQUIRED)
+
+**NEVER use react-toastify** - Project standard is MUI Snackbar
+
+```typescript
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+export const MyComponent: React.FC = () => {
+    const { showSuccess, showError, showInfo, showWarning } = useMuiSnackbar();
+
+    const handleAction = async () => {
+        try {
+            await api.doSomething();
+            showSuccess('Operation completed successfully');
+        } catch (error) {
+            showError('Operation failed');
+        }
+    };
+
+    return <Button onClick={handleAction}>Do Action</Button>;
+};
+```
+
+**Available Methods:**
+- `showSuccess(message)` - Green success message
+- `showError(message)` - Red error message
+- `showWarning(message)` - Orange warning message
+- `showInfo(message)` - Blue info message
+
+### TanStack Query Error Callbacks
+
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+export const MyComponent: React.FC = () => {
+    const { showError } = useMuiSnackbar();
+
+    const { data } = useSuspenseQuery({
+        queryKey: ['data'],
+        queryFn: () => api.getData(),
+
+        // Handle errors
+        onError: (error) => {
+            showError('Failed to load data');
+            console.error('Query error:', error);
+        },
+    });
+
+    return <Content data={data} />;
+};
+```
+
+### Error Boundaries
+
+```typescript
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error, resetErrorBoundary }) {
+    return (
+        <Box sx={{ p: 4, textAlign: 'center' }}>
+            <Typography variant='h5' color='error'>
+                Something went wrong
+            </Typography>
+            <Typography>{error.message}</Typography>
+            <Button onClick={resetErrorBoundary}>Try Again</Button>
+        </Box>
+    );
+}
+
+export const MyPage: React.FC = () => {
+    return (
+        <ErrorBoundary
+            FallbackComponent={ErrorFallback}
+            onError={(error) => console.error('Boundary caught:', error)}
+        >
+            <SuspenseLoader>
+                <ComponentThatMightError />
+            </SuspenseLoader>
+        </ErrorBoundary>
+    );
+};
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Modern Component with Suspense
+
+```typescript
+import React from 'react';
+import { Box, Paper } from '@mui/material';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { SuspenseLoader } from '~components/SuspenseLoader';
+import { myFeatureApi } from '../api/myFeatureApi';
+
+// Inner component uses useSuspenseQuery
+const InnerComponent: React.FC<{ id: number }> = ({ id }) => {
+    const { data } = useSuspenseQuery({
+        queryKey: ['entity', id],
+        queryFn: () => myFeatureApi.getEntity(id),
+    });
+
+    // data is always defined - no isLoading needed!
+    return (
+        <Paper sx={{ p: 2 }}>
+            <h2>{data.title}</h2>
+            <p>{data.description}</p>
+        </Paper>
+    );
+};
+
+// Outer component provides Suspense boundary
+export const OuterComponent: React.FC<{ id: number }> = ({ id }) => {
+    return (
+        <Box>
+            <SuspenseLoader>
+                <InnerComponent id={id} />
+            </SuspenseLoader>
+        </Box>
+    );
+};
+
+export default OuterComponent;
+```
+
+### Example 2: Legacy Pattern with LoadingOverlay
+
+```typescript
+import React from 'react';
+import { Box } from '@mui/material';
+import { useQuery } from '@tanstack/react-query';
+import { LoadingOverlay } from '~components/LoadingOverlay';
+import { myFeatureApi } from '../api/myFeatureApi';
+
+export const LegacyComponent: React.FC<{ id: number }> = ({ id }) => {
+    const { data, isLoading, error } = useQuery({
+        queryKey: ['entity', id],
+        queryFn: () => myFeatureApi.getEntity(id),
+    });
+
+    return (
+        <LoadingOverlay loading={isLoading}>
+            <Box sx={{ p: 2 }}>
+                {error && <ErrorDisplay error={error} />}
+                {data && <Content data={data} />}
+            </Box>
+        </LoadingOverlay>
+    );
+};
+```
+
+### Example 3: Error Handling with Snackbar
+
+```typescript
+import React from 'react';
+import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { Button } from '@mui/material';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+import { myFeatureApi } from '../api/myFeatureApi';
+
+export const EntityEditor: React.FC<{ id: number }> = ({ id }) => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    const { data } = useSuspenseQuery({
+        queryKey: ['entity', id],
+        queryFn: () => myFeatureApi.getEntity(id),
+        onError: () => {
+            showError('Failed to load entity');
+        },
+    });
+
+    const updateMutation = useMutation({
+        mutationFn: (updates) => myFeatureApi.update(id, updates),
+
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: ['entity', id] });
+            showSuccess('Entity updated successfully');
+        },
+
+        onError: () => {
+            showError('Failed to update entity');
+        },
+    });
+
+    return (
+        <Button onClick={() => updateMutation.mutate({ name: 'New' })}>
+            Update
+        </Button>
+    );
+};
+```
+
+---
+
+## Loading State Anti-Patterns
+
+### ❌ What NOT to Do
+
+```typescript
+// ❌ NEVER - Early return
+if (isLoading) {
+    return <CircularProgress />;
+}
+
+// ❌ NEVER - Conditional rendering
+{isLoading ? <Spinner /> : <Content />}
+
+// ❌ NEVER - Layout changes
+if (isLoading) {
+    return (
+        <Box sx={{ height: 100 }}>
+            <Spinner />
+        </Box>
+    );
+}
+return (
+    <Box sx={{ height: 500 }}>  // Different height!
+        <Content />
+    </Box>
+);
+```
+
+### ✅ What TO Do
+
+```typescript
+// ✅ BEST - useSuspenseQuery + SuspenseLoader
+<SuspenseLoader>
+    <ComponentWithSuspenseQuery />
+</SuspenseLoader>
+
+// ✅ ACCEPTABLE - LoadingOverlay
+<LoadingOverlay loading={isLoading}>
+    <Content />
+</LoadingOverlay>
+
+// ✅ OK - Inline skeleton with same layout
+<Box sx={{ height: 500 }}>
+    {isLoading ? <Skeleton variant='rectangular' height='100%' /> : <Content />}
+</Box>
+```
+
+---
+
+## Skeleton Loading (Alternative)
+
+### MUI Skeleton Component
+
+```typescript
+import { Skeleton, Box } from '@mui/material';
+
+export const MyComponent: React.FC = () => {
+    const { data, isLoading } = useQuery({ ... });
+
+    return (
+        <Box sx={{ p: 2 }}>
+            {isLoading ? (
+                <>
+                    <Skeleton variant='text' width={200} height={40} />
+                    <Skeleton variant='rectangular' width='100%' height={200} />
+                    <Skeleton variant='text' width='100%' />
+                </>
+            ) : (
+                <>
+                    <Typography variant='h5'>{data.title}</Typography>
+                    <img src={data.image} />
+                    <Typography>{data.description}</Typography>
+                </>
+            )}
+        </Box>
+    );
+};
+```
+
+**Key**: Skeleton must have **same layout** as actual content (no shift)
+
+---
+
+## Summary
+
+**Loading States:**
+- ✅ **PREFERRED**: SuspenseLoader + useSuspenseQuery (modern pattern)
+- ✅ **ACCEPTABLE**: LoadingOverlay (legacy pattern)
+- ✅ **OK**: Skeleton with same layout
+- ❌ **NEVER**: Early returns or conditional layout
+
+**Error Handling:**
+- ✅ **ALWAYS**: useMuiSnackbar for user feedback
+- ❌ **NEVER**: react-toastify
+- ✅ Use onError callbacks in queries/mutations
+- ✅ Error boundaries for component-level errors
+
+**See Also:**
+- [component-patterns.md](component-patterns.md) - Suspense integration
 - [data-fetching.md](data-fetching.md) - useSuspenseQuery details