Add "Accessibility" table to Vaadin components

vaadin / docs

Official documentation for Vaadin and Hilla.

https://vaadin.com/docs

Other

29 stars 183 forks source link

Add "Accessibility" table to Vaadin components #865

Open web-padawan opened 2 years ago

web-padawan commented 2 years ago

Motivation

We need some easy way to communicate the state of accessibility support in Vaadin 22. Some inspiration can be found here https://github.com/vaadin/vaadin-grid/issues/1015#issuecomment-333854723

We can use emoji in docs to indicate screen reader support status, e.g.

✅ 　- full support, no issues identified
⚠️ 　- partial support , some known issues
❌ 　- not supported (component is broken)
⭕ 　- missing (screen reader feature is lacking).

Then we need to use *, ** etc with specific links to some known issues.

Example how we could make that for Checkbox and Checkbox Group:

Accessibility

Component	WCAG 2.1 AA	VoiceOver	JAWS	NVDA
Checkbox	✅	✅	✅	✅
Checkbox Group	✅	✅	✅	⚠️ *

NVDA does not announce required state for group elements.

web-padawan commented 2 years ago

@jouni @anezthes Do you have any recommendations on the design and where to place this content etc?

jouni commented 2 years ago

I would start with a standard Asciidoc table, just like we have here in this issue. Feels like it could be at the end of the page, after "Best Practices".

web-padawan commented 2 years ago

We can discuss this with a team and maybe it's something that we can work on unless there are many blockers 👍

jouni commented 1 year ago

Perhaps as the first step, we start with a single "Accessibility" page (probably under "Components”), which focuses on technical topics (rather than duplicating the content from vaadin.com/accessibility).

Some examples that come to my mind:

Emphasize importance of label / helper text for fields
Mention aria-label or tooltip for icon-only buttons

These pieces of advice are currently scattered across individual components pages in no particular order. The dedicated “Accessibility” page could maybe contain links to those, in addition to ARIA standards.

We do have some practical content around accessibility in the blog and YouTube. Those could be refactored to docs content or simply linked in there.

https://vaadin.com/blog/basic-tips-for-improving-accessibility + video
https://vaadin.com/blog/infographic-improve-accessibility-in-your-web-app
https://vaadin.com/blog/building-accessible-web-apps-with-vaadin
Rolf's webinars on A11Y (only part 3 is in YouTube?)

juuso-vaadin commented 1 year ago

Another thing that could be listed in such accessibility table are the known issues. These could be simply links to GitHub tickets or very short descriptions. We tend to use quite a bit of time to figure out if some a11y issue is already identified and prioritized.