name: material-design description: | Implement and review Material Design 3 (Material You) interfaces. Use when: (1) Building UI with MUI, Tailwind, or vanilla CSS following M3 guidelines (2) Reviewing code for M3 compliance (color, typography, shape, motion, elevation) (3) Creating dynamic color themes from brand colors (4) Implementing M3 components (buttons, cards, dialogs, navigation, etc.) (5) Auditing accessibility and contrast ratios Triggers: "Material Design", "M3", "Material You", "MUI", "dynamic color", "MD3 compliance"

Material Design 3 Implementation Guide

Quick Reference

Topic	Reference	When to read
Color system	color-system.md	Theme creation, dynamic color, dark mode
Typography	typography.md	Font scales, responsive text
Components	components.md	Specific component implementation
Layout	layout.md	Spacing, grids, responsive breakpoints
Motion	motion.md	Animations, transitions, easing
Dynamic color theme	example-dynamic-color-theme.ts	MUI v6+ theme setup with seed color
MUI patterns	example-mui-patterns.ts	Props interface, theme extension, breakpoints
CSS patterns	example-css-patterns.css	Surface tint, state layers

Core Principles

1. Dynamic Color (Material You)

Generate color scheme from a single seed color using HCT color space. See example-dynamic-color-theme.ts for MUI v6+ implementation.

Key color roles:

Primary: Key actions, active states
Secondary: Less prominent elements
Tertiary: Accents, contrasting elements
Surface: Backgrounds at different elevations
Error/Warning/Success: Semantic feedback

2. Elevation & Surface

M3 uses tonal elevation (color tint) instead of shadows. See example-css-patterns.css for CSS implementation.

Elevation	Use case	Surface tint
0	Background	None
1	Cards, raised buttons	+5% primary
2	Menus, dialogs	+8% primary
3	Navigation drawer	+11% primary
4	App bar	+12% primary
5	FAB	+14% primary

3. Typography Scale

M3 defines 15 text styles across 5 categories:

Category	Sizes	Use
Display	Large/Medium/Small	Hero text, splash
Headline	Large/Medium/Small	Section headers
Title	Large/Medium/Small	Card titles, dialogs
Body	Large/Medium/Small	Paragraph text
Label	Large/Medium/Small	Buttons, captions

See typography.md for exact specs.

4. Shape System

M3 corner radii by component size:

Size	Radius	Components
Extra Small	4px	Tooltips, snackbars
Small	8px	Chips, small cards
Medium	12px	Cards, dialogs
Large	16px	Large cards, sheets
Extra Large	28px	FAB
Full	50%	Circular buttons

5. Motion

Standard easing curves:

Emphasized: cubic-bezier(0.2, 0, 0, 1) — Primary interactions
Emphasized Decelerate: cubic-bezier(0.05, 0.7, 0.1, 1) — Enter
Emphasized Accelerate: cubic-bezier(0.3, 0, 0.8, 0.15) — Exit
Standard: cubic-bezier(0.2, 0, 0, 1) — General
Standard Decelerate: cubic-bezier(0, 0, 0, 1) — Fade in
Standard Accelerate: cubic-bezier(0.3, 0, 1, 1) — Fade out

Duration guidelines:

Micro (50-100ms): Button press feedback
Short (100-200ms): Tooltips, small expansions
Medium (200-400ms): Page transitions, modals
Long (400-700ms): Complex animations

MUI Implementation Patterns

Component Structure (from MUI codebase)

components/Button/
├── Button.tsx           # Implementation
├── Button.types.ts      # TypeScript declarations
├── Button.test.tsx      # Unit tests
├── buttonClasses.ts     # CSS class names
└── index.ts             # Public exports

Props Interface & Theme Extension

See example-mui-patterns.ts for:

Props interface convention (using interface for component props)
Theme type extension for M3 palette (tertiary, surfaceVariant)
M3 canonical responsive breakpoints

Review Checklist

When reviewing M3 compliance:

Color
- Uses semantic color roles (primary/secondary/tertiary), not arbitrary hex
- Dark mode inverts correctly (light surfaces → dark, dark text → light)
- Contrast ratios meet WCAG AA (4.5:1 text, 3:1 UI)
Typography
- Uses M3 type scale (display/headline/title/body/label)
- Responsive scaling for large displays
- Line height follows M3 specs
**Spa