consider using cascade layers #1048

mayank99 · 2023-11-06T23:55:14Z

mayank99
Nov 6, 2023

What version of `starlight` are you using?

0.12.0

What is your idea?

Currently evaluating starlight for a docsite (already using Astro) which makes heavy use of cascade layers for all of its styles. It would help if Starlight wrapped all of its styles in a cascade layer (either by default or opt-in). Alternatively, provide a manual way to import Starlight styles. Would this be possible?

Why is this feature necessary?

Cascade layers are a sort of "all or nothing" feature. Starlight's unlayered styles will take preference over even the highest priority cascade layer, which causes varying amounts of frustration depending on where the custom styles are meant to go.

With all Starlight styles wrapped in a specific layer, it allows the author to add styles both before and after starlight's styles, without any specificity battles. The basic order would be something like this:

@layer my-globals, starlight, my-overrides;

Do you have examples of this feature in other projects?

No response

Participation

I am willing to submit a pull request for this feature.

delucis · 2023-11-07T10:03:27Z

delucis
Nov 7, 2023
Maintainer

Definitely on our radar, thanks @mayank99! @layer would also save us from needing to enforce a specific scoped style strategy like we do currently.

Our current browser support matrix includes Chromium v88–98 which don’t support @layer, but I think we could prepare to make a breaking release that drops those and move to @layer.

6 replies

delucis Nov 7, 2023
Maintainer

Sure, would love some help! Can’t say I’m up-to-speed on @layer best practices, so if you already have experience of structuring projects that use it, I’d be happy for you to take the lead and propose something.

mayank99 Nov 10, 2023
Author

Here's the gist of using layers in Astro:

Layer order should be defined upfront in order for them to work at all.
- To ensure it appears before any bundled CSS, I like to inline it inside <head>.
```
<head>
  <style is:inline>
    @layer globals, layouts, components;
  </style>
</head>
```
- The above shows a very basic layer order, but usually I go with something more involved like below (You can add/subtract layers (and sublayers) as necessary depending on where you usually face difficulty in your CSS):
```
@layer reset, globals, layouts, thirdparty, components, pages, overrides;
```
Define global (non-scoped) styles inside CSS files and let them orchestrate their own order, then import them into the layout component's frontmatter.
- This is super important, because Astro has a nasty bug where it will break your layers in dev environments if you @import CSS files into a layer inside an Astro component's <style>.
Within component files, wrap all scoped styles into layers!
- Different parts of the components can go into different layers as necessary. Example:
```
<button {...Astro.props}>
  <svg>…</svg>
  <span></span>
</button>

<style>
  @layer components.base {
    button { … }
    svg { … }
  }
  @layer components.modifiers {
    button: { … }
  }
</style>
```
- If using something like Sass, the layer syntax can be nested at any level without any restrictions.
- Since layouts/pages are also components, the same philosophy applies. Just switch the layer names.

I haven't looked inside Starlight's CSS so I can't speak to that, but I imagine you'd want a layer order like the second one I used above. Only other thing, you may (or may not) want to wrap all your layers in a combined starlight parent layer, so that the user can easily move around all Starlight styles to their desired place in order. From an API standpoint, it's generally better to have fewer "exposed" layers, even if you use lots of "internal" nested layers (e.g. @layer starlight.globals.theme).

Hope that was at least a little bit helpful! Let me know if you have any questions

mayank99 Mar 1, 2024
Author

@delucis Have you given this any more thought?

One interesting development since then is Expressive Code's cascadeLayer support. Maybe Starlight could do something similar?

starlight({
  cascadeLayer: 'starlight',
}),

I'd imagine you'd need to expose multiple layer names, since Starlight has a lot of styles.

starlight({
  cascadeLayers: {
    reset: 'reset.starlight',
    layouts: 'layouts.starlight',
    components: 'components.starlight',
    pages: 'pages.starlight',
  },
}),

delucis Mar 1, 2024
Maintainer

Interesting! I guess that’s a bit trickier for us because most of our styles are either in <style> tags in Astro components or in actual CSS files. I’m guessing Expressive Code can support this because it generates style strings artisanally outside of Astro’s standard build pipelines.

And sorry, haven’t had the bandwidth to think about this much sorry, although I do still think this is where we should end up eventually.

Do you think there is a big advantage to allowing custom naming for layers? Would complicate our lives quite a bit I guess.

One thing I’m curious about: you mentioned wanting to combine Starlight with your own code using cascade layers. Are there any things Starlight should definitely do or not do to ensure someone who already has code like that has a nice experience? (Beyond “use layers”, because obviously Starlight styles need to be in some kind of layer to be easily overridable.) Like, would you expect to somehow slot your layers into Starlight’s order? Have reserved names for your own use? etc.

mayank99 Mar 1, 2024
Author

The most important thing is that the application/consumer is able to specify the "final" layer order.

Custom layer names are the most foolproof way to do this (maybe could be achieved via a PostCSS plugin?), but if that's not possible, then Starlight layer names should be (1) namespaced, and (2) few in number.

For example, you might have a @layer starlight-base and a @layer starlight-pages (both of which can still have "private" sub-layers that you use for organizing your own styles). Having fewer layer names reduces your API surface and makes it easy for the consumer to insert them into their own layer order.

@layer my-base, starlight-base, my-components, starlight-pages, my-pages;

silveltman · 2024-06-09T13:23:01Z

silveltman
Jun 9, 2024

Is there a wat we can place starlights styles manually in a @layer? Or at least the style reset in a @layer base{}

I'm building Fulldev UI (an Astro ui component library https://ui.full.dev/) and I want the styles of the components to have low specificity so that they can be overwritten with Tailwind, Unocss etc.

Because of the low specificity (because styles are placed in a @layer fulldev {}, the starlight style reset overwrites the component styles.

The not-content class allows us to prevent some styling, but not all.

Tailwindcss V4 looks like it's going to use CSS layers too: https://tailwindcss.com/blog/tailwindcss-v4-alpha

2 replies

delucis Jun 18, 2024
Maintainer

Unfortunately this kind of thing is not easy to apply manually, so will probably need to wait until we do refactor things on our end — definitely planning to do that, just a matter of time!

Boston343 Jan 26, 2025

I have a request related to this (resurrecting this largely dead discussion). What about if the CSS reset can just be cancelled with a class? Similar to the "non-content" class for cancelling out md / mdx starlight styling.

The problem I'm currently facing is the starlight CSS reset includes

input, button, textarea, select {
  font: inherit;
}

This overrides every font setting that Tailwind V4 uses because this is not in a CSS layer, and all of Tailwind v4 is in CSS layers.

Instead I propose changing the reset to something like this:

input:not(:where(.not-starlight-reset *)) {
  font: inherit;
}

etc. I believe this would allow you to still support older browsers that don't support CSS layers, and it gives users a class to cancel out all starlight styling for a completely blank slate. This allows Tailwind v4 users (me) to have a component like:

---
import "@/styles/tailwind.css"
---
<div class="not-content not-starlight-reset">
  <slot />
</div>

Which would cancel out any starlight styling, and then I can use all of Tailwind's features within this component.

delucis · 2025-07-07T17:29:31Z

delucis
Jul 7, 2025
Maintainer

Ooh, just realised this is still open. #2322 implemented this and we shipped it in Starlight v0.34 — thanks again for the discussion folks 🙌

0 replies

Uh oh!

consider using cascade layers #1048

Uh oh!

Uh oh!

mayank99 Nov 6, 2023

What version of starlight are you using?

What is your idea?

Why is this feature necessary?

Do you have examples of this feature in other projects?

Participation

Replies: 3 comments · 8 replies

Uh oh!

delucis Nov 7, 2023 Maintainer

Uh oh!

delucis Nov 7, 2023 Maintainer

Uh oh!

Uh oh!

mayank99 Nov 10, 2023 Author

Uh oh!

Uh oh!

mayank99 Mar 1, 2024 Author

Uh oh!

delucis Mar 1, 2024 Maintainer

Uh oh!

mayank99 Mar 1, 2024 Author

Uh oh!

silveltman Jun 9, 2024

Uh oh!

delucis Jun 18, 2024 Maintainer

Uh oh!

Boston343 Jan 26, 2025

Uh oh!

delucis Jul 7, 2025 Maintainer

mayank99
Nov 6, 2023

What version of `starlight` are you using?

Replies: 3 comments 8 replies

delucis
Nov 7, 2023
Maintainer

delucis Nov 7, 2023
Maintainer

mayank99 Nov 10, 2023
Author

mayank99 Mar 1, 2024
Author

delucis Mar 1, 2024
Maintainer

mayank99 Mar 1, 2024
Author

silveltman
Jun 9, 2024

delucis Jun 18, 2024
Maintainer

delucis
Jul 7, 2025
Maintainer