Mui Styling

---
name: mui-styling
description: "Material-UI (MUI) styling standards: sx-prop priority, theme tokens, spacing scale, responsive design, and accessibility. TRIGGER when: styling MUI components, defining theme tokens, or building responsive layouts. SKIP: component logic and hooks (use react-patterns); cross-stack UX/design decisions (use ui-ux-pro-max)."
context: fork
agent: general-purpose
---

# MUI Styling Skill

Material-UI styling standards and best practices.

## When to Apply

- Creating styled components
- Implementing responsive design
- Theme customization
- UI consistency review

---

## Styling Approach Priority

| Priority | Approach | Use When |
|----------|----------|----------|
| 1st | `sx` prop | Most styling needs |
| 2nd | `styled()` API | Reusable styled components |
| 3rd | Theme overrides | Global component defaults |
| Avoid | Inline CSS / CSS files | Never use in MUI projects |

---

## Spacing System

### Spacing Scale
| Value | Pixels | Usage |
|-------|--------|-------|
| 0.5 | 4px | Tight spacing |
| 1 | 8px | Default small |
| 2 | 16px | Default medium |
| 3 | 24px | Section spacing |
| 4 | 32px | Large spacing |

### Spacing Props
| Prop | CSS Property |
|------|--------------|
| `m` | margin |
| `p` | padding |
| `mt`, `mr`, `mb`, `ml` | margin-top/right/bottom/left |
| `pt`, `pr`, `pb`, `pl` | padding-top/right/bottom/left |
| `mx`, `my` | margin x/y axis |
| `px`, `py` | padding x/y axis |
| `gap` | flex/grid gap |

---

## Color System

### Theme Colors
| Category | Values |
|----------|--------|
| Primary | `primary.main`, `primary.light`, `primary.dark`, `primary.contrastText` |
| Secondary | `secondary.main`, `secondary.light`, `secondary.dark` |
| Status | `error.main`, `warning.main`, `info.main`, `success.main` |
| Grey | `grey.100` through `grey.900` |
| Background | `background.default`, `background.paper` |
| Text | `text.primary`, `text.secondary`, `text.disabled` |

### Color Usage Guidelines
| Use Case | Color |
|----------|-------|
| Primary actions | `primary.main` |
| Secondary actions | `secondary.main` |
| Error states | `error.main` |
| Success feedback | `success.main` |
| Backgrounds | `background.paper` or `background.default` |
| Body text | `text.primary` |
| Helper text | `text.secondary` |

---

## Responsive Design

### Breakpoints
| Key | Min Width | Target |
|-----|-----------|--------|
| `xs` | 0px | Mobile phones |
| `sm` | 600px | Tablets portrait |
| `md` | 900px | Tablets landscape |
| `lg` | 1200px | Desktops |
| `xl` | 1536px | Large screens |

### Responsive Syntax
| Syntax | Description |
|--------|-------------|
| `{ xs: value }` | Mobile first, applies to xs and up |
| `{ sm: value }` | Applies to sm and up |
| Object syntax | `{ xs: '100%', sm: 400, md: 600 }` |

### Responsive Guidelines
| Guideline | Description |
|-----------|-------------|
| Mobile first | Start with `xs`, override for larger |
| Test all breakpoints | Verify layout at each breakpoint |
| Use relative units | Prefer `%`, `vh`, `vw` over fixed `px` |
| Hide/show elements | Use `display: { xs: 'none', md: 'block' }` |

---

## Layout Components

### Component Selection
| Component | Use When |
|-----------|----------|
| `Box` | Generic container, flexbox layouts |
| `Stack` | Vertical/horizontal lists with spacing |
| `Grid` | 12-column grid layouts |
| `Container` | Centered max-width wrapper |

### Flexbox with Box
| Property | Values |
|----------|--------|
| `display` | `'flex'`, `'inline-flex'` |
| `flexDirection` | `'row'`, `'column'` |
| `justifyContent` | `'flex-start'`, `'center'`, `'space-between'` |
| `alignItems` | `'flex-start'`, `'center'`, `'stretch'` |
| `gap` | Spacing value (1, 2, 3...) |

### Grid System
| Prop | Description |
|------|-------------|
| `container` | Defines grid container |
| `item` | Defines grid item |
| `xs`, `sm`, `md`, `lg` | Columns at breakpoint (1-12) |
| `spacing` | Gap between items |

---

## Typography Standards

### Variant Usage
| Variant | Use For |
|---------|---------|
| `h1` - `h6` | Headings (use semantic hierarchy) |
| `body1` | Primary body text |
| `body2` | Secondary body text |
| `caption` | Small helper text |
| `button` | Button text |

### Typography Guidelines
| Guideline | Description |
|-----------|-------------|
| Semantic hierarchy | h1 > h2 > h3 (don't skip levels) |
| Color for emphasis | Use `text.secondary` for less important |
| Consistent variants | Same content type = same variant |

---

## Component Styling Standards

### Button Styling
| Variant | Use When |
|---------|----------|
| `contained` | Primary actions |
| `outlined` | Secondary actions |
| `text` | Tertiary actions, links |

### Card Styling
| Element | Standard |
|---------|----------|
| Padding | `p: 2` or `p: 3` |
| Border radius | Use theme default |
| Shadow | Use theme shadows (1-24) |

### Form Styling
| Element | Standard |
|---------|----------|
| TextField | `fullWidth` for forms |
| Spacing | `Stack spacing={2}` between fields |
| Labels | Always provide `label` prop |

---

## Anti-Patterns

| Avoid | Use Instead |
|-------|-------------|
| Inline CSS objects | `sx` prop with theme values |
| `!important` | Increase specificity via `sx` |
| Fixed pixel values | `theme.spacing()` values |
| Hardcoded colors | `theme.palette` colors |
| CSS classes | `sx` prop or `styled()` |
| External CSS files | MUI styling system |

---

## Performance Guidelines

### DO
- Use `sx` prop for one-off styles
- Use `styled()` for reusable styled components
- Leverage theme values for consistency
- Use responsive object syntax

### DON'T
- Create inline style objects (new reference each render)
- Override theme styles unnecessarily
- Use CSS-in-JS libraries alongside MUI
- Nest `sx` props deeply

---

## Accessibility Standards

| Standard | Implementation |
|----------|----------------|
| Color contrast | Use theme colors (WCAG compliant) |
| Focus indicators | Don't remove, customize if needed |
| Touch targets | Minimum 44x44px for buttons |
| Semantic HTML | Use correct MUI component for purpose |

---

## Code Review Checklist

- [ ] Uses `sx` prop or `styled()`, not inline CSS
- [ ] Colors from theme palette
- [ ] Spacing from theme scale
- [ ] Responsive breakpoints applied
- [ ] No hardcoded pixel values
- [ ] Typography variants used correctly
- [ ] Accessibility standards met

---

## Example: Centralized Theme Module (illustrative)

> Illustrative — this is one team's convention shown as a concrete example.
> Substitute your project's own theme tokens, palette, and component-style
> helpers. The *pattern* (centralize colors/shadows/component styles in a theme
> module and reference tokens instead of raw values) is the reusable part; the
> specific neon-cyberpunk values below are just an example.

### Theme: Neon Cyberpunk (Dark Mode Only)

Font: `"Ubuntu"` (UI), `"Ubuntu Mono"` (code/terminal). Theme at `<your-theme-module>/index.ts`.

### Color Palette (`<your-theme-module>/colors.ts`)

```typescript
colors.background.primary   // '#0D0D0D' - page background
colors.background.secondary // '#121212' - AppBar, Drawer
colors.background.surface   // '#1E1E1E' - cards, paper
colors.background.elevated  // '#252525' - hover states
colors.background.input     // '#1A1A1A' - text fields

colors.neon.cyan     // '#00FFFF' - primary actions, focus rings
colors.neon.lime     // '#39FF14' - secondary actions, success
colors.neon.red      // '#FF1744' - errors, danger
colors.neon.yellow   // '#FFEA00' - warnings
colors.neon.orange   // '#FF9100' - cancelled status
colors.neon.purple   // '#E040FB' - accents
colors.neon.green    // '#00E676' - success variant

colors.text.primary   // '#F0F0F0'
colors.text.secondary // '#888888'
colors.text.muted     // '#666666'
colors.border.primary // '#2A2A2A'
```

### Alpha Helpers (`<your-theme-module>/colors.ts`)
```typescript
alpha.cyan(0.08)   // hover backgrounds
alpha.cyan(0.16)   // selected backgrounds
alpha.red(0.1)     // error backgrounds
alpha.lime(0.1)    // success backgrounds
```

### Glow Effects (`<your-theme-module>/glows.ts`)
```typescript
glows.cyan         // '0 0 15px rgba(0,255,255,0.4)' - standard
glows.cyanLight    // '0 0 10px rgba(0,255,255,0.2)' - subtle (buttons, inputs)
glows.cyanStrong   // dual shadow for hover emphasis
glows.terminalInset// inset shadow for terminal containers
statusGlows[status]// per-TaskStatus glow effects
```

### componentStyles (`<your-theme-module>/componentStyles.ts`)

Pre-built `SxProps<Theme>` objects. Apply via spread in `sx` prop:
```tsx
import { componentStyles } from '../theme';

<Button sx={componentStyles.primaryButton}>Submit</Button>
<Button sx={componentStyles.dangerButton}>Delete</Button>
<IconButton sx={componentStyles.iconButtonDanger}>...</IconButton>
<TextField sx={componentStyles.textField} />
<Box sx={componentStyles.terminal}>output here</Box>
<Box sx={componentStyles.statusBadge('running')}>Running</Box>
<Alert sx={componentStyles.alertError}>Error msg</Alert>
<Typography sx={componentStyles.sectionHeader}>SECTION</Typography>
```

Available styles: `primaryButton`, `secondaryButton`, `dangerButton`, `ghostButton`, `iconButton`, `iconButtonDanger`, `iconButtonSuccess`, `iconButtonPrimary`, `selectorButtonSidebar`, `selectorButtonHeader`, `textField`, `textFieldSmall`, `dialog`, `terminal`, `statusBadge(status)`, `alertError`, `alertSuccess`, `dangerButtonContained`, `sectionHeader`, `menuHeader`, `scrollbar`, `alertBackendOffline`, `resizeHandle(isResizing)`, `liveBadge`, `collapsibleSection(expanded)`, `pulsingDot`.

### Animations (global keyframes in theme)
- `pulse` - opacity fade for running indicators
- `neonPulse` - scale+opacity for status dots
- `neonBlink` - cursor blink
- `liveGlow` - streaming indicator glow
- `subtleBgPulse` - running task row background

Usage: `animation: 'liveGlow 2s ease-in-out infinite'`

### Example Anti-Patterns (for the theme module above)
- Do NOT use raw hex colors - use `colors.*` tokens
- Do NOT write inline `boxShadow` - use `glows.*` presets
- Do NOT create new button styles - use `componentStyles.*Button`
- Do NOT hardcode font families - use `fonts.mono` / `fonts.monoExtended`