Improvements for screen readers

[aomarks]

Did a pass through the home page and docs with voiceover on Safari.

• Disabled reading of decorative images.

• Added labels for some images that were missing them.

• Switched code snippets to <figure> elements. If there's a <figcaption>, as we now have on the homepage, it reads it nicely, otherwise it seems to read the same. Maybe we can add captions to our other code snippets if we have time. I think it should help with navigation though, (i.e. "skip this figure" command, vs a div where there's no semantic encapsulation).

Fixes #158

[github-actions]

A live preview of this PR will be available at the URL(s) below.
The latest URL will be appended to this comment on each push.
Each build usually takes around 7 minutes, and will 404 until finished.

https://pr205-3a1468e---lit-dev-bvxw3ycs6q-uw.a.run.app/

[justinfagnani]

Should we allow both a heading and caption? The heading would be the title of the example, and the caption could be equivalent to the alt-text with longer content?

It looks like headings in figures are excluded from the outline algorithms (which screen readers might sort-of follow? afaik, nothing really implemented the HTML outline algorithm correctly) so I'm not sure if the heading should be inside or before the figure in that case.

[aomarks]

Yeah interesting, I guess we could put "Code example" in the <figcaption>, render if off screen somewhere so that it's not shown visually but still reads to screenreaders, and then keep the "Hello World" in a heading? Will play around with that for a followup.

[arthurevans]

For the most part, we don't have titles on our examples. Occasionally, we have a filename attached to an example.

Generally the code example is described in the accompanying text. We use alt-text to describe stuff that the screen reader can't read, but it can read the code example. I think the caption "Code example" gives the information that's conveyed by formatting to the sighted reader.

(I don't know how you'd do this, but an additional cool perk would be if we could provide an optional title/filename that gets integrated into the figcaption. i.e., so looking at the page you see "my-element.js" above the example, but the screen reader would say, "Code example: my-element.js")

I wouldn't spent more than about 10 minutes thinking about that, though. I think "Code example" is good. With the obvious caveat, I Am Not An A11y Expert.