Fix Safari VoiceOver issue

[HiDeoo]

Description

The change may look a bit weird at first but it looks like the number of Safari/VoiceOver issue with display: contents; is growing. A new "fun" one I just discovered seems to be related to a web component having display: contents; and a <script> element as a direct child which seems to make VoiceOver read the content of the <script> element.

This reproduces at least on macOS Sequoia 15.1 with Safari 18.1.

Here is a video before the fix…

before.mp4

Here is a video after the fix:

after.mp4

If this is accepted, maybe we could add a comment in the file frontmatter explaining why we have this attribute on a script element with a link to this PR and the videos?

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	8400bdf
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/6742ff3f5dc33d0008f22acc
😎 Deploy Preview	https://deploy-preview-2633--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.

[KonnorRogers]

I tested the current Starlight docs home page on MacOS 14.6 and found similar results:

VO + Safari 17.6 reads the script tag contents (unexpected)
VO + Chrome 131 / Firefox 132 correctly skip the script tag contents (expected)

[delucis]

Thanks for catching this @HiDeoo! Linking a WebKit bug I just reported based on this: https://bugs.webkit.org/show_bug.cgi?id=283645

Given the bug is CSS related I'm curious whether setting display: none on the script would also work to fix this. But I don't really mind what approach we use as long as we're not announcing code to people 😅

I shared this issue on Mastodon and got various responses including some recommending avoiding display: contents entirely. I understand that sentiment given the difficulty testing the full matrix of OS x browser x screen reader combinations and the apparent flakiness of support for display: contents, but in a handful of cases it's really really useful, so I think we can just proceed with caution and take extra care to test whenever we use it (and use it as a last resort).

[HiDeoo]

Given the bug is CSS related I'm curious whether setting display: none on the script would also work to fix this. But I don't really mind what approach we use as long as we're not announcing code to people 😅

The script already get that style from the user agent style sheet and I guess it's not enough in this case.

but in a handful of cases it's really really useful, so I think we can just proceed with caution and take extra care to test whenever we use it (and use it as a last resort).

That's also my opinion, especially in this one I think it's super useful, the bug is definitely not a common case and we don't overuse this value anyway.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8400bdf

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	Patch

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

[delucis]

Thanks for the fix! I also tested on Safari 18.1 on macOS 15.1 and confirmed both that the bug exists and that this PR fixes it.