SX and Styled can't override applyStyles css

[RickyRoller]

Steps to reproduce

Repro link

Steps:

1. Setup theme to use css variables
2. Use theme.applyStyles to apply dark theme styles to component
3. Sx and Styled components can't overwrite the dark theme styles

Current behavior

Sx and Styled theme behavior breaks with this new paradigm. They can't override the styles if the base component is using the new applyStyles helper since it creates a css selector with higher specificity

Expected behavior

Sx and Styled should be able to override styles like they used to with theme.palette.mode conditional logic

Context

There are multiple issues with the new css variables system.

1. Sx and Styled can't override styles that use theme.applyStyles due to specificty
2. theme.applyStyles doesn't support template literal syntax so the css selector has to either be extracted to a var or hardcoded
3. Docs are inconsistent on recommendations. Docs say to use spread syntax on theme.applyStyles, then the actual code files say to not use spread syntax. ie. Docs, Code
4. applyStyles isn't a valid replacement for controlling the theme of specific components. If you only specify dark theme styles with applyStyles, then adding .mode-light to a component won't apply those styles since .mode-dark has higher specificity. Refer to link for example

The biggest issue is the breaking change with sx/styled behavior

/**
 * All 3 buttons should be green (#bada55)
 */

/**
 * Light theme should be red
 * Dark theme should be blue
 */

const BaseButton = styled(Button)(({ theme }) => ({
  background: 'red',
  color: '#fff',
  ...theme.applyStyles('dark', {
    background: 'steelblue',
    color: '#fff',
  }),
}));

/**
 * Styled can't override dark theme either
 */

const StyledButton = styled(BaseButton)`
  background: #bada55;
`;

/**
 * No support for applyStyles with template literals
 */

const TemplateButton = styled(Button)`
  background: red;
  color: #fff;
  *:where(.mode-dark) & {
    background: aliceblue;
    color: #555;
  }
`;

/**
 * applyStyles isn't a valid alternative to controlling theme for a specific component.
 * If you don't split all styles into applyStyles('light') and applyStyles('dark') then it won't apply the alternative
 */

const Themed = () => (
  <div className=".mode-light">
    <BaseButton variant="contained">Light Themed</BaseButton>
  </div>
);

export default function BasicButtons() {
  return (
    <Stack spacing={2} direction="row">
      <BaseButton
        variant="contained"
        sx={{
          background: '#bada55',
        }}
      >
        Dark
      </BaseButton>
      <StyledButton variant="contained">Styled</StyledButton>
      <TemplateButton
        variant="contained"
        sx={{
          background: '#bada55',
        }}
      >
        Template
      </TemplateButton>
      <Themed />
    </Stack>
  );
}

Your environment

npx @mui/envinfo

  System:
    OS: macOS 14.1.1
  Binaries:
    Node: 20.12.2 - ~/.nvm/versions/node/v20.12.2/bin/node
    npm: 10.8.3 - ~/.nvm/versions/node/v20.12.2/bin/npm
    pnpm: 9.13.0 - ~/.nvm/versions/node/v20.12.2/bin/pnpm
  Browsers:
    Chrome: 131.0.6778.71
    Edge: Not Found
    Safari: 17.1

Search keywords: css variables, css vars, applyStyles, sx, styled

[siriwatknp]

Sx and Styled theme behavior breaks with this new paradigm. They can't override the styles if the base component is using the new applyStyles helper since it creates a css selector with higher specificity

This is expected as a default behavior. However, you can customize applyStyles to match your need, here is an example:

const theme = createTheme({
  cssVariables: {
    colorSchemeSelector: '.mode-%s',
  },
  colorSchemes: {
    dark: {},
    light: {},
  },
  applyStyles: function (key: string, styles: any) {
    if (typeof styles === 'string') {
      return `*:where(.mode-${key}:not(:has(.mode-light))) & {${styles}}`;
    }
    return {
      [`*:where(.mode-${key}:not(:has(.mode-light &))) & `]: styles,
    };
  },
});

[siriwatknp]

I mark this as an enhancement to make the applyStyles support literal styles.

And to add a docs about customizing theme.applyStyles.

[RickyRoller]

It's good to know that you can override the applyStyles function, but that's not the crux of this issue.

The issue is that there is a breaking change when switching to the new system of using applyStyles and there is seemingly no workaround for it.

This code creates green text in both themes

const Text = styled('div')`
  color: ${({ theme }) => theme.palette.mode === 'dark' ? 'red' : 'blue'};
`;

<Text sx={{ color: 'green' }}>Hello</Text>

But that's not possible with the new system. This results in green text in light mode and red text in dark mode.

const Text = styled('div')(({ theme }) => ({
  color: 'blue',
  ...theme.applyStyles('dark', {
    color: 'red',
  }),
}));

<Text sx={{ color: 'green' }}>Hello</Text>

It's a problem with sx and styled modifying the base styles of a component and so the dark theme styles always overwrite those. Honestly I'm not sure how this is even solvable with out a major change like moving styles into layers so that sx/styled always override.
If it's not solvable, there should be a massive warning on the docs that say this approach has a very real limitation that will be very hard to work around and is a breaking change from old behavior

[siriwatknp]

The issue is that there is a breaking change when switching to the new system of using applyStyles and there is seemingly no workaround for it.

That's true. I will add docs for this but I don't see a perfect transition, the @layer will make the experience the same but you will to adjust the external CSS.

Anyway, the next step is to add option to enable CSS @layer as it's become a standard.