Use CSS cascade layer (`@layer`)

[siriwatknp]

Why

To ensure that the styles are overrides in a correct order regardless of framework.

The issue I found is from Next.js v14 where the appearance of dev and production are not the same. The generated CSS are the same but the order are not:

dev: the CSS is bundled in one file _page.css which gives the expected result because the styles from sx prop comes later. production: the CSS is split across files then Next.js specifies through <link rel="stylesheet">, somehow the link that contains sx overrides is placed before the components which gives the unexpected result like the image below (the header should not have background blue).

Solution

If styles are organized with CSS layer, the appearance will be the same for both dev and production regardless of how frameworks bundle the build.

Proposal

As a start, Pigment should have 2 layers when enabled: @layer base, overrides

• base are default styles including CSS variables from the theme and component styles. This is for library author, e.g. Material UI to use.
• overrides are styles from the consumer, any APIs that are used in the project including theme.components.

Search keywords:

[siriwatknp]

@brijeshb42 Do you think variants layer is needed?