Pigment CSS migration limits for runtime theming and dynamic sx usage

Direct Answer

Pigment CSS and Material UI's runtime styled engine can coexist during incremental adoption, but the pattern requires component-level implementation rather than a simple global toggle. For applications needing both zero-runtime CSS for static components and runtime theming for dynamic parts, the supported approach is to apply Pigment CSS only to specific components while continuing to use the default styled engine elsewhere.

How Selective Adoption Works

The key is that Pigment CSS operates at the component level through Babel plugin transformation. When you configure the babel-plugin-pigment-css, it processes only the files where you explicitly import from @pigment-css or apply its styling patterns. Components using standard Material UI imports remain on the runtime engine.

// pigment-button.jsx - uses zero-runtime CSS
import { styled } from '@pigment-css/react';

const PigmentButton = styled('button')({ color: 'primary' });

// regular-button.jsx - uses runtime engine
import { styled } from '@mui/material/styles';

const RegularButton = styled('button')({ color: 'primary' });

Compatibility Criteria for sx Expressions

The critical question is whether an sx expression can be resolved at build time. Pigment CSS can extract static values, but dynamic theme references require runtime evaluation:

• Compatible: Literal values, CSS variables, static theme tokens (theme.spacing(2) when theme is static)
• Incompatible: Dynamic theme access ((theme) => theme.palette.primary.main), responsive values with runtime conditions, theme overrides that change at runtime

Verification Requirements

Because Pigment CSS's production readiness varies significantly across Material UI versions, you must verify your specific version's capabilities:

1. Check your Material UI version's documentation for Pigment CSS support status
2. Test a component with purely static styles using Pigment to confirm build-time extraction works
3. Verify that dynamic theme switching still functions for components using the default engine
4. Confirm your sx expressions resolve correctly—expressions using theme callbacks will not work with Pigment

Important Considerations

The migration does not require a global switch. You can incrementally adopt Pigment CSS by transforming components one at a time. However, each component must be evaluated independently for compatibility. If your application relies heavily on runtime theme switching or complex dynamic sx expressions, the benefits of Pigment CSS may be limited for those components.

One missing detail needed: What Material UI version are you using? The experimental vs. production-ready status of Pigment CSS features differs significantly across v5.10, v5.13, and later releases, which directly impacts the migration path and feature availability.