Cascade Layers

[HiDeoo]

Description

• Closes consider using cascade layers #1048

This PR is a WIP that refactors all Starlight CSS to use cascade layers.

At the moment, Starlight will internally uses the following nested layers:

• starlight.base
• starlight.reset
• starlight.core
• starlight.content
• starlight.components
• starlight.utils

This slightly reduces browser support by 0.3% (Chrome >= 88 → Chrome >= 99).

Testing

As I quickly realized that manually inspecting would not be practical for this PR to ensure there are no regressions, I created a new temporary package to help test the changes (packages/local-prod-visual-diff) that can be run using pnpm test from that directory.

For a list of routes, the tool will:

• Grab an entire page screenshot of the production version of the route (if it doesn't already exist locally)
• Start a local server and grab an entire page screenshot of the local version of the route
• Visually diff the two screenshots
• If there are significant differences, a diff image with differences in yellow/red will be generated and the test will fail

This has been very helpful to spot some tiny issues during the refactor, e.g. the following diff image that shows a tiny difference in the header <Select> component icons:

Another one showing an issue with the content of the last step in a set of <Steps>:

Of course, this is only a bonus and this PR would still be a good Talking & Doc'ing candidate with many different eyes/browsers.

Remaining tasks

• Tailwind v4 support
• Figure out which layers we want to use (I mostly maximized the number of layers in the first implementation and we can reduce them during the review)
• Figure out if we should namespace the Tailwind layers, e.g. tailwind.base like we do at the moment for Starlight or if we should just use the default layers (not doing that)
• Update the documentation theme editor Tailwind output
• Address and remove the TODO(HiDeoo) comment in the docs/astro.config.mjs file
• Remove the packages/local-prod-visual-diff package
• See if we should remove the default scoped style strategy enforced by Starlight? (not doing that)
  • We would need to refactor various components to handle data-astro-cid-* attributes. Not confident this PR is the right place to do that.
• Improve documentation
• Add changesets for all impacted packages.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6928271

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@astrojs/starlight	Minor
@astrojs/starlight-tailwind	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	6928271
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67fe9610f0ba0c0008bb618d
😎 Deploy Preview	https://deploy-preview-2322--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/css-and-tailwind.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[delucis]

Copying @mayank99 in on this PR! Will try to take a look soon.

[mayank99]

Excited to see this!

I'll try to take a deeper look when I have some time. For now I've just left one question.

[HiDeoo]

Small note that Tailwind CSS v4.0 Beta adds native CSS cascade layers support.

[mayank99]

Tailwind v4's layer implementation has good and bad parts.

The bad: they implicitly create very generic layer names (i.e. not namespaced).

The good: they allow control over importing their stylesheets(s) so you can put their layers inside your own layer or even change the names.

@import "tailwindcss" layer(💨);

/* or */

@import "tailwindcss/base" layer(💨base);
@import "tailwindcss/theme" layer(💨theme);
@import "tailwindcss/utilities" layer(💨utilities);

[mayank99]

Finally got the chance to try it out, and I'm happy to report it's working great! 🥳

When I used customCss, I found that the stylesheet was linked before Starlight's own CSS. I'm not sure if this behavior is intentional and will remain this way, but it works out great for the layer use-case.

For extra surety, I also tried overriding Starlight's Head component and it worked as expected for placing an inline <style> tag with my predefined layer order before all other <head> content.

[delucis]

I’m too sleepy to fully tackle the docs — will do those tomorrow morning — but getting in at least a review on all the code changes.

Amazing work as always @HiDeoo and I haven’t spotted anything major I don’t think!

• See if we should remove the default scoped style strategy enforced by Starlight?

I was also wondering that the other day, but I agree with you that this PR already has enough going on 😁

We could definitely reuse your visual diff script for that PR when the time comes though!

[delucis]

Last few remarks on the changesets. Will looks at docs now.

[delucis]

I think this PR is in great shape to merge in our next minor! Many, many thanks to @HiDeoo for iterating over this and getting us to this point. In some ways this is a big architectural change but you’ve carried it out with such care that I think most people will hardly notice, while unlocking lots of improvements for those who need it.