RFC: Contextual alt text

[gasman]

Wagtail's default image model does not currently provide an alt text field - the title is used instead. Wagtail could add a dedicated alt text field (and developers often do so on custom image models); however, ideally alt text should be tailored to the context where the image is being used - for example, a gallery implemented with an InlinePanel would make the alt text a property of the GalleryItem model - and adding a field at the image level would interfere with this 'ideal' approach. Unfortunately, since both approaches require up-front effort on the part of the developer, it's common for neither one to be implemented. We therefore seek a solution for context-aware alt text that is as frictionless as possible for both developers and editors. This RFC proposes a solution for this within StreamField image blocks.

[kaedroho]

For this, and https://github.com/wagtail/rfcs/pull/66, how do you feel about making it easier to use non-streamblocks in streamfields?

For example we could use these blocks as regular database fields by wrapping them with StreamField()

class MyPage(Page):
    image = StreamField(ImageChooserBlock())
    link = StreamField(LinkBlock())

Both would store the data in JSON though. But would have the same UI as the streamfield version

---

Crazy idea, maybe we could somehow allow people to use struct blocks on page models and these get converted into database fields?

so:

class MyPage(Page):
    image = ImageChooserBlock()

Expands the structblock into actual fields like so:

class MyPage(Page):
    image_image = models.ForeignKey()
    image_alt = models.CharField()

    image = an accessor that gets/sets these fields with a struct value

[Stormheg]

Thanks for putting this RFC together Matt! Contextual alt text is a great step in the right direction for accessibility 👍

From the discussion in https://github.com/wagtail/wagtail/issues/6034, I understand that a dedicated alt text field is often added using a custom image model. You've explained why we don't have this field in core Wagtail and why contextual alt text is preferred pretty well in your comment.

contextual_alt_text mechanism

We add a contextual_alt_text attribute (as opposed to a model field) to the Image model, and have Rendition's alt property pick up alt text from there when defined, in preference to the image's default_alt_text property (which returns the title, or can be overridden on custom image models to a more appropriate field). With this in place, any mechanism within Wagtail that would ordinarily return an Image instance (e.g. ImageChooserBlock) can set contextual_alt_text to a context-specific string so that it will be used as alt text at the point of rendering the image - without the template author having to explicitly handle alt text, and without any database-level changes to the image.

With the contextual_alt_text mechanism in place we can have both 'generic' alt text and context specific alt text without too much friction for developers. I like this approach! ❤️ Should we reconsider adding a dedicated alt field on the Image model with this mechanism in place?

Decorative images One thing I'd consider is the ability to explicitly mark an image as decorative as Helen and Thibaud have done for rich text images: https://github.com/wagtail/wagtail/pull/6730. A checkbox that disables the contextual alt field when checked sounds like the way to go or would that get too clunky? Thoughts?

Auto-populating contextual alt As for auto-populating the contextual alt text, I'm not sure that is desirable. I feel like it is fine to leave this field empty, in which case the 'generic' alt text from default_alt_text is used. We could make the default_alt_text visible somewhere on the block so the editor can consider whether context-specific alt text is needed but I'm afraid that makes for a clunky interface.

Naming conventions I'm not super keen on the naming of ImageBlock and ImageChooserBlock. It is not immediately apparent what the difference is from an outsider's perspective. Could we perhaps rename the proposed ImageBlock to ImageAltChooserBlock?

Alternatively (not sure how feasible it is), would it be possible to keep the ImageChooserBlock and have the contextual alt text features be enabled/disabled with a keyword argument? E.g. image = ImageChooserBlock(contextual_alt=True). Disabling alt text features would be useful if the image is always used decoratively in the template. For example, as background image.

Keen to hear what others think!

[gasman]

Could we perhaps rename the proposed ImageBlock to ImageAltChooserBlock?

The rationale for calling it ImageBlock is that we want to steer developers towards it as the default option whether or not they're actively aware of accessibility issues. We don't want them to go "this is an image chooser with Some Weird Option I Don't Understand. I think I'll stick with the normal image chooser."

ImageChooserBlock with a keyword argument (defaulting to alt text enabled) would solve that, but I don't think it adequately communicates that ImageChooserBlock(contextual_alt=True) and ImageChooserBlock(contextual_alt=False) have completely different data representations.

I expect that once we introduce ImageBlock, we'll downplay the existence of ImageChooserBlock in the documentation so that only 'advanced' developers will need to understand the distinction.

[lacymorrow]

Have to say that we are very excited for an ImageBlock that supports alt-text. I know we're still in the early comments stage, but I'm interested in getting an idea of when this would be supported officially.

I think ImageBlock is perfectly acceptable as a name.

As for:

Decorative images One thing I'd consider is the ability to explicitly mark an image as decorative as Helen and Thibaud have done for rich text images: wagtail/wagtail#6730. A checkbox that disables the contextual alt field when checked sounds like the way to go or would that get too clunky? Thoughts?

Personally I'd think that any developer who knew about marking images as decorative would also be aware that an empty alt-text would suffice. I'd imagine leaving the field empty would be the default when using this block, but then-again, maybe being explicit would help folks stay more accessible.

Any idea how long this will take to be supported?

[kbayliss]

A few of the @wagtail/accessibility team, along with others, met to discuss this last week with the hope of reviving this thread and nudging us closer towards improving this in Wagtail.

We discussed a few options:

1. Adding an optional alt text field to the Image model and updating default_alt_text() to return self.alt_text or self.title.
2. Adding an optional alt text field to image implementations within StreamFields (example), plus guidance for how developers should implement this when adding using Images within models (outside of StreamFields).
3. A combination of the above, along with the ability to override the alt text defined on the Image model with instance-specific alt text which is contextual, plus the ability to mark the image as decorative (and therefore be ignored by assistive tech).

We concluded that option three provides the most flexibility and is a sensible foundation to add to Wagtail, though we'd like more opinions on this before committing to the approach.

In particular, we'd love to investigate this suggestion from @kaedroho about reducing the burden on developers when using images within models. Currently a developer only has to add one field (a FK to the Image model), and asking them to instead add three fields:

1. a FK to the Image model
2. a field to override the alt text
3. a field to choose whether the default or overridden alt text should be used or if the image is decorative

...is a significant change that will likely be inconsisntely implemented. We'd like a more reliable/robust way of doing this - e.g. adding a single field as per @kaedroho's suggestion.

Thoughts?

[gasman]

I think it's possible in Django to construct field types that appear as a single field in the model definition but translate to multiple fields at the database level, but that would need more research. (I thought GenericForeignKey did this, but apparently not...). I'd definitely prefer that to a JSON / StreamField representation, both for the added referential integrity of having a proper FK, and for avoiding a Wagtail-specific solution that departs from the 'natural' DB representation.

[wimfeijen]

Hi all,

Thanks for adding alt texts in Wagtail!

In our case, we are dealing with a lot of (inexperienced) web editors. An image library with just one alt text per image (insensitive of context) would be entirely appropriate and suffice. It is the same approach WordPress uses.

So option 1 would already be enough.

Thanks!

Wim

[thibaudcolas]

@wimfeijen Hi Wim, isn’t this something that’s already possible? It feels to me like you could just add the field to a custom image model.

From our perspective this isn’t good enough, and we wouldn’t recommend this option for any site. Without knowing in what context an image is used in, it’s hard for editors to judge whether the alt text is appropriate or not. Without any way to explicitly mark an image as decorative, it’s even harder for inexperienced web editors to make the judgement call to leave an optional alt text field empty.

[Stormheg]

Hi all, I'd like to report that there is renewed interest in this RFC from the accessibility team. See the accessibility team meeting notes from the 22nd of December, 2023.

I'm still catching up on everything that has been said on this RFC and in other issues over the past years. It is my intention to revive this RFC and make a more accessible default image model happen in 2024.

(cc'ing @SaptakS as he has expressed interest in helping out)

[Stormheg]

There is now a working group working on this. Come find us in the #a11y-image-model-working-group channel on Slack!

[thibaudcolas]

Based on our recent ATAG audit, here are ATAG requirements pertaining to alt text.

• Alt text in the CMS user interface: A.2.1. (For the authoring tool user interface) Make alternative content available to authors
  • This is interesting as it highlights the need for alt text for screen reader users within the CMS.
  • Here’s my evaluation of A.2.1.1. in particular.
  • TL;DR; recommendation: Consider whether to sign-post the Title field as the image’s alt text in the CMS, or add another mandatory "default alt text" to the image model, which can be used as alt text whenever images are rendered in the CMS, and potentially also in the frontend (with clear options to mark images as decorative or define alt text in context)
• B.2.3.1 Alternative Content is Editable (WCAG)
  • My evaluation: Fail – Though Wagtail provides support for editing alt text everywhere images can be added, it doesn’t provide support for marking images as decorative (set to empty alt text), or changing alt text in context.
• B.2.3.3 Save for Reuse
  • My evaluation: Fail – By default, Wagtail saves each image’s text alternative and reuses it everywhere the image is reused ("Save and Suggest"). It is possible to replace this text alternative with a new one, but it isn’t possible to delete it.

Additionally – per ATAG, all of this needs to be documented, either in docs or in the CMS. And I’d also recommend looking at the results of the We4Author Cluster project for text alternatives.

Based on all of this, my "ideal scenario" if I could redesign this all from scratch would be:

1. A mandatory "alt text" field at the level of the image model. It has to be mandatory so images can be described for screen reader users within the CMS. If that’s not possible, it could also be the "Title" field with help text to explain its role as alt text, plus possibly a description field which if set would be used instead of "Title".
2. Wherever images can be selected, a mechanism to set alt text in context, or set alt text to "empty" for decorative images.
3. Optionally (AAA requirement) – a mechanism to save those in-context text alternatives for reuse in other places where the same image is reused.

[wimfeijen]

Hi @thibaudcolas,

Thanks for looking into this!

Your ideal scenario sounds very nice.

1. If a mandatory alt text is added, it could be prefilled based on title.
2. This setting in context is optional, right? So most of the times, we can use the default alt text from above.
3. For me, either use the default or edit it by hand would suffice.

Best regards,

[thibaudcolas]

@wimfeijen in my mind, in this ideal world where there is a separate mandatory alt text field, pre-filling from the title doesn’t sound right – as title itself is pre-filled from the file name on upload. The point of having a separate field be mandatory is so people make some effort to write it right. Or if they don’t want to – they can copy-paste the contents of the title field themselves.

And yes, setting in context would be optional. I’d assume we could default the alt text field to use what has been defined centrally, and provide help text to explain that "Set a different alt text to better describe the image in context", and a separate "mark image as decorative" checkbox.

[thibaudcolas]

Link to meeting notes from our accessible image model working group.

[Chiemezuo]

As per the discussions for the GSoC '24 project on alt text capabilities, this RFC has been modified in RFC #97.

[thibaudcolas]

Closing in favour of #97. We could use more feedback there if anyone who’s read this RFC has the chance to take a look :)