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.

[ericfennis]

Sorry for the late review.
This is such an awesome guide, thank you @karsa-mistmere super useful!
We can improve this even more if we add some small code examples for some things to make it visible in the code.

I've provided some suggestions and one comment

[ericfennis]

Suggested change

	#### In code
	```tsx
	// Don't do this
	<button>
	<Plus aria-label="Plus icon"/>
	Add document
	</button>
	// Do this, just leave it
	<button>
	<Plus />
	Add document
	</button>

[karsa-mistmere]

@ericfennis: These could be useful, but they break up the guide quite a bit, I've hidden them within details elements.

[ericfennis]

Suggested change

	#### In code
	```tsx
	// Don't do this
	<button>
	<Home />
	</button>
	// Do this
	<button aria-label="Go to home">
	<Plus />
	</button>

[ericfennis]

Can you explain why we should be "against" this? It would be nice if we explained this more in the text, about why using "visually hidden" is better than using aria-label, we also could provide some sources for blog posts or documentation to prove our "recommendation".

Also maybe this reads a bit nicer

Suggested change

	generally recommend against this for and instead suggest that
	you [use your chosen CSS framework's "visually hidden" utility whenever possible](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/).
	generally recommend visually hiding textual descriptions. For example by [using utility CSS framework's "visually hidden"](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/).

[karsa-mistmere]

That means something different though. Also, the link itself is the resource that explains why .visually-hidden > [aria-label], I've rephrased the link text so that it's clearer.

Suggested change

	generally recommend against this for and instead suggest that
	you [use your chosen CSS framework's "visually hidden" utility whenever possible](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/).
	generally recommend against this and instead suggest that you use your chosen CSS framework's "visually hidden" utility whenever possible. You can [read more about why `aria-label` might not be the best solution](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/).