/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 |