Support for CSS @layer

[lyleaigbedion]

Is there a chance for all of the Infima CSS it be wrapped in @layer to better override the css in Docusaurus?

[slorber]

I don't think we'll do this on the Infima side (which I'd like to slowly deprecate and internalize to Docusaurus)

If you only care about Docusaurus global CSS pollution, track https://github.com/facebook/docusaurus/issues/6032

Maybe we'll adopt Cascade layers and append one automatically to all Infima classes, but we'll probably also want to do so on other parts of Docusaurus.

[shirakaba]

I keep bumping into this. I am using Tailwind v4 in Docusaurus and fundamental Tailwind classnames like hidden and max-w-none get ignored because they're in @layer utilities, while Infima has global rules like these that take priority over them regardless of CSS rule specificity:

* {
  box-sizing: border-box;
}

img {
  max-width: 100%;
}

If these were in @layer base, it would be possible to override them with Tailwind, but because they're not, I can't override them even with higher rule specificity. I'm kinda stuck.

~~For now, I'm doing the following as a workaround. I duplicate each problematic class from Infima, resetting their values to initial, and then I duplicate the original content of the classes into @layer base~~:

:root {
  /*
   * Reset these global rules that we got from Infima:
   * node_modules/infima/dist/css/default/default.css.
   */
  * {
    box-sizing: initial;
  }
  img,
  video {
    max-width: initial;
    height: initial;
  }
}

@layer base {
  /*
   * Move the Infima rules into the "base" layer, which is below the "utilities"
   * layer, so that we can override them with Tailwind classes.
   */
  * {
    box-sizing: border-box;
  }

  img {
    max-width: 100%;
  }
  img,
  video {
    max-width: 100%;
    height: auto;
  }
}

EDIT: I misunderstood, and the workaround doesn't work as intended (setting those styles to initial in the global scope of course means they can't be overridden by @layer base). Now I have a big dinosaur covering my screen.

Looking forward to the CSS being internalised to Docusaurus – but in layers below Tailwind's @layer utilities layer, please!

[slorber]

Yes I understand those problems are annoying.

We'll try to figure out a solution as CSS support increase in browsers.

I also plan to explore CSS Scope limit to opt out of base styling for specific HTML subtrees.

@scope (.docusaurus-style-start) to (.docusaurus-style-end) {
  rulesets
}

This is part of Interop 2025 and we are just waiting for Firefox to unflag this.

---

Looking forward to the CSS being internalised to Docusaurus – but in layers below Tailwind's @layer utilities layer, please!

We don't officially use Tailwind on our theme so it's unlikely that we'll even choose an order for that layer. Afaik you can override the default order we provide for layers so you can decide on your own if the Tailwind layer should appear above/under ours.