Pigment CSS

MUI 团队推进的零运行时 CSS-in-JS 方案，旨在替代 Emotion 成为 Material UI 的下一代样式引擎。

技术简介说明

Pigment CSS 是由 MUI（原 Material-UI）团队开发的零运行时 CSS-in-JS 方案。它的核心目标是将 MUI 从运行时 CSS-in-JS（Emotion）迁移到构建时 CSS 提取方案，从而消除运行时样式引擎的性能开销，同时保持与 Material Design 的深度集成。Pigment CSS 基于 WyW-in-JS（Whatever-you-want-in-JS，由 Callstack 团队维护的 Linaria 底层引擎）构建，在构建阶段通过 Babel/SWC 插件将 styled、css、sx 等 API 调用转换为静态 CSS 文件。

Pigment CSS 的设计哲学是"无痛迁移"——为现有 MUI/Emotion 用户提供一条渐进式迁移路径，保持相似的 API 体验（styled、sx prop）但消除运行时开销。它完全兼容 React Server Components（RSC），这是 Emotion 无法做到的。通过 extendTheme 工具，Pigment CSS 将主题值编译为 CSS 变量，运行时通过 CSS 切换主题而非 JavaScript 重新计算。

然而，截至 2026 年初，MUI 官方博客明确表示 Pigment CSS "仍处于 alpha 阶段且目前已暂停开发"。虽然项目概念（零运行时 + RSC 兼容）被认为是正确的方向，但底层技术挑战导致核心团队暂停了推进。MUI v7 仍然使用 Emotion 作为默认样式引擎，Pigment CSS 的未来路线图存在不确定性。

基本信息

• 官网：https://mui.com/material-ui/experimental-api/pigment-css/ （无独立官网，作为 MUI Material 文档下的 experimental API 章节存在）
• GitHub：https://github.com/mui/pigment-css （⭐ ~1,100）
• License：MIT
• 最新版本：v0.0.31（@pigment-css/react，2026-05-22）；@mui/material-pigment-css v9.1.1
• 主要维护者/公司：MUI 团队（Olivier Tassinari 为核心人物）；MUI 整体生态每周 npm 下载量 670 万+

快速上手

安装

Next.js 项目：

# 安装 Pigment CSS 核心和 Next.js 插件
npm install @pigment-css/react
npm install --save-dev @pigment-css/nextjs-plugin
 
# 安装 MUI Material 的 Pigment CSS 包装层（可选）
npm install @mui/material-pigment-css

Vite 项目：

# 安装 Pigment CSS 核心和 Vite 插件
npm install @pigment-css/react
npm install --save-dev @pigment-css/vite-plugin

基础配置

Next.js 配置（next.config.js）：

const { withPigment } = require('@pigment-css/nextjs-plugin')
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
}
 
module.exports = withPigment(nextConfig, {
  // Pigment CSS 选项
})

Vite 配置（vite.config.ts）：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import pigmentCSS from '@pigment-css/vite-plugin'
 
export default defineConfig({
  plugins: [react(), pigmentCSS()],
})

主题配置（theme.ts）：

import { extendTheme } from '@pigment-css/react'
 
export const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: { main: '#007bff' },
        secondary: { main: '#6c757d' },
        text: { primary: '#333333' },
        background: { default: '#ffffff' },
      },
    },
    dark: {
      palette: {
        primary: { main: '#3b82f6' },
        secondary: { main: '#9ca3af' },
        text: { primary: '#f3f4f6' },
        background: { default: '#1f2937' },
      },
    },
  },
  typography: {
    fontFamily: '"Inter", sans-serif',
    h1: { fontSize: '2rem', fontWeight: 700 },
    body1: { fontSize: '1rem' },
  },
  shape: {
    borderRadius: 8,
  },
})

最小示例

import { styled, css } from '@pigment-css/react'
 
// 使用 styled API（与 Emotion/MUI 风格一致）
const Card = styled('div')({
  padding: '16px',
  borderRadius: '8px',
  boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
  backgroundColor: theme.vars.palette.background.default,
})
 
const Title = styled('h1')({
  fontSize: '1.5rem',
  fontWeight: 'bold',
  color: theme.vars.palette.text.primary,
})
 
// 使用 variants（类似 Stitches）
const Button = styled('button', {
  base: {
    padding: '8px 16px',
    borderRadius: '4px',
    border: 'none',
    cursor: 'pointer',
  },
  variants: {
    intent: {
      primary: { backgroundColor: '#007bff', color: 'white' },
      secondary: { backgroundColor: '#6c757d', color: 'white' },
    },
    size: {
      small: { fontSize: '12px', padding: '4px 8px' },
      medium: { fontSize: '14px', padding: '8px 16px' },
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'medium',
  },
})
 
function App() {
  return (
    <Card>
      <Title>Hello Pigment CSS</Title>
      <Button intent="primary" size="medium">点击我</Button>
    </Card>
  )
}

核心概念与架构

工作原理

Pigment CSS 基于 WyW-in-JS（Linaria 底层引擎）实现零运行时 CSS 提取：

┌────────────────────┐     ┌──────────────────────┐     ┌──────────────┐
│  React 组件代码     │ ──▶ │  WyW-in-JS 编译器    │ ──▶ │  静态 CSS    │
│  styled/css/sx     │     │  (Babel/SWC 插件)    │     │  文件输出    │
└────────────────────┘     └──────────────────────┘     └──────────────┘
         │                            │
         ▼                            ▼
   导出 className 引用          生成独立 CSS 文件
   (如 "pigment-xxxx")         + CSS 变量主题

1. 编译期分析：基于 WyW-in-JS 在构建阶段通过 Babel/SWC 插件分析源码
2. 静态抽取：将 styled、css、sx 等 API 调用转换为静态 CSS
3. 输出分离：生成独立的 CSS 文件，JS 中仅保留 className 引用
4. CSS 变量注入：主题值被编译为 CSS 变量（theme.vars.*），运行时通过 CSS 切换主题

sx 属性替换

// 传统 MUI（运行时 Emotion）
<Box sx={{ color: 'primary.main', mt: 2 }} />
 
// Pigment CSS（构建时编译）
// sx prop 被编译为 className + style props
// 运行时不执行样式对象解析

主题编译

// extendTheme 将主题对象编译为 CSS 变量
import { extendTheme } from '@pigment-css/react'
 
export const theme = extendTheme({
  palette: { primary: { main: '#007bff' } },
})
 
// 生成的 CSS 变量
// :root {
//   --palette-primary-main: #007bff;
// }
 
// 在样式中访问
const styles = css({
  color: theme.vars.palette.primary.main, // → 'var(--palette-primary-main)'
})

CSS 分层输出

Pigment CSS 的输出使用 CSS @layer 结构，控制样式优先级：

tokens → base styles → variants → compound variants

核心 API

核心特性

• 零运行时（Zero-Runtime）：构建时将 CSS-in-JS 抽取为独立 CSS 文件，运行时不执行 JS 样式逻辑，消除 Emotion 的运行时开销
• Material Design 深度集成：通过 @mui/material-pigment-css 提供与 Material UI 一致的 styled 和主题 API，MUI 用户几乎零学习成本
• sx 属性编译：构建时将 sx prop 转换为 className 和 style props，避免运行时样式对象解析
• CSS 变量主题系统：extendTheme 将主题编译为 CSS 变量，运行时通过 CSS 切换主题（light/dark）
• React Server Components 完全兼容：零运行时特性天然兼容 RSC，不会因客户端样式计算破坏 Server Components 边界
• CSS 分层（@layer）：输出 tokens → base styles → variants → compound variants 的分层结构，控制样式优先级
• 颜色方案（Color Schemes）：内置 light/dark 模式支持，通过 CSS 变量切换
• 跨框架组件兼容：可与任意 React 组件库（HTML、MUI、第三方 JSX）协同工作
• variants/compoundVariants：类似 Stitches 的组件变体系统，支持复合变体
• Emotion 迁移路径：API 风格与 Emotion 高度一致，为 MUI 用户提供渐进式迁移路径

生态图

官方包

底层依赖

MUI 生态关系

┌─────────────────────────────────────────────┐
│                  MUI 生态                    │
├─────────────────────────────────────────────┤
│                                             │
│  MUI v5/v6/v7 ─── 默认使用 Emotion          │
│       │                                     │
│       ├── opt-in ──→ Pigment CSS (实验性)    │
│       │                                     │
│  @mui/material-pigment-css                  │
│       │                                     │
│       └── Material Design 主题 + styled API │
│                                             │
└─────────────────────────────────────────────┘

Bundler 支持

社区生态

• 社区规模小：GitHub ~1,100 Stars，依赖该包的公开仓库较少
• 无独立官网：文档散布在 MUI Material 文档中
• 无 Discord/Forum：依赖 MUI 主社区（Stack Overflow、GitHub Discussions）
• 第三方资源匮乏：教程、博客、第三方库极少

适用场景

• MUI 深度用户追求性能优化：如果你已深度使用 MUI 且希望消除 Emotion 运行时开销，Pigment CSS 是唯一的官方路径
• RSC 优先的 MUI 项目：Emotion 不兼容 RSC，Pigment CSS 是 MUI 在 Next.js App Router 生态中的关键布局
• Material Design 项目：深度集成 Material Design 主题和组件，通过 CSS 变量实现 Material You / Material 3 支持
• 需要 Emotion 迁移路径：API 风格与 Emotion 高度一致，提供渐进式迁移方案
• Bundle 大小敏感项目：移除 Emotion 运行时可节省约 10-15 KB gzip
• MUI + Material You 项目：通过 extendTheme 可以将 Material You (MD3) tokens 注入 Pigment CSS
• CSS 变量驱动的主题切换：light/dark 模式通过 CSS 变量切换，无需运行时主题重建

开发与工程化

开发流程

1. 安装配置：安装 Pigment CSS 和对应的 bundler 插件
2. 主题配置：使用 extendTheme 定义 Material Design 主题
3. 编写组件：使用 styled、css、sx 等 API（与 MUI/Emotion 风格一致）
4. 开发调试：HMR 预览样式变化
5. 构建部署：编译器自动提取 CSS 文件
6. 主题切换：通过 CSS 类名切换 light/dark 模式

主题管理

// theme.ts - 定义主题
import { extendTheme } from '@pigment-css/react'
 
export const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: { main: '#007bff' },
        background: { default: '#ffffff' },
      },
    },
    dark: {
      palette: {
        primary: { main: '#3b82f6' },
        background: { default: '#1f2937' },
      },
    },
  },
})

// 组件中使用 CSS 变量
import { css } from '@pigment-css/react'
import { theme } from './theme'
 
const styles = css({
  color: theme.vars.palette.primary.main,    // → var(--palette-primary-main)
  backgroundColor: theme.vars.palette.background.default,
})

// Light/Dark 切换 - 通过 CSS 类名
function ThemeToggle() {
  return (
    <div className={theme.vars.colorScheme === 'dark' ? 'light-mode' : 'dark-mode'}>
      {/* 主题通过 CSS 变量自动切换 */}
    </div>
  )
}

与 MUI 组件混用

// 可以在同一个项目中混用 Emotion MUI 和 Pigment CSS
import { Button as MuiButton } from '@mui/material' // Emotion
import { styled } from '@pigment-css/react'           // Pigment CSS
 
const PigmentCard = styled('div')({
  padding: '16px',
  borderRadius: '8px',
})
 
function App() {
  return (
    <PigmentCard>
      <MuiButton variant="contained">MUI 按钮</MuiButton>
    </PigmentCard>
  )
}

CI/CD 集成

• Pigment CSS 与标准 CI/CD 流程兼容
• 构建时编译器自动提取 CSS
• 确保 CI 环境安装 Node.js
• Alpha 阶段 API 不稳定，建议锁定版本

迁移策略

1. 混合使用：可混合使用 Emotion + Pigment CSS（opt-in 模式）
2. 逐步迁移：从新组件开始使用 Pigment CSS，旧组件保持 Emotion
3. 锁定版本：关注 @pigment-css/react 的 CHANGELOG，避免自动升级 minor 版本

性能与安全

性能特点

与 Emotion 的性能对比

安全注意事项

• Pigment CSS 编译时提取的 CSS 是静态的，不存在运行时注入风险
• CSS 变量值是静态编译的，不存在运行时注入风险
• 主题对象运行时只包含可序列化值，不能动态构造

已知性能瓶颈

• 构建时间增加：零运行时方案通病，WyW-in-JS 编译需要额外的构建时间
• 主题编译开销：extendTheme 在构建时编译主题，复杂主题可能增加构建时间
• Alpha 阶段优化不足：尚未进行充分的性能优化

技术对比

关键对比结论

• vs Emotion/styled-components：Pigment CSS 消除运行时开销、兼容 RSC，是 MUI 官方的"未来方案"；但 Emotion 仍是 MUI 默认且成熟稳定
• vs Panda CSS：MUI 成员 Olivier Tassinari 表示 Pigment CSS 的目标是"从 styled-components 无痛迁移"；Panda CSS 更成熟、社区更大
• vs vanilla-extract：vanilla-extract 学习曲线更陡但社区更成熟；Pigment CSS 对 MUI 用户更友好
• vs StyleX / Griffel：社区有声音认为 MUI 应直接采用 Facebook 的 StyleX 或 Microsoft 的 Griffel，而非自研（参见 GitHub Issue #45759）

最佳实践

推荐模式

1. 统一通过 theme.vars.* 访问 CSS 变量

   // ✅ 推荐：使用 CSS 变量
   const styles = css({
     color: theme.vars.palette.primary.main,
     backgroundColor: theme.vars.palette.background.default,
   })
    
   // ❌ 避免：运行时主题对象
   const styles = css({
     color: theme.palette.primary.main, // 运行时解析
   })

2. 使用 variants 管理组件变体

   const Button = styled('button', {
     base: { padding: '8px 16px', borderRadius: '4px' },
     variants: {
       intent: {
         primary: { backgroundColor: '#007bff', color: 'white' },
         secondary: { backgroundColor: '#6c757d', color: 'white' },
       },
     },
     defaultVariants: { intent: 'primary' },
   })

3. Light/Dark 通过 CSS 类切换

   // ✅ 通过 CSS 类名切换颜色方案
   <div className={isDark ? 'dark-mode' : 'light-mode'}>
    
   // ❌ 避免：运行时重建主题对象
   <ThemeProvider theme={isDark ? darkTheme : lightTheme}>

4. 全局样式在 JS 文件根级声明

   // ✅ 根级声明
   globalCss({
     body: { margin: 0, fontFamily: 'Inter, sans-serif' },
   })

5. 避免动态字符串拼接样式

   // ❌ 避免
   const styles = css({
     color: `#${userColor}`, // 运行时值
   })

常见陷阱

1. 运行时主题对象——Pigment CSS 的主题运行时只包含可序列化值，不能动态构造新主题
2. 动态 light/dark 切换——主题在构建时编译，运行时只能通过 CSS 变量切换预设颜色方案
3. Alpha API 不稳定——v1 RFC 显示将进行重大重构（模块化拆分）
4. 与 MUI 强绑定——@mui/material-pigment-css 是主入口，独立使用体验不佳
5. 文档不完善——无独立官网，文档散布在 MUI Material 文档中
6. Webpack 不支持——目前仅官方支持 Next.js 和 Vite

技术局限与边界

已知限制

不适用场景

• 新项目默认采用：鉴于"on hold"状态，不建议新项目默认采用
• 需要长期稳定支持：无明确 v1 时间表，长期维护存在风险
• 非 MUI 项目：独立使用体验不佳，不如 vanilla-extract 或 Panda CSS
• 需要完整 Webpack 支持：目前仅支持 Next.js 和 Vite
• 高度动态样式：运行时主题限制较多
• 社区资源依赖：遇到问题时可参考资源极少

迁移注意事项

• 从 Emotion 迁移：API 风格相似，可混合使用逐步迁移，但需注意 Pigment CSS 的"on hold"状态
• 从 JSS（MUI v4）迁移：建议先迁移到 Emotion（MUI v5/v6），再考虑 Pigment CSS
• 迁移到替代方案：若追求零运行时且无需 MUI 集成，Panda CSS 或 vanilla-extract 是更稳妥的选择
• 回退到 Emotion：建议做好 fallback 到 Emotion 的准备， Pigment CSS 随时可能停止维护

学习资源

• 官方文档：https://mui.com/material-ui/experimental-api/pigment-css/
• GitHub 仓库：https://github.com/mui/pigment-css
• MUI 博客 - 介绍 Pigment CSS：https://mui.com/blog/introducing-pigment-css/
• MUI 博客 - 2026 及未来规划：https://mui.com/blog/2026-and-beyond/ （明确 Pigment CSS "on hold"）
• v1 RFC：https://github.com/mui/pigment-css/issues/362
• MUI 社区讨论：https://github.com/mui/material-ui/issues/45759
• 迁移指南：https://mui.org.cn/material-ui/migration/migrating-to-pigment-css/
• 教程文章：
  • LogRocket - Exploring Pigment CSS
• Twitter/X：@PigmentCSS

2026 年现状

最新版本

关键状态：项目处于"暂停 / 战略待定"阶段

MUI 官方表述（2026 博客原文摘要）

"Pigment CSS remains in alpha phase and is currently on hold. We made fast progress early on, but it became clear that the underlying problems… progressing further would require a different approach."

"We believe in the potential of the original concepts, but development is paused while we redirect focus toward separate core objectives."

发展趋势

• 非活跃开发状态：核心团队已暂停推进
• 无明确 v1 时间表
• MUI v7 仍使用 Emotion：Pigment CSS 未成为默认
• 无独立官网
• 仓库仍维护：有 issue 响应，偶尔发布 patch 版本
• 概念被认可：零运行时 + RSC 兼容的方向被认为是正确的

社区活跃度

评估：社区规模极小，属于"关注度高、采用率低"的项目——大量 MUI 用户在观望，但真正用于生产环境的较少。

与 MUI v6 及 Material You 的关系

• MUI v6（2024-08）首次引入 Pigment CSS 作为 opt-in experimental，但默认仍使用 Emotion
• MUI v7（2025）仍使用 Emotion，Pigment CSS 依旧 experimental
• Material You / Material 3：Pigment CSS 与 MD3 互补——MD3 提供设计规范，Pigment CSS 提供将 tokens 编译为 CSS 变量的机制
• 战略意义：Pigment CSS 是 MUI 在 RSC 时代的关键布局，但"on hold"状态表明这条路径存在技术和资源挑战

项目状态评估

替代方案建议