用途
该技能用于在 MUI v6 及以上版本中采用 CSS 变量驱动的主题方案，并可选地接入 Pigment CSS 零运行时样式引擎。它解决的核心问题是：传统 ThemeProvider 把主题值放在 JS 上下文中，切换明暗模式会触发整棵 React 树重渲染；而 CssVarsProvider 把主题值输出为根元素上的 CSS 自定义属性，配色切换只发生在 CSS 层。
主要能力
CssVarsProvider 与 extendTheme
CssVarsProvider 在需要基于 CSS 变量的主题时替代 ThemeProvider。extendTheme() 生成可感知 CSS 变量的主题对象，接受 colorSchemes 在单个对象中定义 light 与 dark 调色板，并自动生成 CSS 自定义属性。与 createTheme() 的差异包括：主题值是否进入 CSS、明暗切换是否重渲染、SSR 防闪烁是否内置、主题访问方式（theme.vars.palette.primary.main 或 var(--mui-palette-primary-main)）、以及多配色方案的组织方式。
colorSchemes 配置
colorSchemes 取代 palette.mode 的写法，在一个对象中定义全部方案。除 light/dark 外可定义额外方案（如 highContrast），第一个键被视为默认方案。defaultMode 支持 'light'、'dark'、'system'（跟随系统偏好）。
SSR 防闪烁
getInitColorSchemeScript() 注入阻塞式 script，在首次绘制前读取 localStorage 或系统偏好并设置 data-* 属性，避免 SSR 应用先显示默认（浅色）主题再被水合修正。可配置 defaultMode、modeStorageKey、colorSchemeStorageKey、attribute、colorSchemeNode。文档给出 Next.js App Router（layout.tsx）与 Pages Router（_document.tsx）的接入示例。
运行时配色切换
useColorScheme() 返回 mode 与 setMode。setMode 更新根 HTML 元素上的 data-* 属性并写入 localStorage，CSS 变量通过属性选择器响应，因此只有读取 mode 的组件会重渲染，实际样式变化是纯 CSS。文档给出二态切换与 light/dark/system 三态切换示例，并提示 mode 为空时返回 null 以避免 SSR 水合不一致。
访问 CSS 变量
可在 sx 属性中直接使用 var(--mui-palette-primary-main)，或使用回调形式的 theme.vars.palette.primary.main；在 styled() 组件中使用 theme.vars.；在普通 CSS / CSS Modules 中直接引用 var(--mui-)。通过 cssVarPrefix 可自定义前缀（如 app，变量变为 var(--app-palette-primary-main)）。
主题令牌到 CSS 变量的映射
文档给出映射表，例如 theme.palette.primary.main → --mui-palette-primary-main、theme.shape.borderRadius → --mui-shape-borderRadius、theme.shadows[4] → --mui-shadows-4；theme.spacing(2) 默认不是 CSS 变量而是计算值。使用 CssVarsProvider 时应使用 theme.vars 而非直接访问 theme，否则会在构建期解析、水合时不一致。还可通过模块声明扩展 CssVarsThemeOptions 与 Theme，添加自定义令牌（如 headerHeight、sidebarWidth、contentMaxWidth），并作为 CSS 变量访问。
Pigment CSS
Pigment CSS 是 MUI 的编译期 CSS 提取引擎，替代 Emotion 作为样式运行时：所有 styled() 与 css() 调用在构建期求值并提取为静态 CSS 文件，不向浏览器发送 JS 样式运行时。文档给出 Next.js App Router（安装 @pigment-css/react 与 @pigment-css/nextjs-plugin，配置 withPigment）与 Vite（安装 @pigment-css/vite-plugin，配置 pigment 插件）的接入方式，以及 css()、styled() 与 variants 的用法示例。
适用场景
使用 extendTheme + CssVarsProvider 的场景：需要 SSR 且不希望出现错误主题闪烁；希望仅靠 CSS 切换暗色模式、不触发重渲染；在非 React 环境中嵌入 MUI 组件；希望在普通 CSS 文件中引用主题令牌；使用 MUI v6+。
使用 createTheme + ThemeProvider 的场景：从 MUI v4/v5 迁移且尚未准备切换；依赖 ThemeProvider 上下文的第三方库；单一配色方案且不需要 SSR。
使用 Pigment CSS 的场景：服务端渲染较重的应用（Next.js App Router、RSC）；对性能敏感、希望消除样式运行时以减小 JS 包体；React Server Components（Emotion 需要客户端边界，Pigment CSS 不需要）；大型设计系统，静态提取有利于缓存。
限制
Pigment CSS 不适合高度动态、依赖运行时状态的样式；不适合深度使用 Emotion API（keyframes、Global、css prop）的项目；面向 MUI v6+，不适用于需要 MUI v5 兼容的项目。资料在“Limitations and gotchas”处截断，关于 Pigment CSS 动态运行时样式的完整限制说明暂未提供。