wagtail
RFC 97: Alt Text Capabilities
View the rendered RFC with graphs
In its current state, Wagtail’s alt text functionality presents a significant accessibility challenge. Its approach to alt text relies heavily on the implementation of developers who use Wagtail, with the only default mechanism being that when alt text is not provided, the title of the image is used as the alt text. The problem with this is that image titles are also defaulted to what the file is saved as, and site editors are not mandated to change the titles from this default. Research by Wagtail’s accessibility team has shown that many sites have not attempted to customize the alt text mechanism, instead, relying on the default to file names. Much too often, this leads to a very poor experience for screen-reader users.
Additionally, the developers who create their own ways of enforcing alt text do so in a way that does not allow alt text to be tailored to the context in which the image is used. This is likely due to a general lack of awareness of the value that contextual alt text provides to users. Therefore with images in Wagtail, we have a lot of sites not adhering to Web Accessibility Standards, despite the developers behind them thinking otherwise.
This RFC proposes a solution to improve the overall accessibility of Wagtail sites by expanding the alt text capabilities provided out of the box, thereby enforcing good practices. It approaches this by adding supported mechanisms for handling alt texts in their most common use-case scenarios; such as in StreamField Image blocks, StructBlocks, and by providing helpful image descriptions in the AbstractImage model.
Achieving these objectives, will by extension, provide a way for contextual alt text to be supported for images, especially when they appear in more than one place in a Wagtail website.
Thank you @Chiemezuo - I had a read and cannot see anything I would like to add. Thank you so much for putting this together.
It may be good to work through whether this RFC replaces the other similar RFC https://github.com/wagtail/rfcs/pull/51
@lb- Yes, it does replace RFC #51 Although they have a similar goal, the approaches are quite different, and there have been a lot of changes to Wagtail since then. My mentors and I felt a new RFC might be better.
Thanks @Chiemezuo I think that makes sense, can you please update the RFC with a link to the other one and a note about this one superseding that one. Additionally, a comment on the other RFC.
Amazing work here, excited to see this be outworked.
One nice-to-have feature that isn't mentioned here is the ability to switch an existing ImageChooserBlock to an ImageBlock and have it just work with no additional data migrations. I think this should be achievable quite easily by patching ImageBlock.to_python (or possibly normalize, or both) to check if the incoming value is an integer - which would mean that it's receiving data that previously belonged to an ImageChooserBlock - and handle that by looking up the image with that ID, along with its default alt text.
Regarding fallback - I think a fallback is needed to support existing sites.
- Add new alt text field to Image model.
- Use a getter method to generate the alt text - first on alt text field, then on title.
- The advantage of the getter method is that the dev can override it if necessary to fit their site.
- Add accessibility warning to the image edit view if the alt text is empty.
Hey @vsalvino, I think I can answer your above points.
We're planning to write upgrade considerations explaining how existing sites can make use of the image_description field by doing a data migration from a custom alt text field (a common custom implementation we've seen) to the new image_description field. This data migration is something developers have to write and run themselves.
Use a getter method to generate the alt text - first on alt text field, then on title. The advantage of the getter method is that the dev can override it if necessary to fit their site.
We explicitly don't want to fallback to the title as it is often a garbage filename and something we very much want to move away from as a default in Wagtail. Yes, this is breaking change, but one we believe needs to be made.
If one does want to retain the implicit title-as-alt-text implementation as fallback, I would suggest overriding AbstractImage's default_alt_text method which - while not explicitly documented - is often already used to implement custom alt text. I suppose this would function as the getter you are describing. Perhaps we should considering documenting it as a workaround to restore the old behavior, though we don't really want to encourage this for the above reason.
Add accessibility warning to the image edit view if the alt text is empty.
Yep! This is already on our radar as part of the implementation 👍
Do you feel this addresses your concerns?
Thanks, definitely document default_alt_text as part of the upgrade considerations!
My perspective - almost all sites are using the stock Image model. And most sites have thousands or tens of thousands of images. So if we make the upgrade difficult on them in the name of accessibility, they will simply never upgrade. We definitely need to provide specific upgrade instructions for sites that currently have NO alt-text.
Thanks for the reply @vsalvino. Discussion about this is good, though I'm not sure I fully understand your perspective and concern.
The data migration I mentioned (and that you appear to be perceiving as something that would impede upgrading?) would only be recommended (but not mandated) for sites using a custom image model with an alt text field. The intent of this recommendation being they can transfer any alt text they already have for existing images and adopt the new Wagtail defaults over their own custom implementation.
Developers of a site using the stock image model ('sites that have no alt text') won't have to perform any upgrade steps at all. We're not requiring the image description for existing images be filled during the upgrade if that part is unclear.
The resulting change in behavior will be that instead of images being rendered with a garbage filename alt attribute there won't be an alt attribute at all. If a visualization helps, this is what the HTML diff would look like.
-<img source="DSC_01234.jpeg" alt="DSC_01234.jpeg">
+<img source="DSC_01234.jpeg">
To reiterate the reason behind this (in different words): we consider no alt text to be equivalent to bad alt text.
The difference being that missing alt text is easier for accessibility checker tools to flag. I don't feel this will be a behavioral change that non-accessibility focused developers would really care about.
For anyone interested in this, we had internal discussions about the proposal and have devised changes to respond to my feedback. @Chiemezuo will update the RFC, I’d recommend holding off from further reviews in the meantime.
Hi, for us it is very important that we can set an alt text per image in the imaging library. For example: "Voedselbosbouw team", "Voedselbosbouw logo", "portrait of Kaat", "people planting trees". And in Dutch as well, so this would probably need to be multi-lingual.
We have no need of changing alt texts based on the page the image is shown, "people planting trees" would still be a good description for us.
[updated comment for clarification]
Hi, for us it is very important that we can set an alt text per image in the imaging library. For example: "Voedselbosbouw team", "Voedselbosbouw logo", "portrait of Kaat", "people planting trees". And in Dutch as well, so this would probably need to be multi-lingual.
We have no need of changing descriptions based on the page the image is shown, "people planting trees" would still be a good description for us.
Hi @wimfeijen
Image descriptions will not change across pages or in situations where the image is used multiple times on the same page. They will remain fixed. That's where the new ImageBlock comes in. It'll allow you set alt text per image (even when the same image is used multiple times).
For example, say I have image "🖼️", and I have pages "1️⃣" and "2️⃣". At the point of uploading the image, the description will be set, and it will be fixed. The image 🖼️ can be used in pages 1️⃣ and 2️⃣. In both pages, it will have the same description, but the alt texts will be treated as unique. This is also the same behaviour for when the same image is used multiple times on the same page.
Marking this as Final Comment Period as we now have two approvals from the core team (me and Storm). Even at this stage I’d feel more comfortable if we got more feedback / explicit approval on this. If anyone is interested do feel free to comment, and we can delay merging of the RFC as needed.
Thank you @lb- for the final review 😌. With no further feedback, looks like it’s time to merge this. Nice one @Chiemezuo! 🚀