Mui Styling

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 /index.ts.

Color Palette (/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 (/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 (/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 (/componentStyles.ts)

Pre-built SxProps objects. Apply via spread in sx prop:

import { componentStyles } from '../theme';

Submit
Delete
...

output here
Running
Error msg
SECTION

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: komluk
• Source: komluk/scaffolding
• License: MIT

Install and usage instructions live in the source repository linked above.