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
Project Theme Reference
Theme: Neon Cyberpunk (Dark Mode Only)
Font: "Ubuntu" (UI), "Ubuntu Mono" (code/terminal). Theme at src/theme/index.ts.
Color Palette (src/theme/colors.ts)
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 (src/theme/colors.ts)
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 (src/theme/glows.ts)
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 (src/theme/componentStyles.ts)
Pre-built SxProps<Theme> objects. Apply via spread in sx prop:
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'
Project Anti-Patterns
- 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