Docs blockquotes accessiblitly concerns

[Nicolaos Skimas]

<blockquotes> are being used throughout the docs to provide call out notes. There are a number of them, but here are a couple for the sake of example.

• the note about converting style-dictionary files on the getting started page
• the note about file extensions on the config api reference page

There are two accessibility issues with the current implementation.

Contrast

The white text on the light blue background is really not perceivable. I'm measuring a contrast ratio of 1.16:1, but text that size should be at least 4.5:1. This is a major issue for any sighted user. It looks like the background color is set in styles/_md.scss. I'm not a designer and don't really have a preference as to how this gets solved, but one easy way to do it would be using a darker blue for the background color. blue-50 gets us up to 6.26:1 with the body text, but still leaves links below the threshold at 3.31:1.

Semantics

While not as big of an issue as the first, the second is the misuse of the <blockquote> element for styling purposes. This is unfortunately pretty common in docs sites, but <blockquotes> should only be used if the enclosed text is actually a quotation. Better options here would be to either use the <aside> element or the note role (and probably move the related styling to a class). i realize markdown doesn't have a built in method for either of those approaches like the way a > lets you add a <blockquote>, but it should be possible to write the correct HTML directly inside the markdown file.

[Drew Powers]

Thank you for taking the time to suggest all these fixes! Will make all the suggested changes to improve a11y for the docs.

This is unfortunately pretty common in docs sites, but <blockquotes> should only be used if the enclosed text is actually a quotation.

This is an unfortunate side-effect of markdown. Most docs are written in markdown because they’re friendlier for contributors to edit. There is really no other way to style a callout with markdown-generated content besides blockquote, other than writing your own HTML. Which, if your docs are in HTML, they are not in markdown, and thus introduce more friction to contribution. It’s tough! What is “accessible” to users is also counterintuitively less usable for contributors :(. But will fix nonetheless.

[Nicolaos Skimas]

Most docs are written in markdown because they’re friendlier for contributors to edit. There is really no other way to style a callout with markdown-generated content besides blockquote, other than writing your own HTML. Which, if your docs are in HTML, they are not in markdown, and thus introduce more friction to contribution. It’s tough! What is “accessible” to users is also counterintuitively less usable for contributors :(. But will fix nonetheless.

Yeah, I totally get it. I publish a small blog and its been frustrating because Markdown is so nice to write, but it has just enough things missing that I usually have to write HTML as well. MDX can help bridge that gap, but then you're also taking on a lot thicker dependency and maintenance stack.

Thanks for be willing to prioritize end user experience and accessibility over developer experience.