Feat/add accessibility statement

[markteekman]

Description

Related to the Add Accessibility Statemement (#3616) discussion 🙂

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9c9beca

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	9c9beca
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/695520d7edc62e00081604d4
😎 Deploy Preview	https://deploy-preview-3638--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 project 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	accessibility-statement.md	Source added, will be tracked.

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]

Thanks for getting the ball rolling on this @markteekman! I’m off for a few weeks but looking forward to getting a proper review in when I’m back 💖

[Menelion]

@markteekman I'm absolutely not familiar with your project, just monitoring the #Accessibility hashtag on Mastodon and saw @delucis 's post there. You add an accessibility statement which is good, but did you actually test for accessibility? Like, did you ask blind/low-vision/low-mobility users to verify? I'm asking because I'm blind myself and it's beyond frustrating when you see an accessibility statement and yet the solution is far from being accessible (the most prominent case was with Atlassian, where they stated to support WCAG AA level for poorly accessible Jira and Confluence). Thanks.

[markteekman]

Thanks for getting the ball rolling on this @markteekman! I’m off for a few weeks but looking forward to getting a proper review in when I’m back 💖

Sounds good @delucis! Enjoy your time off 😊

[markteekman]

@markteekman I'm absolutely not familiar with your project, just monitoring the #Accessibility hashtag on Mastodon and saw @delucis 's post there. You add an accessibility statement which is good, but did you actually test for accessibility? Like, did you ask blind/low-vision/low-mobility users to verify? I'm asking because I'm blind myself and it's beyond frustrating when you see an accessibility statement and yet the solution is far from being accessible (the most prominent case was with Atlassian, where they stated to support WCAG AA level for poorly accessible Jira and Confluence). Thanks.

Hey @Menelion! To be frank, no, I haven't tested accessibility with real users, especially people with disabilities. 🤔 I agree that such testing is essential for improving a website's accessibility. I don't have direct access to a testing group, I only have my own expertise. I've worked as a front-end developer for 17 years and have built accessible solutions since 2018. I collaborated closely with a colleague who was an auditor and learned a lot from him, but I don't know everything. I consolidated my knowledge in Accessible Astro and hope to improve it through community feedback and ongoing learning 😄 I also performed an unofficial audit for the Starlight theme last year (#2693), which resulted in this PR about the accessibility statement. Again, that audit reflects my knowledge, not user testing. I'm always open to learning more and improving the overall user experience, so tips are always welcome! 🙏🏼

Edit: Also, I get that it must be very frustrating when organizations put up an accessibility statement whilst not being accessible at all.. 😅 That's exactly the kind of stuff we want to prevent here.

[delucis]

Thanks for chiming in @Menelion! I’m one of the lead maintainers of this project. Absolutely agreed that a statement on its own is not worth much. Starlight is an open-source website generator, focused primarily on technical documentation, and it’s important to us that we do everything we can to help make sure that the websites generated with our tool are as accessible as possible out of the box.

We consider accessibility in the UI design and for every feature we work on. Every code change is tested using an automated test suite (using axe-core) and we manually test on a range of browsers, operating systems, and screen readers. I also take it as a responsibility as a maintainer to research common patterns so that we’re starting from a good baseline.

We haven’t usually been able to do user testing, although we try to. For example, we are currently rebuilding the search UI, which is an area that was lacking in terms of accessibility, and were able to do some direct testing with a blind user to evaluate it. More of that would definitely be ideal, if not always possible for an open-source project like this. Sometimes we’ve had to adjust things retrospectively based on user feedback when early user testing wasn’t possible. (For example, Mark mentioned the audit he did, which resulted in several improvements.)

From my perspective, adding an accessibility statement is hopefully a way for us to reflect the values we already hold and have been trying to put into practice. I would also like to make sure people feel empowered to call out issues they encounter, knowing it’s something we care about and are happy to improve wherever we can.

[delucis]

@markteekman In case you’re interested, here’s the Mastodon thread where I asked for feedback from people, which already has a few nice ideas: https://m.webtoo.ls/@swithinbank/115808212064480692

[delucis]

Adding a quick summary of feedback I got from that Mastodon thread and in private messages, so I don’t lose them (thanks everyone who chimed in!):

• Including an e-mail address would be good for people without GH/Discord. (I can investigate what’s best here. Can maybe set up a Google Group address that maintainers would receive.)

• Some way to indicate known issues would be helpful. Rather than maintaining that in the statement, we could link to issues with the a11y label on GitHub.

• This repo has helpful links to relevant resources: https://github.com/accessibility/Accessibility-Statement

• The Web Accessibility Initiative provides a planning tool for statements: https://www.w3.org/WAI/planning/statements/

• It may be good to stick to the structure of the WAI generator (or even use it directly). Described to me as “straightforward, researched, already used by many others, and also avoids reinventing the wheel”.

  • A minimal generated example statement
  • A complete generated example statement

[markteekman]

Adding a quick summary of feedback I got from that Mastodon thread and in private messages, so I don’t lose them (thanks everyone who chimed in!):

* Including an e-mail address would be good for people without GH/Discord. (I can investigate what’s best here. Can maybe set up a Google Group address that maintainers would receive.)

* Some way to indicate known issues would be helpful. Rather than maintaining that in the statement, we could link to [issues with the a11y label](https://github.com/withastro/starlight/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22%F0%9F%A4%A9%20a11y%22) on GitHub.

* This repo has helpful links to relevant resources: https://github.com/accessibility/Accessibility-Statement

* The Web Accessibility Initiative provides a planning tool for statements: https://www.w3.org/WAI/planning/statements/

* It may be good to stick to the structure of the [WAI generator](https://www.w3.org/WAI/planning/statements/generator/#create) (or even use it directly). Described to me as “straightforward, researched, already used by many others, and also avoids reinventing the wheel”.
  
  * [A minimal generated example statement](https://www.w3.org/WAI/planning/statements/minimal-example/)
  * [A complete generated example statement](https://www.w3.org/WAI/planning/statements/complete-example/)

Those are excellent points @delucis! I agree that adding an email address makes it more approachable, and linking to the GitHub issues instead of a static list is a great improvement 👌🏼 I also like the suggestion of using the WAI-generated statement as a base. I’ll make some changes 🙂

[markteekman]

@delucis changed it up a bit. I restructured the content conform the WAI generator example (complete) and adjusted the wording as well. Added a placeholder email for now 😄 I'll sign up for Mastodon too, it might be interesting to see what's being shared about accessibility and web development 😊

[Menelion]

@delucis I won't promise anything, but I'll try to find some time in January to investigate your site. Website generators, especially accessible ones (especially open-source and accessible!) are something that is very rare on the Internet. I mean, there are plenty, but accessibility is, to put it the mildest, is not their strongest point. Thank you for caring, it really warms my heart. Happy new year to all of you!