docs
docs copied to clipboard
withastro
Content audit for Accessibility guidance
Let's review our docs content for
- areas where it makes sense to mention (especially Astro-specific) tips for designing with a11y in mind.
- our code examples to make sure our own suggestions suggest good practices
- ... something else?
Building off of @Yan-Thomas's comments in Discord:
"We could sprinkle some accessibility tips and tricks in some pages, I think we can easily explain some of Astro's features using accessibility. For example, we can showcase how we can easily change an page lang atrribute using layouts and briefly explain why this is helpful. Also worth mentioning that UI framework-specific accessibility patterns should be the same (if the component is properly hydrated)."
We could also consider this in our MPA vs SPA comparison: one benefit of MPAs is not needing to rebuild the a11y structure around navigation (focus management, route change announcements, etc). I remember Marcy Sutton had to do HEAPS of work to make Gatsby more accessible out of the box and these concerns are just solved for you by the browser vendors when you choose an MPA.
Based on what I suggested before, Chris' comment, and some thoughts I had while reading the docs looking for things we could improve, I would tackle this like this:
Layouts + Pages
We know layouts are just Astro components, but I think people may think that there is some limitation, and we currently don't talk about using props to change bits of the page layout, this is a perfect opportunity to change our example to use props and show how we can use layouts to simplify internationalization. In the end, there would be a small tip (or note?) about the importance of the lang attribute for accessibility and how Astro makes this kind of stuff easy. In a bigger codebase, people will prefer to move this i18n logic to some route-checking script rather than manually adding a lang attribute, so I'm not sure if this example/use-case is good.
Also, in the Astro Pages' Page HTML section, we show a <html></html> without the lang attribute, I think it's worth adding these small a11y improvements to examples as a way to influence and prompt people to ask and search things like "why use the lang attribute?"
UI Frameworks
As mentioned before, I think we could add a small accessibility note at the end of "Hydrating Interactive Components" explaining that framework-specific accessibility patterns should be the same if the component is properly hydrated.
Static Assets
At "Other Assets" we have an image example without an alt attribute, I think we can simply add another comment like "Don't forget to add an alt tag to your images and leave it empty if it's just decorative!"
- [x] DONE 🥳
Why Astro
I would add a simple note that since Astro components are compiled to static HTML augmented by the use of UI frameworks, it allows for the use of common progressive enhancement and accessibility techniques without any overhead. I think this fits well at the end of the Easy to Use section.
MPA vs SPA
As Chris suggested, I think we can add a note at the end of the "Are MPAs Better than SPAs?" explaining that since Astro is an MPA we don't need any extra work announcing route changes and managing focus order, different from SPA frameworks.
- [x] DONE 🥳
Feel free to suggest any changes to my plan in how to tackle this, ideas of other changes are also welcome!
These all sound great, @Yan-Thomas! Let's put out a note to team-docs today about this issue, and invite people to submit PRs for these things!
Thanks so much for the detailed ideas @Yan-Thomas! I think I’ll take the MPA vs SPA note — maybe let’s also check in with Fred before making changes to “Why Astro” but please feel free for anyone to jump on those others!
Saw this labeled as good first issue so I hopped on it haha. Could I handle the note on Static assets if that's okay?
Saw this labeled as good first issue so I hopped on it haha. Could I handle the note on Static assets if that's okay?
Hi @Njong392 :wave:, sure. It's all yours! Thank you for tackling this :raised_hands: