Adds custom styles for <details> and <summary> elements in Markdown content

[HiDeoo]

What kind of changes does this PR include?

• Changes or translations of Starlight docs site content
• Changes to Starlight code

Description

This PR adds custom styles for <details> and <summary> elements in Markdown content, adresssing the request in the built-in components discussion.

Preview playground page: https://starlight-git-fork-hideoo-hd-style-details-astrodotbuild.vercel.app/reference/details/

The approach used does not add a new <Details> component but relies on the native <details> and <summary> HTML elements, similar to the Docusaurus approach.

The current design is based on the Astro Docs custom implementation but the implementation is not exactly identical as I noticed a few minor issues while implementing it (some margins inconsistencies and some border being offset by 1px when toggling the details).
This PR also adds support for RTL languages, prefers-reduced-motion and some minor color adjustments to match the Starlight theme.

One point to note is also the usage of <details> in asides, where the styling deviates from Astro Docs as it can lead to some readability issues. I implemented custom variations to address this, but I don't think it looks the best as I did not introduce any new color (which may be needed to make it more appealing) and I'm also not the best when it comes to design decisions.

I reviewed the accessibility of the implementation using this checklist and testing with screen readers but relying on the native elements ensures most of the concerns are addressed out of the box.

Any feedback is welcome!

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	May 17, 2024 4:45pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 535328d

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

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

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

[HiDeoo]

Following a Talking and Doc'ing session (April 11, 2024), some very interesting feedback was received from the participants, thank you all for your time and feedback!

One particular piece of feedback from @kevinzunigacuellar was that it may be difficult to follow if a user is still in a <details> or not , specially in nested <details>. Discussions about this included the idea of adding some borders to the <details> to make it more clear. Here are some screenshots of me playing around with the idea, nothing is final of course and the goal is just to discuss the idea.

Borders around all <details>

Personal opinion: I think this adds a lot of visual noise and importance to the <details>.

Borders only around nested <details>

Slightly dimmed borders around nested <details>

[HiDeoo]

Sharing here another great approach to the design by @delucis

The preview is available here: https://starlight-git-chris-details-dabbling-astrodotbuild.vercel.app/reference/details/

An early feedback for this variation is that it may be less obvious that these are clickable without a more involved CTA compared for example to a Google variation:

[HiDeoo]

I updated the PR to use Chris's design. I personally prefer it but as it's now part of the history, we can easily switch between the two if ever needed. My main remaining concern may be the visibility of the left border in light mode.

In a separate commit, I also added a suggestion from Sarah to move the marker to the left to emphasize that these are clickable which was one of the main feedback from the previous post. Same, this can be easily reverted now during iterations.

[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/authoring-content.md	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.

[HiDeoo]

Updated the PR and tweaked border colors: the <details> border color is now more "vivid" compared to the one from a blockquote or a <Steps> component to emphasize that it's an interactive element. Hovering and the opened state borders are also more "vivid" now to match this change.

Hovering an opened <details> element will now also change the border color to a different color to still indicate that it's clickable.

And finally, I fixed a marker position issue with long summaries due to MDX wrapping the summary in a <p> tag.

[delucis]

Thanks again for the work on this @HiDeoo!

I’ll summarise again the couple of changes that we discussed and I pushed directly:

• border is now 2px instead of 1px, matching the <Tabs> component thickness
• hover styling only applies when hovering <summary> on expanded <details> — this helps avoid a slightly chaotic/flickering feeling with the border colour changing rapidly as users move over details
• hover colour is now a more bold accent like <Tabs> uses for selected tabs

Other than that I think we’re more or less there! I left a couple of notes on the docs and some CSS, but then I think we should be good to clean up the test page.

We’ll probably also need to bump up the CSS size-limit budget.

[sarah11918]

Approving for docs!

[delucis]

Thank you for working through the different iterations and rolling with the changes I kept throwing at you @HiDeoo! 🎉

It will be nice to see these updated and in-use in Astro’s docs soon too.