dev-backbone-template/SKILLS/56-ui-material-ui.md

# Material UI (MUI) Design System

Use this skill for any React/Next “portal/admin/dashboard” UI so you stay consistent and avoid random component soup.

## Standard choice
- Preferred UI library: **MUI (Material UI)**.
- Prefer MUI components over ad-hoc HTML/CSS unless there’s a good reason.
- One design system per repo (do not mix Chakra/Ant/Bootstrap/etc.).

## Setup (Next.js/React)
- Install: `@mui/material @emotion/react @emotion/styled`
- If using icons: `@mui/icons-material`
- If using data grid: `@mui/x-data-grid` (or pro if licensed)

## Theming rules
- Define a single theme (typography, spacing, palette) and reuse everywhere.
- Use semantic colors (primary/secondary/error/warning/success/info), not hard-coded hex everywhere.
- Prefer MUI’s `sx` for small styling; use `styled()` for reusable components.

## “Portal” patterns (modals, popovers, menus)
- Use MUI Dialog/Modal/Popover/Menu components instead of DIY portals.
- Accessibility requirements:
  - Focus is trapped in Dialog/Modal.
  - Escape closes modal unless explicitly prevented.
  - All inputs have labels; buttons have clear text/aria-labels.
  - Keyboard navigation works end-to-end.

## Layout conventions (for portals)
- Use: AppBar + Drawer (or NavigationRail equivalent) + main content.
- Keep pages as composition of small components: Page → Sections → Widgets.
- Keep forms consistent: FormControl + helper text + validation messages.

## Performance hygiene
- Avoid re-render storms: memoize heavy lists; use virtualization for large tables (DataGrid).
- Prefer server pagination for huge datasets.

## PR review checklist
- Theme is used (no random styling).
- Components are MUI where reasonable.
- Modal/popover accessibility is correct.
- No mixed UI libraries.