Joy UI 是什么
Joy UI（@mui/joy）是 MUI 的替代性组件库，提供一种现代、简洁的设计语言，区别于 Google 的 Material Design。它从底层构建时就把 CSS 变量作为一等特性，并配有灵活的 variant 系统和比 Material UI 更简单的 API。
安装： npm install @mui/joy @emotion/react @emotion/styled
或
pnpm add @mui/joy @emotion/react @emotion/styled
Joy UI 沿用 MUI 的工程品质（无障碍、TypeScript、可组合性），但做出了不同的设计决策：默认使用 CSS 变量（非实验性、非可选）；variant 系统——每个组件都支持 solid、soft、outlined、plain；颜色系统——使用语义化颜色（primary、neutral、danger、success、warning）而非 primary/secondary；decoration levels——替代 Material UI 的 elevation，概念更灵活；现代美学——开箱即用的圆润、宽松、当代外观。
何时使用 Joy UI
- 应用不应看起来像 Material Design：Joy UI
- 希望无需实验性标志即可使用 CSS 变量：Joy UI
- 需要符合 Google Material Design 规范：Material UI
- 构建现代 SaaS 仪表盘：Joy UI
- 已有 Material UI 代码库：Material UI（或渐进迁移）
- 需要最大的组件目录：Material UI（目前组件更多）
- 希望零配置内置暗色模式：Joy UI
与 Material UI 的关键差异
Variant 系统：Material UI 仅在某些组件上使用 variant（如 Button 的 contained、outlined、text）。Joy UI 在所有组件上应用一致的 variant 系统：solid（填充背景，高强调，用于主要操作、选中状态）、soft（细微背景色调，用于次要操作、标签、徽章）、outlined（仅边框，用于三级操作、表单字段）、plain（无背景或边框，低强调、类文本操作）。
颜色系统：Material UI 为 primary、secondary、error、warning、info、success；Joy UI 为 primary、neutral、danger、success、warning。
组件命名差异：Paper 对应 Sheet（表面容器）；TextField 对应 Input / Textarea（分离组件，而非包装器）；AppBar 对应 Header（自定义，Joy UI 不提供 AppBar，使用 Sheet）；Snackbar 同名但 API 不同；Fab 无对应（使用 variant="solid" 的 IconButton）；Rating 无对应（Joy UI 尚未提供）；SpeedDial 无对应（尚未提供）。
Decoration Levels 与 Elevation：Material UI 使用 elevation={0..24} 控制 box-shadow 深度；Joy UI 使用 CSS 变量和 shadow 属性。
设置
使用 CssVarsProvider 的基础设置：CssVarsProvider 替代 Material UI 的 ThemeProvider，会自动将 CSS 变量注入 :root，支持明暗模式切换而无需重建主题，并支持运行时主题切换而无需 JavaScript 重新计算。
暗色模式切换：使用 useColorScheme 获取 mode 和 setMode，无需创建单独的明暗主题，CSS 变量会自动切换。
主题定制：使用 extendTheme 可配置 colorSchemes（light/dark 下的 palette）、fontFamily、typography、radius 以及 components 的 styleOverrides 和 defaultProps。在自定义组件中可通过 styled 访问 CSS 变量（如 theme.vars.radius.md、theme.vars.palette.background.surface、theme.vars.shadow.sm），也可直接使用 var(--joy-palette-background-surface)。自定义 token 可通过 extendTheme 添加，并在 TypeScript 中扩展 Palette 接口。
组件示例
Button：支持 variant、color、size（sm/md/lg）、startDecorator/endDecorator 图标、loading 状态（含 loadingPosition）、IconButton、ButtonGroup。
Input 与 Textarea：Input 支持 startDecorator/endDecorator；配合 FormControl、FormLabel、FormHelperText 使用，支持 error 状态；Textarea 支持 minRows/maxRows 自动调整大小。
Card（基于 Sheet）：包含 Card、CardContent、CardOverflow、CardActions、AspectRatio 等，可组合出产品卡片。
Typography：使用 level 而非 variant，级别包括 h1–h4、title-lg/md/sm、body-lg/md/sm/xs；支持 color、textColor 以及 startDecorator 内联图标。
Modal：包含 Modal、ModalDialog、ModalClose、DialogTitle、DialogContent、DialogActions；ModalDialog 支持 layout（'center' | 'fullscreen'），可在移动端实现全屏或底部抽屉式布局。
Autocomplete：支持 options、getOptionLabel、isOptionEqualToValue、renderOption，可配合 AutocompleteOption、ListItemDecorator、ListItemContent 自定义选项渲染。
同时使用 Joy UI 与 Material UI
可以在同一应用中同时使用 Joy UI 和 Material UI，适用于迁移期间或需要仅存在于某一库中的组件时。设置双 Provider：使用 Material 的 ThemeProvider（配合 THEME_ID）包裹 Joy 的 CssVarsProvider。为避免 CSS 变量冲突，Joy UI 变量使用 --joy- 前缀（可通过 cssVarPrefix 显式指定），Material UI 变量使用 --mui- 前缀，二者不冲突。
适用场景与限制
适用场景：不希望应用呈现 Material Design 风格、希望无需实验性标志使用 CSS 变量、构建现代 SaaS 仪表盘、需要零配置暗色模式。限制：若需符合 Google Material Design 规范、已有 Material UI 代码库或需要最大组件目录，应选择 Material UI；Joy UI 目前不提供 AppBar、Fab、Rating、SpeedDial 等组件。