📖 Improve accessible figures with Jupyter docs

[choldgraf]

This adds some more information on how you can make Jupyter image outputs more accessible with alternative text by embedding them with image and figure directives. It also updates some of the labeling for the jupyter outputs to follow a type:label structure (like img:altair-horsepower instead of just altair-horsepower).

But does alt-text for images work for Jupyter outputs?

However I noticed that alt-text with a notebook image output doesn't seem to work properly. For example, if I do this to embed a matplotlib output:

![My alt text](#img:mpl)

Then the resulting alt text for the image is: <Figure size 640x480 with 1 Axes>. I suspect this is the default alt-text that you get from the notebook output. I would have expected the embed code to over-ride this.

Is this a bug? Or is it expected behavior, and we should recommend that people use {figure} instead of {image} to make notebook outputs accessible for screen readers?

[rowanc1]

We haven't considered alt-text for Jupyter outputs, as many of these can be interactive, tables, text, or other elements. I think that we could and should special case images and override the alt text in the case of a single image in an output. I don't know what we would do for other cases though? For figures, we are adding semantics of a figure > figcaption.

[rowanc1]

I am curious if this is related to this @choldgraf or the timing is just a coincidence?!

• Pre-proposal: standardize setting alt text from alt metadata in display_data jupyter/enhancement-proposals#120

[choldgraf]

Ah yeah that makes sense - so for now we should just recommend wrapping visual outputs in a figure in order to set alt text with the caption. Does that sound right? IMO that is a reasonable first step that gets us most of the way there without adding more complexity.

Your multiple images point is a good one - is that generally not a recommended practice? And if so not then perhaps we should warn against it in the docs as well. I can see how things could be confused if we did stuff like attach a label to a cell with multiple outputs.

For timing, I was partially inspired by a post I saw @willingc make online yesterday, and I wonder if this is the same thing that inspired @minrk - it certainly made accessibility top of kind and caused me to realize that you can already get close to this with MyST, so I wanted to document it!

[choldgraf]

@rowanc1 I've updated the PR to:

• Only recommend {figure} for now.
• Recommend and show a pattern for attaching one image output per cell.

LMK if this looks OK or merge if you like!

[tonyfast]

Ah yeah that makes sense - so for now we should just recommend wrapping visual outputs in a figure in order to set alt text with the caption. Does that sound right? IMO that is a reasonable first step that gets us most of the way there without adding more complexity.

the figure approach might not be the most ideal for images. figure semantics can be added to quite a few tags not just images, it is more of general catch all for labeling non-image things like qutoes, code blocks or poems. when AT users experience figure > img, the image is assigned the alt text of the figure caption if it does not have one already. this means that the alt text is read twice when AT users read a figure with a figcaption. if the caption is long then this is a labor intensive design choice for AT users who have to experience the alt text twice. the native solution for AT would be img tag with alt text, and the best verification would be to test with or include assistive technology users in these discussions.

Your multiple images point is a good one - is that generally not a recommended practice? And if so not then perhaps we should warn against it in the docs as well. I can see how things could be confused if we did stuff like attach a label to a cell with multiple outputs.

the assistive solution for multiple images or subplots would start with the area which includes alt text in regions of an image. if you're wrapping an entire region of outputs in in a figure then that makes sense. a figcaption with "display with 2 outputs for cell 4 in 9" would make sense, but then again, on AT, there are better solutions with groups roles. it really sounds like your figure directive is talking about a caption for the cell input rather than the output.