# Styling Guide

Modern styling patterns for using MUI v7 sx prop, inline styles, and theme integration.

---

## Inline vs Separate Styles

### Decision Threshold

**<100 lines: Inline styles at top of component**

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

const componentStyles: Record<string, SxProps<Theme>> = {
    container: {
        p: 2,
        display: 'flex',
        flexDirection: 'column',
    },
    header: {
        mb: 2,
        borderBottom: '1px solid',
        borderColor: 'divider',
    },
    // ... more styles
};

export const MyComponent: React.FC = () => {
    return (
        <Box sx={componentStyles.container}>
            <Box sx={componentStyles.header}>
                <h2>Title</h2>
            </Box>
        </Box>
    );
};
```

**>100 lines: Separate `.styles.ts` file**

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

export const componentStyles: Record<string, SxProps<Theme>> = {
    container: { ... },
    header: { ... },
    // ... 100+ lines of styles
};

// MyComponent.tsx
import { componentStyles } from './MyComponent.styles';

export const MyComponent: React.FC = () => {
    return <Box sx={componentStyles.container}>...</Box>;
};
```

### Real Example: UnifiedForm.tsx

**Lines 48-126**: 78 lines of inline styles (acceptable)

```typescript
const formStyles: Record<string, SxProps<Theme>> = {
  gridContainer: {
    height: "100%",
    maxHeight: "calc(100vh - 220px)",
  },
  section: {
    height: "100%",
    maxHeight: "calc(100vh - 220px)",
    overflow: "auto",
    p: 4,
  },
  // ... 15 more style objects
};
```

**Guideline**: User is comfortable with ~80 lines inline. Use your judgment around 100 lines.

---

## sx Prop Patterns

### Basic Usage

```typescript
<Box sx={{ p: 2, mb: 3, display: 'flex' }}>
    Content
</Box>
```

### With Theme Access

```typescript
<Box
    sx={{
        p: 2,
        backgroundColor: (theme) => theme.palette.primary.main,
        color: (theme) => theme.palette.primary.contrastText,
        borderRadius: (theme) => theme.shape.borderRadius,
    }}
>
    Themed Box
</Box>
```

### Responsive Styles

```typescript
<Box
    sx={{
        p: { xs: 1, sm: 2, md: 3 },
        width: { xs: '100%', md: '50%' },
        flexDirection: { xs: 'column', md: 'row' },
    }}
>
    Responsive Layout
</Box>
```

### Pseudo-Selectors

```typescript
<Box
    sx={{
        p: 2,
        '&:hover': {
            backgroundColor: 'rgba(0,0,0,0.05)',
        },
        '&:active': {
            backgroundColor: 'rgba(0,0,0,0.1)',
        },
        '& .child-class': {
            color: 'primary.main',
        },
    }}
>
    Interactive Box
</Box>
```

---

## MUI v7 Patterns

### Grid Component (v7 Syntax)

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

// ✅ CORRECT - v7 syntax with size prop
<Grid container spacing={2}>
    <Grid size={{ xs: 12, md: 6 }}>
        Left Column
    </Grid>
    <Grid size={{ xs: 12, md: 6 }}>
        Right Column
    </Grid>
</Grid>

// ❌ WRONG - Old v6 syntax
<Grid container spacing={2}>
    <Grid xs={12} md={6}>  {/* OLD - Don't use */}
        Content
    </Grid>
</Grid>
```

**Key Change**: `size={{ xs: 12, md: 6 }}` instead of `xs={12} md={6}`

### Responsive Grid

```typescript
<Grid container spacing={3}>
    <Grid size={{ xs: 12, sm: 6, md: 4, lg: 3 }}>
        Responsive Column
    </Grid>
</Grid>
```

### Nested Grids

```typescript
<Grid container spacing={2}>
    <Grid size={{ xs: 12, md: 8 }}>
        <Grid container spacing={1}>
            <Grid size={{ xs: 12, sm: 6 }}>
                Nested 1
            </Grid>
            <Grid size={{ xs: 12, sm: 6 }}>
                Nested 2
            </Grid>
        </Grid>
    </Grid>

    <Grid size={{ xs: 12, md: 4 }}>
        Sidebar
    </Grid>
</Grid>
```

---

## Type-Safe Styles

### Style Object Type

```typescript
import type { SxProps, Theme } from "@mui/material";

// Type-safe styles
const styles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    // Autocomplete and type checking work here
  },
};

// Or individual style
const containerStyle: SxProps<Theme> = {
  p: 2,
  display: "flex",
};
```

### Theme-Aware Styles

```typescript
const styles: Record<string, SxProps<Theme>> = {
  primary: {
    color: (theme) => theme.palette.primary.main,
    backgroundColor: (theme) => theme.palette.primary.light,
    "&:hover": {
      backgroundColor: (theme) => theme.palette.primary.dark,
    },
  },
  customSpacing: {
    padding: (theme) => theme.spacing(2),
    margin: (theme) => theme.spacing(1, 2), // top/bottom: 1, left/right: 2
  },
};
```

---

## What NOT to Use

### ❌ makeStyles (MUI v4 pattern)

```typescript
// ❌ AVOID - Old Material-UI v4 pattern
import { makeStyles } from "@mui/styles";

const useStyles = makeStyles((theme) => ({
  root: {
    padding: theme.spacing(2),
  },
}));
```

**Why avoid**: Deprecated, v7 doesn't support it well

### ❌ styled() Components

```typescript
// ❌ AVOID - styled-components pattern
import { styled } from "@mui/material/styles";

const StyledBox = styled(Box)(({ theme }) => ({
  padding: theme.spacing(2),
}));
```

**Why avoid**: sx prop is more flexible and doesn't create new components

### ✅ Use sx Prop Instead

```typescript
// ✅ PREFERRED
<Box
    sx={{
        p: 2,
        backgroundColor: 'primary.main',
    }}
>
    Content
</Box>
```

---

## Code Style Standards

### Indentation

**4 spaces** (not 2, not tabs)

```typescript
const styles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    display: "flex",
    flexDirection: "column",
  },
};
```

### Quotes

**Single quotes** for strings (project standard)

```typescript
// ✅ CORRECT
const color = "primary.main";
import { Box } from "@mui/material";

// ❌ WRONG
const color = "primary.main";
import { Box } from "@mui/material";
```

### Trailing Commas

**Always use trailing commas** in objects and arrays

```typescript
// ✅ CORRECT
const styles = {
  container: { p: 2 },
  header: { mb: 1 }, // Trailing comma
};

const items = [
  "item1",
  "item2", // Trailing comma
];

// ❌ WRONG - No trailing comma
const styles = {
  container: { p: 2 },
  header: { mb: 1 }, // Missing comma
};
```

---

## Common Style Patterns

### Flexbox Layout

```typescript
const styles = {
  flexRow: {
    display: "flex",
    flexDirection: "row",
    alignItems: "center",
    gap: 2,
  },
  flexColumn: {
    display: "flex",
    flexDirection: "column",
    gap: 1,
  },
  spaceBetween: {
    display: "flex",
    justifyContent: "space-between",
    alignItems: "center",
  },
};
```

### Spacing

```typescript
// Padding
p: 2           // All sides
px: 2          // Horizontal (left + right)
py: 2          // Vertical (top + bottom)
pt: 2, pr: 1   // Specific sides

// Margin
m: 2, mx: 2, my: 2, mt: 2, mr: 1

// Units: 1 = 8px (theme.spacing(1))
p: 2  // = 16px
p: 0.5  // = 4px
```

### Positioning

```typescript
const styles = {
  relative: {
    position: "relative",
  },
  absolute: {
    position: "absolute",
    top: 0,
    right: 0,
  },
  sticky: {
    position: "sticky",
    top: 0,
    zIndex: 1000,
  },
};
```

---

## Summary

**Styling Checklist:**

- ✅ Use `sx` prop for MUI styling
- ✅ Type-safe with `SxProps<Theme>`
- ✅ <100 lines: inline; >100 lines: separate file
- ✅ MUI v7 Grid: `size={{ xs: 12 }}`
- ✅ 4 space indentation
- ✅ Single quotes
- ✅ Trailing commas
- ❌ No makeStyles or styled()

**See Also:**

- [component-patterns.md](component-patterns.md) - Component structure
- [complete-examples.md](complete-examples.md) - Full styling examples