Cascade Layers by HiDeoo · Pull Request #2322 · withastro/starlight

HiDeoo · 2024-09-11T14:49:28Z

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

changeset-bot · 2024-09-11T14:49:32Z

🦋 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 · 2024-09-11T14:49:43Z

✅ 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 · 2024-09-11T14:50:20Z

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 · 2024-09-11T14:56:33Z

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.

packages/starlight/style/layers.css

HiDeoo · 2024-11-22T09:03:46Z

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

mayank99 · 2024-11-22T13:12:16Z

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

* main: (493 commits) i18n(de): update `sidebar.mdx` (withastro#2900) Adding all samples for badges in sidebar as example (withastro#2881) i18n(fr): fix highlighting in `reference/plugins.md` (withastro#2898) i18n(fr): update `reference/plugins` & `guides/i18n` (withastro#2886) i18n(fr): update `reference/overrides` & `guides/sidebar` (withastro#2887) i18n(fr): add `guides/route-data` and `reference/route-data` (withastro#2884) i18n(fr): update `guides/overriding-components` (withastro#2885) i18n(fr): update `reference/configuration` (withastro#2888) i18n(de): update German translation with withastro#2578 (withastro#2882) [ci] format i18n(ru): update some translations (withastro#2895) i18n(de): update `reference/configuration.mdx` (withastro#2883) [ci] format i18n(ko-KR): update `configuration.mdx` (withastro#2892) i18n(ko-KR): update `overrides.md` (withastro#2893) i18n(ko-KR): update `overriding-components.mdx` (withastro#2890) i18n(ko-KR): update `i18n.mdx` and `plugins.md` (withastro#2889) [ci] format i18n(ko-KR): create `guides/route-data.mdx` and `reference/route-data.mdx` (withastro#2896) i18n(ko-KR): update `/resources/plugins.mdx` (withastro#2894) ...

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.

docs/src/content/docs/guides/css-and-tailwind.mdx

Co-authored-by: Mayank <9084735+mayank99@users.noreply.github.com>

* main: (31 commits) [ci] release (withastro#3091) i18n(de): update `environmental-impact` (withastro#3112) feat: update environment comparisons data (withastro#3097) chore(deps): update actions/setup-node action to v4.4.0 (withastro#3111) Update Expressive Code and related packages (withastro#3109) i18n(de): update `reference/overrides.md` (withastro#3093) i18n(de): update `reference/route-data.mdx` (withastro#3094) i18n(de): update `resources/themes.mdx` (withastro#3092) [ci] format i18n(zh-cn): Update configuration.mdx (withastro#3102) i18n(zh-cn): Update overrides.mdx (withastro#3103) [ci] format i18n(zh-cn): Add route-data.mdx (withastro#3106) [ci] format i18n(zh-cn): Add themes.mdx (withastro#3105) [ci] format i18n(zh-cn): Update plugins.md (withastro#3104) [ci] format i18n(zh-cn): Update customization.mdx (withastro#3101) i18n(zh-cn): Update badges.mdx (withastro#3100) ...

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!

.changeset/old-toes-flow.md

docs/src/components/theme-designer.astro

packages/local-prod-visual-diff/diff.test.ts

packages/starlight/components/Search.astro

packages/starlight/style/print.css

packages/starlight/components/Select.astro

docs/src/content/docs/guides/css-and-tailwind.mdx

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

delucis

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

.changeset/old-toes-flow.md

docs/astro.config.mjs

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

…add`

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.

* main: [ci] release (withastro#3124) Fix E2E tests broken by formatter [ci] format Add built-in heading anchor link support (withastro#3033) i18n(fr): update `environmental-impact` (withastro#3123) Cascade Layers (withastro#2322) Fix image metadata validation in StarlightPage schema (withastro#3118) Don’t set defaults for `attrs` and `content` in head entries (withastro#3122) [ci] format i18n(es) Translate `route-data` (withastro#3071)

Co-authored-by: Matthew Justice <72817096+JusticeMatthew@users.noreply.github.com> Co-authored-by: Mark Gaze <16718355+markgaze@users.noreply.github.com> Co-authored-by: Mayank <9084735+mayank99@users.noreply.github.com> Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

HiDeoo added 15 commits September 10, 2024 16:30

feat: add layers for built-in styles

6275672

feat: add layer for components

f2e6bf4

feat: add layer for content

db9e350

feat: add layer for asides

dedea00

refactor: increase utils layer precedence order

ee9ca47

feat: add layer for user components

ddb7cb3

feat: add layer to expressive-code

af7e55a

fix: aside component icon size

37c2255

test: add local-prod-visual-diff module

81c6b13

fix: select icons

475c26d

fix: steps content styles

8070d70

docs: update browserslist query

ec587be

test: add local prod command

cc2fccd

refactor: clean css import comments

94e7df4

docs: cascade layers

cee7cbd

github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Sep 11, 2024

fix: update lockfile

8b39634

mayank99 reviewed Sep 11, 2024

View reviewed changes

packages/starlight/style/layers.css Show resolved Hide resolved

This was referenced Oct 11, 2024

How do I change colors for accents ? HiDeoo/starlight-theme-rapide#12

Closed

Change look and feel of auto generated components HiDeoo/starlight-openapi#49

Closed

delucis mentioned this pull request Nov 19, 2024

Starlight markdown CSS selector messes with Latex/Katex square roots. #2511

Closed

1 task

HiDeoo added 2 commits February 18, 2025 16:08

chore: update lockfile

f26e7f8

delucis mentioned this pull request Apr 13, 2025

Lower CSS specificity by wrapping styles in @layer #3098

Closed

mayank99 approved these changes Apr 14, 2025

View reviewed changes

docs/src/content/docs/guides/css-and-tailwind.mdx Outdated Show resolved Hide resolved

HiDeoo and others added 4 commits April 14, 2025 19:17

feat: refactor and simplify tailwind theme configuration

3ad1e64

docs: fix tailwind font customization examples

edb64f0

docs: better cascade layer intro

2b4cf9e

Co-authored-by: Mayank <9084735+mayank99@users.noreply.github.com>

delucis reviewed Apr 14, 2025

View reviewed changes

HiDeoo and others added 4 commits April 15, 2025 09:21

chore: remove astro <5.2.0 tailwind update instructions

0009fb6

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

feat: simplify tailwind @layer directive

90a2b4d

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

fix: port search ui change for metadata from withastro#2848

61fb729

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

docs: update tailwind theme designer output

d70a7ba

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

delucis reviewed Apr 15, 2025

View reviewed changes

.changeset/old-toes-flow.md Show resolved Hide resolved

.changeset/old-toes-flow.md Outdated Show resolved Hide resolved

docs/astro.config.mjs Outdated Show resolved Hide resolved

HiDeoo and others added 5 commits April 15, 2025 15:06

chore: update changeset

e13d8be

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>

chore: remove local-prod-visual-diff package

941c530

Update Tailwind example project to use same style location as `astro …

00400b1

…add`

Tweak “Cascade layers” section

a0b5374

Tweak Tailwind CSS docs

6928271

delucis approved these changes Apr 15, 2025

View reviewed changes

delucis added the ✅ approved Pull requests that have been approved and are ready to merge when next cutting a release label Apr 15, 2025

delucis mentioned this pull request Apr 15, 2025

Add built-in heading anchor link support #3033

Merged

4 tasks

delucis merged commit f14eb0c into withastro:main Apr 16, 2025
16 checks passed

astrobot-houston mentioned this pull request Apr 16, 2025

[ci] release #3124

Merged

HiDeoo mentioned this pull request Apr 16, 2025

i18n(fr): update guides/css-and-tailwind #3128

Merged

jsparkdev mentioned this pull request Apr 16, 2025

i18n(ko-KR): update css-and-tailwind.mdx #3129

Merged

trueberryless mentioned this pull request Apr 17, 2025

i18n(de): update guides/css-and-tailwind.mdx #3137

Merged

HiDeoo mentioned this pull request May 1, 2025

Cascade layer issues/feedbacks #3162

Closed

1 task

HiDeoo mentioned this pull request Jun 9, 2025

Update to Starlight 0.34.4 withastro/docs#11870

Merged

3 tasks

morinokami mentioned this pull request Feb 5, 2026

i18n(ja): update css-and-tailwind.mdx #3694

Merged

Uh oh!

Conversation

HiDeoo commented Sep 11, 2024 • edited by delucis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Remaining tasks

Uh oh!

changeset-bot bot commented Sep 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Sep 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

astrobot-houston commented Sep 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

delucis commented Sep 11, 2024

Uh oh!

mayank99 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

HiDeoo commented Nov 22, 2024

Uh oh!

mayank99 commented Nov 22, 2024

Uh oh!

mayank99 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

delucis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

HiDeoo commented Sep 11, 2024 •

edited by delucis

Loading

changeset-bot bot commented Sep 11, 2024 •

edited

Loading

netlify bot commented Sep 11, 2024 •

edited

Loading

astrobot-houston commented Sep 11, 2024 •

edited

Loading

delucis left a comment •

edited

Loading