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)

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)

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)

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:

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