feat(docs): added accessibility guide

[karsa-mistmere]

closes #2121

What is the purpose of this pull request?

• Documentation update

Before Submitting

• I've read the Contribution Guidelines.
• I've checked if there was an existing PR that solves the same issue.

[jguddas]

• The content of the images is not accessible, the alt text is different from the content of the image. I would generally prefer if we moved the text out of the images and made them just normal text.
• Would be nice to have a section on flashing images and use reduce motion as well
• Also aria-label is not perfect, using something like RadixUIs AccessibleIcon is something that we should point people to use instead.
• A section on who this for and why you should do this would also be nice.

[jguddas]

We can also point people to resources that they should reference, be it just the WCAG or even component libraries or guides like https://inclusive-components.design/toggle-button/

[karsa-mistmere]

• The content of the images is not accessible, the alt text is different from the content of the image. I would generally prefer if we moved the text out of the images and made them just normal text.

For the most part this is entirely intentional, these are illustrations, I've added accessible text where there was information otherwise missing, but most of these illustrations contain redundant information that is not useful to be read out as is. There's probably room for improvement, on that I can agree.

Would be nice to have a section on flashing images and use reduce motion as well

We don't really have ootb support for such animations, so I'm not entirely sure if it's relevant within the context of Lucide.

Also aria-label is not perfect, using something like RadixUIs AccessibleIcon is something that we should point people to use instead.

Well, the current guide does recommend not using it in places where it's problematic, but you're right, there probably space for some more nuance about this.

A section on who this for and why you should do this would also be nice.

Is it not for everyone using Lucide? 🧌

We can also point people to resources that they should reference, be it just the WCAG or even component libraries or guides like https://inclusive-components.design/toggle-button/

Great idea, we should definitely add a "Further resources" section!

[jguddas]

A section on who this for and why you should do this would also be nice.

Is it not for everyone using Lucide? 🧌

Example: Your should give your icons enough contrast so people with visual impairments, be it physical or just them being outside in the glaring sun can still get the amazing benefit of looking at those cute icons.

[jguddas]

Would be nice to have a section on flashing images and use reduce motion as well

We don't really have ootb support for such animations, so I'm not entirely sure if it's relevant within the context of Lucide.

Tailwind based example: You can do <DogIcon className="animate-ping" /> but what you should consider using <DogIcon className="motion-safe:animate-ping" /> instead.

[karsa-mistmere]

Would be nice to have a section on flashing images and use reduce motion as well

We don't really have ootb support for such animations, so I'm not entirely sure if it's relevant within the context of Lucide.

Tailwind based example: You can do <DogIcon className="animate-ping" /> but what you should consider using <DogIcon className="motion-safe:animate-ping" /> instead.

Yeah, but this is entirely dependant on Tailwind, I think it should be their responsibility to educate people about using their animations responsibly. :)

(To be frank, this should be their default, it shouldn't be something to opt into.)

[jguddas]

We could even set aria-hidden="true" on decorative icons like that.

[jguddas]

Did some actuall user research on this, having decortive images be read out as image by your screen reader is apperently super annoying.

So 👍 for adding aria-hidden="true".

[karsa-mistmere]

I'm a bit confused, does this mean that simple SVGs with no accessible text are currently being read out? 🤔

[jguddas]

The read-out text for voiceover for example is "You are currently on an image. To begin interacting with the contents of this image, press Control-Option-Shift-Down Arrow.", that's so super not helpful for decorative images.

[karsa-mistmere]

Oh jeez louise, that's awful. 🤮

+1 for adding aria-hidden then. Best course of action would actually be to automatically add that no matter what.

[jguddas]

Hiding the icon by default sounds super dangerous.

As I see it there are 2 okayish options:

1. Add a default label that is a descriptive representation of the icon. Set default `aria-label` or add `<title>` to SVG for accessibility #2121
2. Make setting a label / aria-hidden attribute mandatory and well documented for when to use what.

[karsa-mistmere]

1. Add a default label that is a descriptive representation of the icon. Set default `aria-label` or add `<title>` to SVG for accessibility #2121

Terrible-terrible idea, as I've already explained in #2121:

• Accessible labels on functional icons should describe the use case, not the graphical representation (and even that isn't necessarily unambiguous, especially considering abstract icons).
• Decorative icons on the other hand should have no accessible label whatsoever.

2. Make setting a label / aria-hidden attribute mandatory and well documented for when to use what.

Supporting any kind of accessible label would lead to breaking changes, since we cannot use either <title> nor aria-label="..." as already discussed in previous threads. That means we would have to add at least one extra element to the DOM and inject CSS where there previously were none (or use inline CSS for our visually-hidden util).

Hiding the icon by default sounds super dangerous.

I don't really see why, it is practically never advisable to set an accessible label on an icon itself, but instead on other interactive elements, or using some kind of visually-hidden/sr-only util class, but that by nature will be on a different element as well.