Understanding how CSS layers are used

[hyperknot]

I'm looking at the output of the official babel + PostCSS plugin, and don't yet understand why are CSS layers needed? (or their polyfilled alternatives).

I mean, for example, why does margin-bottom need to be limited to priority5?

The more important question is, how can I combine this with my non-StyleX styles, like reset, etc.?

My idea is to insert this at the beginning of the file:

@layer base,
  priority1,
  priority2,
  priority3,
  priority4,
  priority5,
  priority6,
  priority7,
  priority8,
  priority9,
  priority10;

This line will override the StyleX generated layer list later on, so it allows me to use a base layer for all my non-StyleX parts.

But the layer generation isn't yet clear to me yet. I've noticed the following:

• priority1 is not used
• what would get in priority1, gets in nowhere, I mean it becomes non-layered CSS:

@layer priority1, priority2, priority3, priority4, priority5;
@property --width { syntax: "*"; inherits: false;}

:root, .xnm736s{--blue800-xcbct7y:#1971c2;}
:root, .xl51v50{--sand2-xsmovd3:#f9f9f8;--sand3-x1tww3uu:#f1f0ef;--sand4-xz7wd9t:#e9e8e6;--sand5-x19f15gt:#e2e1de;}

.--trigger-icon-color-xhi76h0{--trigger-icon-color:hsl(0,0%,40%)}
.--trigger-icon-color-x1hiz4or:hover{--trigger-icon-color:hsl(0,0%,0%)}
.--trigger-icon-color-x711iem:hover:is([data-disabled]){--trigger-icon-color:hsl(0,0%,40%)}

@layer priority2{
.inset-x10a8y8t{inset:0}

Can you confirm if this is by design? So in theory I could just keep the layer declaration line from StyleX and reuse priority1 for my own rules?

[nmn]

So in theory I could just keep the layer declaration line from StyleX and reuse priority1 for my own rules?

yes you could do this, but StyleX may output styles within that layer. It depends on what styles exist.

the layers exist to ensure that various different styles have the right specificity. We need margin-top to win over margin for example. But in practice things are more complex as we account for pseudo-classes and at-rules and combinations of them alongside shorthand’s and longhand’s.

For reset styles, you can wrap them in your own layer and ensure they’re inserted on the HTML page before the StyleX styles.

[hyperknot]

It'd be nice to have support for adding layers before (and possibly after) the StyleX priority ones.

The current hack of inserting my own empty layer declarations, guessing that StyleX will never use more than 10 priority layers and trusting the fact that browsers only look at the first empty layer declarations and discard the later ones is very much a hack.

It'd be so elegant to say something like layersBefore, like this:

        stylexPostcss({
          babelConfig: stylexBabelConfig,
          useCSSLayers: true,
          include: ['../packages/shared/**/*.tsx', '../packages/shared/**/*.stylex.ts'],
          exclude: [
            '../packages/**/_not_used/**',
            '../packages/**/node_modules/**',
            '../packages/**/*.d.ts',
          ],
          layersBefore: ['variables', 'reset', 'base'],

[necolas]

It shouldn't matter what layers StyleX uses, or how many, as you can create your own layers or layer statements before or after in other files or inline code - https://developer.mozilla.org/en-US/docs/Web/CSS/@layer. I'd recommend keeping any non-StyleX CSS code to a minimum though.

[hyperknot]

I didn't find this information on that page, but in the specs:
https://drafts.csswg.org/css-cascade-5/

So, if I understand correctly:

1. multiple @layer statement at-rules are OK in the same file.
2. the individual layer order is mixed-and-matched between @layer statement at-rules.

So I can do this:

@layer reset, base;
@layer base {
...
}
@import url(components.css) layer(components);
@layer utilities, base, shame;
@layer debug;

And the final layer order will be:

reset
base
components
utilities
shame
debug

---

What it means for StyleX is that I can just leave all those priority layers alone and add my layers before them. Both statement at-rule and layer contents.

If I understand correctly.

[necolas]

That is my understanding too

[nmn]

is your concern that you can’t always insert your own CSS before styleX’s output?

[hyperknot]

My concern was that I didn't know how can I extend or override the @layer statement at-rule StyleX creates.
Normally you don't have multiple of these statements in a CSS file and it wasn't documented almost anywhere what happens when multiple statements are added to the same file and how they interact.
I thought I need to repeat the ones made by StyleX, so I had to look into how does it work internally, what's the biggest priorityX number it's going to use, etc.
Now, in my understanding this is not needed, I can just add my own statement before and the browser will combine both.

[nmn]

Now, in my understanding this is not needed, I can just add my own statement before and the browser will combine both.

Yes this is true. Any CSS you have before the StyleX generated CSS will work as expected as long as you wrap your styles in a layer.