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.shiki
• starlight.components
• starlight.content
• starlight.user-components
• starlight.asides
• starlight.expressive-code
• 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 (I didn't even look at it yet)
• 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?
  • We would need to refactor various components to handle data-astro-cid-* attributes. Not sure yet if this PR is the right place to do that.
• Documentation (only a very rough draft for now)
• Add a changeset

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8b39634

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	8b39634
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/66e1aedf5ebcc80008b9a28b
😎 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 (🟢 up 1 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (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.

[mayank99]

Where is this file used? It is very important that this comes before any other starlight stylesheets.

[HiDeoo]

Currently, this is used in the <Page> component before any other Starlight styles, altho this can still be overridden by a user through the virtual:starlight/user-css import.

Excited to see interest in this, the draft may a bit rough at this point but I'll continue iterating on it and it should be a good starting point for discussion.

[mayank99]

What I've found is that order of imports is not a reliable way to ensure order of styles. I've run into many instances where Vite/Astro jumbles up the CSS order.

Should we move this layer statement into a <style> tag in the <head>? Ideally this would be placed after the user's own <head> content, but before all the bundled stylesheets.

[HiDeoo]

This is something I'll need to investigate as this is not something I've encountered so far in this first iteration. The suggested approach could also decrease the DX for user customization. Adding that point to my todo list of things to investigate and I'll get back with my findings.

[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);