supabase / supabase / 30132169033

74%

push

github

fix(docs) Improve a11y for Admonitions with file refactor (#48112)

Closes FE-3914


## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## Problem

On screenreader, I found that the Admonition was not behaving as it
should:
- There was no way on screenreader to tell what type of note I was
seeing
- I could not tell when a note began or ended.
- The screenreader also read aloud an 'image' icon without knowing what
it was.
- Notes with titles were an `h5`, breaking header hierarchy structures.

## Solution

This PR does several things to resolve the issue:
- Adds `aria-hidden` to all icons. Instead of duplicating code, I
refactored the icons into a Base Icon and moved Admonitions into its own
folder.
- ~Adds a text label for each of the notes. For example, "**Note:**".
This is a standard practice in other documentation. If there is a title,
it is added there. Otherwise, it's added to the description.~ Change
reverted from design feedback.
- ~Adds `role='note'` and `aria-label` to the Admonition. While
`<aside>` is recommended semantic HTML, the base UI element does not
allow for that change.~ This will be done in a follow-up for docs only.
- Refactors Admonition into a folder with files so that it is more
readable
- Removes `h5` by default with a new prop to declare a header

Additionally adjusts the icon so that it aligns with text better.

## Testing

1. Open documentation preview
2. Navigate to any guide and see its admonition. Compare to live. You
can also see the Design System:
https://design-system-git-a11y-docs-admonition-supabase.vercel.app/design-system/docs/fragments/admonition
3. See the icon position is in line with the text.
4. See the text label.
5. Use a screenreader like Voiceover on the admonition. Hear that it is
clearly defined.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary by CodeRabbit

- **New Features... (continued)

1238 of 1708 branches covered (72.48%)

Branch coverage included in aggregate %.

1842 of 2441 relevant lines covered (75.46%)

237.2 hits per line